Kody błędów i statusy odpowiedzi

Kompletna lista kodów HTTP, statusów transakcji, błędów walidacji i kodów odpowiedzi API dpay.pl.

Kody odpowiedzi HTTP

Kod	Znaczenie	Opis
200	Sukces	Zapytanie przetworzone poprawnie
400	Nieprawidłowe zapytanie	Błąd walidacji biznesowej (np. nieprawidłowy checksum rejestracji, wyłączony kanał, zła kwota)
401	Brak autoryzacji	Brakujące lub nieprawidłowe dane uwierzytelniające; także nieprawidłowy checksum przy zwrotach, szczegółach transakcji i wypłatach (Unauthorized request)
403	Dostęp zabroniony	Brak uprawnień do zasobu (errorcode: err01)
404	Nie znaleziono	Zasób nie istnieje
422	Błąd walidacji pól	Zapytanie nie przeszło walidacji formalnej pól (patrz format poniżej)
500	Błąd serwera	Wewnętrzny błąd serwera

Formaty odpowiedzi

Odpowiedź sukcesu (rejestracja płatności)

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

Pole msg w odpowiedzi sukcesu rejestracji przyjmuje różne wartości w zależności od scenariusza:

Scenariusz	Wartość msg	Dodatkowe pola
Przekierowanie na bramkę płatności	URL bramki płatności	brak
Tryb testowy	URL wewnętrznej strony symulacji płatności	brak
Przetwarzanie wewnętrzne (bez przekierowania, np. płatność inicjowana kodem)	Internal processing	brak
Transakcja natychmiast opłacona	Transaction paid	additionalInfo.transaction ze szczegółami transakcji

Odpowiedź sukcesu - transakcja opłacona

{
  "error": false,
  "msg": "Transaction paid",
  "status": true,
  "transactionId": "A75AEBB4-4B89-4834-AD43-EF442C133769",
  "additionalInfo": {
    "transaction": {
      "payment_id": "A75AEBB4-4B89-4834-AD43-EF442C133769",
      "pid": null,
      "mtid": null,
      "email": "klient@example.com",
      "description": "Zamówienie #1234",
      "name": null,
      "surname": null,
      "value": "29.99",
      "status": "paid",
      "creation_date": "2026-05-03 17:40:07",
      "payment_date": "2026-05-03 17:40:12"
    }
  }
}

Statusy w polu additionalInfo.transaction.status opisuje sekcja Statusy transakcji.

Odpowiedź błędu transakcji (np. anulowana)

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

Błąd walidacji biznesowej (HTTP 400)

Zwracany przy błędach po stronie merchanta (nieprawidłowy checksum, wyłączony kanał, zła kwota). Pole message zawiera konkretny komunikat błędu, a errors to obiekt mapujący nazwę pola na komunikat (nie tablica):

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

{
  "status": "failed",
  "message": "Amount is less than 0.01 PLN",
  "errors": {
    "value": "Invalid value"
  }
}

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

Gdy zapytanie nie przejdzie walidacji formalnej pól (brak pola wymaganego, zły typ danych), API zwraca standardową odpowiedź walidacyjną. W tym formacie errors mapuje nazwę pola na tablicę komunikatów:

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

Odpowiedź błędu z kodem (403)

{
  "error": true,
  "errorcode": "err01",
  "message": "Access denied",
  "status": false
}

Odpowiedź karty - sukces

{
  "success": true,
  "status": "success",
  "message": {
    "redirectText": "",
    "redirectType": "SUCCESS",
    "dccOffer": null
  }
}

Pole message

Przy sukcesie (success: true) pole message jest obiektem, w którym dccOffer występuje zawsze - przyjmuje null, gdy oferta przewalutowania nie została złożona. Przy błędzie (success: false) pole message jest stringiem z komunikatem błędu.

Odpowiedź karty - wymagane 3D Secure

{
  "success": true,
  "status": "success",
  "message": {
    "redirectText": "PGZvcm0gbWV0aG9kPSJQT1NUIi4uLg==",
    "redirectType": "FORM",
    "dccOffer": null
  }
}

Odpowiedź karty - błąd

{
  "success": false,
  "status": "error",
  "message": "DCC_OFFER_EXPIRED"
}

Odpowiedź karty - oferta DCC (karta zagraniczna)

{
  "success": true,
  "status": "success",
  "message": {
    "redirectText": null,
    "redirectType": "DCC_OFFER",
    "dccOffer": {
      "currencyConversionId": "00509166251006151007",
      "originalAmount": 3.00,
      "originalCurrency": "EUR",
      "convertedAmount": 13.52,
      "convertedCurrency": "PLN",
      "exchangeRate": 4.507968,
      "validUntil": "2026-05-03T17:40:07+00:00",
      "declarationText": "Make sure you understand the costs of currency conversions...",
      "markup": [{ "rate": 6.0, "additionalInfo": "Mastercard" }],
      "europeanEconomicArea": true
    }
  }
}

