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

POST/api/v1_0/payments/registerPełny kontrakt rejestracji: parametry, checksum i kody błędów.Pełny kontrakt w API Reference

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.01-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 (patrz zależności niżej)
`email`	string	Adres e-mail klienta (wymagany, gdy podasz `channel`)
`client_name`	string	Imię klienta (wymagane, gdy podasz `channel`)
`client_surname`	string	Nazwisko klienta (wymagane, gdy podasz `channel`)
`accept_tos`	boolean	Potwierdzenie akceptacji regulaminu przez klienta (wymagane, gdy podasz `channel`)
`blik_code`	string	Kod BLIK - 6 cyfr (dla płatności BLIK Level 0), wymaga `user_ip` i `user_agent`
`blik_alias`	string	Alias BLIK OneClick (max 128 znaków, wymaga `user_ip` i `user_agent`)
`register_blik_alias`	object	Rejestracja aliasu BLIK OneClick (`label`, `type`) - wymaga `blik_code`, `user_ip`, `user_agent`
`register_blik_recurring_alias`	object	Rejestracja aliasu płatności cyklicznych BLIK (typ `PAYID`; m.in. `label`, `type`, `model`, `frequency`, limity kwotowe, daty ważności) - wymaga `blik_code`, `user_ip`, `user_agent`. Usługa włączana per serwis - patrz Płatności cykliczne BLIK
`register_card_recurring`	object	Rejestracja mandatu płatności cyklicznych kartą (`label` + opcjonalne `frequency`, limity, daty) - patrz Płatności cykliczne kartą
`card_recurring_alias`	string	Alias mandatu kartowego do obciążenia cyklicznego (max 128 znaków) - patrz Płatności cykliczne kartą
`authorize_only`	boolean	Pre-autoryzacja na zapisanym tokenie zamiast obciążenia (używane z `card_recurring_alias`) - patrz Płatności cykliczne kartą
`alias_ipn_url`	string	URL do powiadomień o zmianach statusu aliasu (max 500 znaków)
`no_delay`	boolean	Tylko płatności cykliczne BLIK: `false` pozwala operatorowi BLIK wstrzymać transakcję do 72 h w oczekiwaniu na potwierdzenie klienta w aplikacji. Domyślnie `true` (odpowiedź natychmiastowa). Wartość `false` wymaga włączenia opcji dla serwisu
`description`	string	Opis transakcji
`custom`	string	Własne dane (np. ID zamówienia)
`products`	array	Lista produktów
`payout`	object	Instrukcja wypłaty 1:1 - kierowanie środków na zweryfikowane konta merchanta (patrz Wypłaty 1:1). Wymaga włączenia opcji dla serwisu.
`currency_code`	string	Kod waluty (np. `PLN`, `EUR`). Wymagany, gdy podasz `phone_number`
`phone_number`	string	Numer telefonu klienta (9-15 znaków)
`billing_address`	object	Adres rozliczeniowy klienta (wykorzystywany m.in. przy płatnościach odroczonych)
`shipping_address`	object	Adres dostawy (wykorzystywany m.in. przy płatnościach odroczonych)
`device_info`	object	Dane urządzenia i przeglądarki klienta - wymagany dla `transactionType: mb_way_direct` (patrz niżej)
`user_ip`	string	Adres IP klienta - wymagany przy `blik_code`, `blik_alias` i płatnościach cyklicznych BLIK
`user_agent`	string	User agent przeglądarki klienta - wymagany przy `blik_code`, `blik_alias` i płatnościach cyklicznych BLIK
`nobanks`	0/1	Flaga kanałów: ukrycie przelewów bankowych na bramce
`paysafecard`	0/1	Flaga kanałów: Paysafecard
`creditcard`	0/1	Flaga kanałów: karty płatnicze
`paypal`	0/1	Flaga kanałów: PayPal
`blik`	0/1	Flaga kanałów: BLIK
`installment`	0/1	Flaga kanałów: raty

Zależności parametru `channel`

ostrzeżenie

Jeśli przekażesz channel, pola email, client_name, client_surname i accept_tos stają się wymagane - ich brak zakończy się błędem walidacji (HTTP 422).

Wartości tester, paypal, installment i paysafecard są niedozwolone jako channel.

Obiekt `device_info` (wymagany dla MB WAY)

