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 danych (np. nieprawidłowy checksum, brakujące pola)
401	Brak autoryzacji	Brakujące lub nieprawidłowe dane uwierzytelniające
403	Dostęp zabroniony	Brak uprawnień do zasobu (errorcode: err01)
404	Nie znaleziono	Zasób nie istnieje (np. err-payment-not-found)
500	Błąd serwera	Wewnętrzny błąd serwera (err-internal-server-error)

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

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

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

Błąd walidacji (HTTP 400)

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

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

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

Odpowiedź karty - wymagane 3D Secure

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

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": "ER_WRONG_TICKET",
    "error_description": null
  }
}

Statusy transakcji

Pole status w odpowiedzi TransactionResponse:

Status	Opis
created	Transakcja utworzona, oczekuje na płatność
processing	Płatność w trakcie przetwarzania
paid	Płatność zakończona sukcesem
canceled	Transakcja anulowana

Statusy wypłat

Pole state w odpowiedzi WithdrawDetailsResponse:

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

Błędy rejestracji płatności

Komunikaty zwracane w polu msg przy error: true:

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)
Service not found	Nieznana nazwa serwisu	Sprawdź pole service w panelu dpay.pl
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://

Kody błędów BLIK

Pole additionalInfo.error w odpowiedzi na płatność BLIK Level 0:

Kod	Opis	Rozwiązanie
ER_WRONG_TICKET	Nieprawidłowy kod BLIK	Poproś klienta o wygenerowanie nowego kodu w aplikacji bankowej

Kody odpowiedzi kart

Pole message.redirectType w odpowiedzi CardPaymentResponse:

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

Pole message w odpowiedzi z success: false przy płatności kartą:

Komunikat	HTTP	Przyczyna	Rozwiązanie
DCC_OFFER_EXPIRED	400	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	400	dccDecision wysłane bez wcześniejszej oferty (np. na zfinalizowanej transakcji)	Błąd techniczny - log + redirect na error screen
DCC_PROVIDER_ERROR	502	Błąd procesora kart przy aktualizacji decyzji DCC	Błąd techniczny - error screen, możliwa retry

Kody błędów DCB

Błędy rejestracji DCB

Komunikat	Przyczyna	Rozwiązanie
Invalid GUID	Nieprawidłowy identyfikator GUID	Sprawdź GUID w panelu dpay.pl
Invalid value	Nieprawidłowa kwota	Podaj kwotę w groszach jako string (np. "1023" = 10.23 PLN)
DCB not available	Operator nie obsługuje DCB	Zaproponuj klientowi inną metodę płatności
Limit exceeded	Przekroczony limit klienta	Poinformuj klienta o limicie operatora

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