Pełen opis obsługi: Dynamic Currency Conversion (DCC).

Odpowiedź BLIK - błąd

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

Statusy transakcji

Pole status w odpowiedzi na zapytanie o szczegóły transakcji (pbl/details) oraz w statusach zwrotów:

Status	Opis
created	Transakcja utworzona, oczekuje na płatność
processing	Płatność w trakcie przetwarzania
paid	Płatność zakończona sukcesem
captured	Środki pobrane po wcześniejszej preautoryzacji
expired	Transakcja anulowana lub wygasła

Druga mapa statusów - odpowiedź rejestracji

W polu additionalInfo.transaction.status odpowiedzi rejestracji (wariant Transaction paid) obowiązuje inne mapowanie: pending, paid, captured, canceled. Statusy pending i canceled pojawiają się wyłącznie w tym miejscu, a created, processing i expired wyłącznie w odpowiedzi szczegółów transakcji.

Statusy wypłat

Pole state w odpowiedzi na zapytanie o szczegóły wypłaty (pbl/withdraws/details):

Wartość	Status	Opis
0	Oczekuje	Wypłata oczekuje na realizację
1	Zrealizowana	Wypłata została przetworzona
-1	Błąd	Wypłata zakończona niepowodzeniem

Oprócz state, pól kwotowych (net, fee, gross) i daty utworzenia (creation_date) odpowiedź zawiera:

Pole	Opis
id	Identyfikator wypłaty
paysafecard	Kwota części Paysafecard wypłaty (obecne, gdy direct_settlement = 0)
declined	1, gdy wypłata została odrzucona; w przeciwnym razie 0
decline_reason	Powód odrzucenia wypłaty (obecne tylko, gdy declined = 1)
decline_status	Status procesu odrzucenia (obecne tylko, gdy declined = 1)
direct_settlement	1, gdy wypłata jest realizowana jako rozliczenie kierowane na wskazane rachunki
nrb	Numer rachunku wypłaty (obecne, gdy direct_settlement = 0)
receiver	Obiekt z danymi odbiorców rozliczenia kierowanego (obecne zamiast nrb, gdy direct_settlement = 1)

Błędy rejestracji płatności

Komunikaty zwracane w polu message odpowiedzi HTTP 400 (patrz Błąd walidacji biznesowej):

Komunikat	Przyczyna	Rozwiązanie
Invalid checksum	Nieprawidłowa suma kontrolna	Sprawdź kolejność pól i klucz Hash. Format: sha256(service|hash|value|url_success|url_fail|url_ipn) z value znormalizowanym do dwóch miejsc po przecinku
Service not found	Nieznana nazwa serwisu	Sprawdź pole service w panelu dpay.pl
Amount is less than 0.01 PLN	Kwota niższa niż minimalna	Podaj kwotę co najmniej 0.01 w formacie z kropką dziesiętną (np. "29.99"); w errors.value pojawia się wtedy Invalid value

Kody błędów BLIK

Przy odmowie płatności BLIK pole additionalInfo.error zawiera surowy kod odmowy systemu BLIK, przekazywany 1:1 bez mapowania po stronie dpay. Lista kodów jest otwarta - zależy od banku klienta i systemu BLIK. Traktuj to pole jako informację diagnostyczną i nie buduj na nim logiki biznesowej.

W trybie testowym płatności są symulowane i pole additionalInfo.error przyjmuje jeden z następujących kodów:

Kod	Opis
DECLINE	Transakcja odrzucona przez wydawcę
EXPIRED_CARD	Instrument płatniczy wygasł
INSUFFICIENT_FUNDS	Niewystarczające środki
USER_DECLINED	Użytkownik odrzucił transakcję
TIMEOUT	Upłynął czas oczekiwania na potwierdzenie
ALIAS_NOT_FOUND	Nie znaleziono aliasu
SYSTEM_ERROR	Symulowany błąd systemowy

Kody błędów MB WAY

Pole additionalInfo.error w odpowiedzi na płatność MB WAY (przy error: true, status: false):

