Rejestracja transakcji

Ten przewodnik przeprowadzi Cię krok po kroku przez proces rejestracji transakcji za pomocą API dpay.pl. Wykorzystamy najprostszą metodę integracji - Simple Gateway (przekierowanie do bramki płatności).

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz:

Zweryfikowane konto w panel.dpay.pl (patrz Rejestracja)
Utworzony serwis płatniczy z nazwą serwisu i kluczem Hash (patrz Konfiguracja)

Schemat działania

Klient

Twój serwer

dpay.pl

Krok 1: Przygotowanie danych

Zbierz wymagane dane do zapytania:

Parametry wymagane

Pole	Typ	Opis	Przykład
`service`	string	Nazwa serwisu z panelu (alternatywnie `name`)	`"abc123"`
`transactionType`	string	Typ transakcji	`"transfers"`
`value`	string	Kwota (0-999999.99, z kropką dziesiętną)	`"29.99"`
`url_success`	string	URL po udanej płatności	`"https://mojsklep.pl/sukces"`
`url_fail`	string	URL po nieudanej płatności	`"https://mojsklep.pl/blad"`
`url_ipn`	string	URL do powiadomień IPN	`"https://mojsklep.pl/api/ipn"`
`checksum`	string	Suma kontrolna SHA-256	(patrz niżej)

Parametry opcjonalne

Pole	Typ	Opis
`channel`	string	Konkretny kanał płatności
`email`	string	Adres e-mail klienta
`client_name`	string	Imię klienta
`client_surname`	string	Nazwisko klienta
`blik_code`	string	Kod BLIK (dla płatności BLIK Level 0)
`description`	string	Opis transakcji
`custom`	string	Własne dane (np. ID zamówienia)
`products`	array	Lista produktów
`currency_code`	string	Kod waluty (np. `PLN`, `EUR`)
`phone_number`	string	Numer telefonu klienta

Typy transakcji

Typ	Opis
`transfers`	Przelewy bankowe (PBL)
`dcb_gateway`	Direct Carrier Billing
`card_auth`	Autoryzacja karty płatniczej
`mb_way_direct`	Płatność MB WAY

informacja

Typ transfers to domyślny typ dla prostego przekierowania do bramki płatności (Simple Gateway), gdzie klient sam wybiera metodę płatności.

Krok 2: Generowanie checksum

Checksum to suma kontrolna zapewniająca integralność danych. Generowana jest algorytmem SHA-256 z połączenia pól rozdzielonych znakiem |:

sha256({service}|{hash}|{value}|{url_success}|{url_fail}|{url_ipn})

Przykład w PHP

$service = 'abc123';
$hash = '9a8b7c6d5e4f3a2b1c0d';
$value = '29.99';
$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/blad';
$urlIpn = 'https://mojsklep.pl/api/ipn';

$checksum = hash('sha256',
    $service . '|' . $hash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

Przykład w JavaScript (Node.js)

const crypto = require('crypto');

const service = 'abc123';
const hash = '9a8b7c6d5e4f3a2b1c0d';
const value = '29.99';
const urlSuccess = 'https://mojsklep.pl/sukces';
const urlFail = 'https://mojsklep.pl/blad';
const urlIpn = 'https://mojsklep.pl/api/ipn';

const checksum = crypto
  .createHash('sha256')
  .update(`${service}|${hash}|${value}|${urlSuccess}|${urlFail}|${urlIpn}`)
  .digest('hex');

Przykład w Python

import hashlib

service = 'abc123'
hash_key = '9a8b7c6d5e4f3a2b1c0d'
value = '29.99'
url_success = 'https://mojsklep.pl/sukces'
url_fail = 'https://mojsklep.pl/blad'
url_ipn = 'https://mojsklep.pl/api/ipn'

data = f'{service}|{hash_key}|{value}|{url_success}|{url_fail}|{url_ipn}'
checksum = hashlib.sha256(data.encode('utf-8')).hexdigest()

Krok 3: Wysłanie zapytania do API

Wyślij zapytanie POST na endpoint rejestracji płatności:

POST https://api-payments.dpay.pl/api/v1_0/payments/register
Content-Type: application/json

Pełny przykład cURL

curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/register \
  -H "Content-Type: application/json" \
  -d '{
    "transactionType": "transfers",
    "service": "abc123",
    "value": "29.99",
    "url_success": "https://mojsklep.pl/sukces",
    "url_fail": "https://mojsklep.pl/blad",
    "url_ipn": "https://mojsklep.pl/api/ipn",
    "checksum": "e3b0c44298fc1c149afb..."
  }'

Przykład w PHP (cURL)

$payload = [
    'transactionType' => 'transfers',
    'service'         => $service,
    'value'           => $value,
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
];

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

Krok 4: Obsługa odpowiedzi

API dpay.pl zwraca odpowiedź w formacie JSON:

Odpowiedź sukcesu

{
  "error": false,
  "msg": "https://secure.dpay.pl/transfer@pay@A75AEBB4-4B89-4834-AD43-EF442C133769",
  "status": true,
  "transactionId": "A75AEBB4-4B89-4834-AD43-EF442C133769"
}