Dla transactionType: mb_way_direct obiekt device_info jest wymagany wraz z polami: browserAcceptHeader, browserJavaEnabled (string "true"/"false"), browserLanguage, browserColorDepth, browserScreenHeight, browserScreenWidth, browserTZ (liczby), browserUserAgent, systemFamily, deviceID, applicationName, geoLocalization.

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
`blik_recurring`	Obciążenie cykliczne BLIK z zarejestrowanego aliasu `PAYID` (patrz Płatności cykliczne BLIK)
`card_recurring`	Obciążenie cykliczne kartą z zarejestrowanego mandatu (patrz Płatności cykliczne kartą)

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})

Normalizacja value

Serwer przed weryfikacją checksum normalizuje value do dwóch miejsc po przecinku (np. 10 staje się 10.00, 9.9 staje się 9.90). Jeśli wysyłasz kwotę w innym formacie, do checksum i tak musisz użyć wartości znormalizowanej - inaczej otrzymasz błąd Invalid checksum. Najprościej: zawsze wysyłaj value już sformatowane do dwóch miejsc.

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ź sukcesu bez URL bramki - "Internal processing" (HTTP 200)

Dla płatności przetwarzanych w tle bez przekierowania klienta (np. BLIK Level 0, BLIK OneClick, MB WAY) pole msg nie zawiera adresu URL, tylko stały tekst Internal processing:

{
  "error": false,
  "msg": "Internal processing",
  "status": true,
  "transactionId": "A75AEBB4-4B89-4834-AD43-EF442C133769"
}

Transakcja czeka na potwierdzenie (np. w aplikacji bankowej klienta). O wyniku dowiesz się z IPN lub odpytując o status transakcji.

Odpowiedź sukcesu - "Transaction paid" (HTTP 200)

Jeśli transakcja została opłacona już w trakcie przetwarzania zapytania (np. natychmiastowe obciążenie z aliasu), odpowiedź zawiera dodatkowo obiekt z danymi transakcji:

{
  "error": false,
  "msg": "Transaction paid",
  "status": true,
  "transactionId": "A75AEBB4-4B89-4834-AD43-EF442C133769",
  "additionalInfo": {
    "transaction": { "...": "dane 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 po stronie merchanta (HTTP 400)

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

{
  "status": "failed",
  "message": "Invalid checksum",
  "errors": {
    "checksum": "Invalid checksum"
  }
}

Pole	Typ	Opis
`status`	string	`"failed"`
`message`	string	Konkretny komunikat błędu (np. `"Invalid checksum"`, `"Amount is less than 0.01 PLN"`)
`errors`	object	Obiekt klucz → komunikat ze szczegółami błędów (np. `{"value": "Invalid value"}`)
`transactionId`	string	Opcjonalne. UUID transakcji, jeśli powstała przed błędem (np. odrzucone pobranie na zapisanej karcie) - możesz zapytać o jej szczegóły
`cardError`	object	Opcjonalne. Kod odmowy wystawcy karty (`code`, `declineCode`, `declineMessage`) - patrz Kody odmowy kartowej

Błąd walidacji pól (HTTP 422)

Braki lub złe formaty pól zapytania (np. brak url_success, zły format blik_code, brak email przy podanym channel) zwracane są ze statusem 422 w standardowym formacie:

{
  "message": "The url_success field is required.",
  "errors": {
    "url_success": ["The url_success field is required."]
  }
}

W formacie 422 errors to obiekt klucz → tablica komunikatów dla danego pola.

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, klucz Hash i normalizację `value` do dwóch miejsc
`Service not found`	Nieznana nazwa serwisu	Sprawdź pole `service` w panelu
`Amount is less than 0.01 PLN`	Kwota poniżej minimum	Minimalna kwota transakcji to `0.01`

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
BLIK OneClick - płatności jednym kliknięciem z zapisanym aliasem
Karty S2S - dodaj płatności kartowe Server-to-Server

Wymagania wstępne​

Schemat działania​

Krok 1: Przygotowanie danych​

Parametry wymagane​

Parametry opcjonalne​

Zależności parametru channel​

Obiekt device_info (wymagany dla MB WAY)​

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ź sukcesu bez URL bramki - "Internal processing" (HTTP 200)​

Odpowiedź sukcesu - "Transaction paid" (HTTP 200)​

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

Błąd po stronie merchanta (HTTP 400)​

Błąd walidacji pól (HTTP 422)​

Krok 5: Przekierowanie klienta​

PHP​

JavaScript (Express.js)​

Krok 6: Odbieranie IPN​

Pełny przykład - PHP​

Najczęstsze błędy​

Co dalej?​