Kod	Opis	Rozwiązanie
E0506	Numer telefonu nie jest zarejestrowany w aplikacji MB WAY	Poproś klienta o rejestrację numeru w aplikacji MB WAY lub o podanie innego numeru
E0508	Numer telefonu chwilowo niedostępny w MB WAY	Spróbuj ponownie za chwilę lub użyj innej metody płatności
E0099	Operacja niedozwolona dla podanego numeru	Klient powinien skontaktować się z obsługą MB WAY
E0103	Niepoprawne dane żądania	Sprawdź format numeru telefonu (PT: 9 cyfr, prefix 351) oraz pozostałe pola
E0309	Transakcja nie znaleziona	Sprawdź transactionId lub zainicjuj nową płatność
E0399	Transakcja odrzucona	Klient odrzucił transakcję w aplikacji lub upłynął czas potwierdzenia
E0000	Kod zastępczy - system nie zwrócił kodu błędu	Potraktuj jak błąd generyczny; sprawdź error_description, przy powtórzeniach eskaluj do support
inne E*	Generyczny błąd procesora MB WAY	Pole error_description zawiera szczegółowy komunikat - eskaluj do support jeśli powtarza się

Format pełnej odpowiedzi błędu MB WAY:

{
  "error": true,
  "msg": "Transaction canceled",
  "status": false,
  "transactionId": "42191111-A7AE-392E-8C09-7965C1DC6B0B",
  "additionalInfo": {
    "error": "E0506",
    "error_description": "The provided alias does not exists"
  }
}

Kody odpowiedzi kart

Pole message.redirectType w odpowiedzi na płatność kartą. Poniższa lista wartości jest kompletna:

Wartość	Znaczenie	Działanie
SUCCESS	Płatność zakończona	Przekieruj klienta na stronę sukcesu
FORM	Wymagane 3D Secure	Wyświetl formularz 3DS z redirectText (zakodowany Base64)
URL	Przekierowanie na adres zewnętrzny	Przekieruj klienta na adres z redirectText
DCC_OFFER	Oferta przewalutowania (DCC)	Pokaż klientowi obie kwoty z pola dccOffer, po decyzji wywołaj endpoint ponownie z dccDecision (patrz DCC)

Kody błędów DCC

Błędy DCC są zwracane z kodem HTTP 200 w formacie {"success": false, "status": "error", "message": "..."} - pole message jest wtedy stringiem z kodem błędu:

{
  "success": false,
  "status": "error",
  "message": "DCC_OFFER_EXPIRED"
}

Komunikat	HTTP	Przyczyna	Rozwiązanie
DCC_OFFER_EXPIRED	200	Decyzja wysłana po validUntil z oferty DCC	Pokaż "Oferta wygasła", wróć do ekranu metody płatności i rozpocznij nowy flow
INVALID_FLOW_STATE	200	dccDecision wysłane bez wcześniejszej oferty (np. na zfinalizowanej transakcji)	Błąd techniczny - log + redirect na error screen

uwaga

Nie rozpoznawaj tych błędów po kodzie HTTP - odpowiedź przychodzi z HTTP 200. Sprawdzaj pole success w body odpowiedzi.

Kody błędów DCB

Błędy rejestracji DCB (endpoint secure.dpay.pl/dcb/register)

Komunikaty zwracane w polu msg przy error: true:

Komunikat	HTTP	Przyczyna	Rozwiązanie
missing guid or value or url success/fail or chcksum	400	Brak jednego z wymaganych pól: guid, value, url_success, url_fail, checksum	Uzupełnij wszystkie wymagane pola zapytania
Could not find service by GUID	400	Nieznany identyfikator GUID	Sprawdź GUID w panelu dpay.pl
Service not verified.	401	Punkt płatności nie przeszedł weryfikacji	Dokończ weryfikację punktu płatności
Invalid checksum	400	Nieprawidłowa suma kontrolna	Kwota w checksum w złotych z dwoma miejscami po przecinku, bez url_ipn - patrz Generowanie checksum

notatka

Komunikat missing guid or value or url success/fail or chcksum zawiera literówkę (chcksum) po stronie API - jest zwracany dosłownie w tej formie.

Statusy płatności DCB

Wartość	Status	Opis
1	PAID	Płatność zrealizowana
0	PENDING	Płatność oczekuje na potwierdzenie
-1	REJECTED	Płatność odrzucona
2	REFUNDED	Płatność zwrócona

Statusy weryfikacji DCB

Wartość	Status	Opis
1	VERIFIED	Numer zweryfikowany
0	NOT_VERIFIED	Numer niezweryfikowany
-1	BLOCKED	Numer zablokowany
-2	REQUIRES_CONTACT	Wymagany kontakt z obsługą

Statusy kodów SMS

Wartość	Status	Opis
1	USED	Kod wykorzystany
0	PENDING	Kod oczekuje na użycie
-1	REJECTED	Kod odrzucony