Pole	Typ	Opis
`error`	boolean	`false` jeśli zapytanie zostało przetworzone poprawnie
`msg`	string	URL bramki płatności - przekieruj klienta na ten adres
`status`	boolean	`true` przy sukcesie, `false` przy błędzie
`transactionId`	string	Unikalny identyfikator transakcji

Odpowiedź błędu transakcji (HTTP 200)

Zwracana np. przy nieprawidłowym kodzie BLIK lub anulowanej transakcji:

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "additionalInfo": {
    "error": "ER_WRONG_TICKET",
    "error_description": null
  }
}

Pole	Typ	Opis
`error`	boolean	`true` - wystąpił błąd
`msg`	string	Opis błędu
`status`	boolean	`false` - transakcja nie powiodła się
`transactionId`	string	Identyfikator transakcji
`additionalInfo`	object	Opcjonalne szczegóły błędu (np. kod błędu BLIK)

Błąd walidacji (HTTP 400)

Zwracany przy błędach po stronie merchanta (nieprawidłowy checksum, wyłączony kanał, nieprawidłowa kwota):

{
  "status": "failed",
  "message": "Payment registration failed",
  "errors": ["Invalid checksum"]
}

Pole	Typ	Opis
`status`	string	`"failed"`
`message`	string	Ogólny komunikat błędu
`errors`	array	Lista szczegółowych komunikatów błędów

Krok 5: Przekierowanie klienta

Po otrzymaniu odpowiedzi z polem error: false, przekieruj klienta na adres URL zawarty w polu msg:

PHP

if (!$result['error']) {
    // Zapisz transactionId w bazie danych
    saveTransaction($orderId, $result['transactionId']);

    // Przekieruj klienta do bramki płatności
    header('Location: ' . $result['msg']);
    exit;
} else {
    // Obsłuż błąd
    echo 'Błąd rejestracji płatności: ' . $result['msg'];
}

JavaScript (Express.js)

if (!result.error) {
  // Zapisz transactionId w bazie
  await saveTransaction(orderId, result.transactionId);

  // Przekieruj klienta
  res.redirect(result.msg);
} else {
  res.status(400).json({ error: result.msg });
}

Krok 6: Odbieranie IPN

Po zakończeniu płatności dpay.pl wyśle powiadomienie IPN na adres url_ipn. Szczegółowy opis obsługi IPN znajdziesz w przewodniku Obsługa IPN.

Pełny przykład - PHP

<?php
// Konfiguracja
$service = getenv('DPAY_SERVICE');
$hash = getenv('DPAY_HASH');

// Dane zamówienia
$value = '29.99';
$urlSuccess = 'https://mojsklep.pl/sukces';
$urlFail = 'https://mojsklep.pl/blad';
$urlIpn = 'https://mojsklep.pl/api/ipn';

// Generowanie checksum
$checksum = hash('sha256',
    $service . '|' . $hash . '|' . $value . '|' .
    $urlSuccess . '|' . $urlFail . '|' . $urlIpn
);

// Rejestracja płatności
$payload = json_encode([
    'transactionType' => 'transfers',
    'service'         => $service,
    'value'           => $value,
    'url_success'     => $urlSuccess,
    'url_fail'        => $urlFail,
    'url_ipn'         => $urlIpn,
    'checksum'        => $checksum,
]);

$ch = curl_init('https://api-payments.dpay.pl/api/v1_0/payments/register');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && !$result['error']) {
    // Przekieruj klienta do bramki
    header('Location: ' . $result['msg']);
    exit;
} else {
    http_response_code(500);
    echo 'Błąd: ' . ($result['msg'] ?? 'Nieznany błąd');
}

Najczęstsze błędy

Błąd	Przyczyna	Rozwiązanie
`Invalid checksum`	Nieprawidłowa suma kontrolna	Sprawdź kolejność pól i klucz Hash
`Service not found`	Nieznana nazwa serwisu	Sprawdź pole `service` w panelu
`Invalid value`	Nieprawidłowa kwota	Użyj formatu z kropką dziesiętną (np. `"29.99"`)
`Invalid URL`	Nieprawidłowy adres URL	Upewnij się, że adresy URL zaczynają się od `https://`

Co dalej?

Obsługa IPN - naucz się odbierać i weryfikować powiadomienia o płatności
BLIK Level 0 - zintegruj bezpośrednie płatności BLIK
Karty S2S - dodaj płatności kartowe Server-to-Server

Wymagania wstępne​

Schemat działania​

Krok 1: Przygotowanie danych​

Parametry wymagane​

Parametry opcjonalne​

Typy transakcji​

Krok 2: Generowanie checksum​

Przykład w PHP​

Przykład w JavaScript (Node.js)​

Przykład w Python​

Krok 3: Wysłanie zapytania do API​

Pełny przykład cURL​

Przykład w PHP (cURL)​

Krok 4: Obsługa odpowiedzi​

Odpowiedź sukcesu​

Odpowiedź błędu transakcji (HTTP 200)​

Błąd walidacji (HTTP 400)​

Krok 5: Przekierowanie klienta​

PHP​

JavaScript (Express.js)​

Krok 6: Odbieranie IPN​

Pełny przykład - PHP​

Najczęstsze błędy​

Co dalej?​