Przejdź do głównej zawartości

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

KodZnaczenieOpis
200SukcesZapytanie przetworzone poprawnie
400Nieprawidłowe zapytanieBłąd walidacji biznesowej (np. nieprawidłowy checksum rejestracji, wyłączony kanał, zła kwota)
401Brak autoryzacjiBrakujące lub nieprawidłowe dane uwierzytelniające; także nieprawidłowy checksum przy zwrotach, szczegółach transakcji i wypłatach (Unauthorized request)
403Dostęp zabronionyBrak uprawnień do zasobu (errorcode: err01)
404Nie znalezionoZasób nie istnieje
422Błąd walidacji pólZapytanie nie przeszło walidacji formalnej pól (patrz format poniżej)
500Błąd serweraWewnę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:

ScenariuszWartość msgDodatkowe pola
Przekierowanie na bramkę płatnościURL bramki płatnościbrak
Tryb testowyURL wewnętrznej strony symulacji płatnościbrak
Przetwarzanie wewnętrzne (bez przekierowania, np. płatność inicjowana kodem)Internal processingbrak
Transakcja natychmiast opłaconaTransaction paidadditionalInfo.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"
}

Gdy operacja została odrzucona przez wydawcę karty, odpowiedź niesie dodatkowo obiekt error z kodem odmowy:

{
"success": false,
"status": "error",
"message": "Payment was declined by the card issuer.",
"error": {
"code": "payment_declined",
"declineCode": "05",
"declineMessage": "Do not honor"
}
}

Znaczenie pól opisuje sekcja Kody odmowy kartowej. Obiekt error jest opcjonalny - pojawia się tylko wtedy, gdy odmowa niesie rozpoznany kod. Buduj integrację tak, żeby jego brak nie był błędem, a pole message pozostaje źródłem komunikatu.

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:

StatusOpis
createdTransakcja utworzona, oczekuje na płatność
processingPłatność w trakcie przetwarzania
paidPłatność zakończona sukcesem
capturedŚrodki pobrane po wcześniejszej preautoryzacji
expiredTransakcja 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śćStatusOpis
0OczekujeWypłata oczekuje na realizację
1ZrealizowanaWypłata została przetworzona
-1BłądWypłata zakończona niepowodzeniem

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

PoleOpis
idIdentyfikator wypłaty
paysafecard1, gdy wypłata rozlicza płatności Paysafecard; w przeciwnym razie 0 (obecne, gdy direct_settlement = 0)
declined1, gdy wypłata została odrzucona; w przeciwnym razie 0
decline_reasonPowód odrzucenia wypłaty (obecne tylko, gdy declined = 1)
decline_statusStatus procesu odrzucenia (obecne tylko, gdy declined = 1)
direct_settlement1, gdy wypłata jest realizowana jako rozliczenie kierowane na wskazane rachunki
nrbNumer rachunku wypłaty (obecne, gdy direct_settlement = 0)
receiverObiekt z danymi odbiorców rozliczenia kierowanego (obecne zamiast nrb, gdy direct_settlement = 1)

Zawartość wypłaty

Endpoint pbl/withdraws/details/full zwraca to samo, co pbl/withdraws/details, i dodatkowo transakcje, które składają się na wypłatę. Odpowiedź ma cztery części:

PoleOpis
settlementNagłówek wypłaty - te same pola co w pbl/withdraws/details, uzupełnione o currency_code i export_date
summarySumy net, fee, gross oraz count dla całej wypłaty, niezależnie od stronicowania
transactionsStrona pozycji: payment_id, date, net, fee, gross, service_id, service_name, custom, ipksef
metapage, per_page, total, total_pages
Kwoty jako łańcuchy dziesiętne

Wszystkie kwoty w tej odpowiedzi - w nagłówku, w summary i w pozycjach - są łańcuchami znaków z dwoma miejscami po przecinku (np. "27.15"). Walutę znajdziesz w settlement.currency_code.

Stronicowanie jest oparte na numerze strony (page od 1, per_page domyślnie 100, maksymalnie 500). Strona poza zakresem zwraca pustą listę transactions, a nie ostatnią stronę - dzięki temu możesz iterować aż do pustej odpowiedzi. Sumy w summary zawsze opisują całą wypłatę, więc nadają się do uzgodnienia kwoty przelewu bez pobierania wszystkich stron.

Wypłata obejmująca dokładnie jedną płatność (rozliczenie kierowane, wypłata z formularza zwrotu) zwraca jedną pozycję z kwotami z nagłówka - kontrakt jest ten sam dla każdego typu wypłaty. Gdy pozycje nie są znane, transactions jest pustą listą, a summary.count wynosi 0.

Dopasowanie pozycji do własnych zamówień

Każda pozycja niesie dwa identyfikatory, którymi zepniesz wypłatę ze swoim systemem bez zgadywania po kwocie i dacie:

PoleZnaczenie
payment_idIdentyfikator transakcji dpay - ten sam, który dostajesz w IPN w polu id
customTwoje dane własne przekazane przy rejestracji płatności - ta sama wartość, którą IPN zwraca jako custom (null, gdy płatność ich nie niosła)

Prowizja jest liczona dla konkretnej płatności, nie rozdzielana proporcjonalnie na pozycje - transactions[].fee to rzeczywisty koszt tej transakcji.

Zwroty i obciążenia salda są osobnymi pozycjami z ujemnymi kwotami, a nie korektą w sumach nagłówka. Ich payment_id wskazuje źródło: ZWROT-{payment_id} dla zwrotu zleconego z panelu, REFUND-FORM-{uuid} dla zwrotu z formularza.

Znalezienie identyfikatora wypłaty

Endpoint pbl/withdraws zwraca listę Twoich wypłat, od najnowszej. Stamtąd bierzesz id, którym odpytujesz szczegóły:

PoleOpis
withdraws[].idIdentyfikator wypłaty - użyj go jako withdraw_id
withdraws[].typestandard, direct (wypłata jednej płatności) albo paysafecard
withdraws[].stateJak wyżej: 0 oczekuje, 1 zrealizowana, -1 błąd
withdraws[].export_dateKiedy przelew poszedł do banku; null, dopóki nie wyszedł
metapage, per_page, total, total_pages

Filtry: date_from, date_to (po dacie utworzenia), state i type. Domyślnie per_page to 50, maksymalnie 200. Lista nie zawiera numeru rachunku ani danych odbiorcy - te wydaje dopiero szczegół wypłaty.

Błędy rejestracji płatności

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

KomunikatPrzyczynaRozwiązanie
Invalid checksumNieprawidłowa suma kontrolnaSprawdź 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 foundNieznana nazwa serwisuSprawdź pole service w panelu dpay.pl
Amount is less than 0.01 PLNKwota niższa niż minimalnaPodaj 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:

KodOpis
DECLINETransakcja odrzucona przez wydawcę
EXPIRED_CARDInstrument płatniczy wygasł
INSUFFICIENT_FUNDSNiewystarczające środki
USER_DECLINEDUżytkownik odrzucił transakcję
TIMEOUTUpłynął czas oczekiwania na potwierdzenie
ALIAS_NOT_FOUNDNie znaleziono aliasu
SYSTEM_ERRORSymulowany błąd systemowy

Kody błędów MB WAY

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

KodOpisRozwiązanie
E0506Numer telefonu nie jest zarejestrowany w aplikacji MB WAYPoproś klienta o rejestrację numeru w aplikacji MB WAY lub o podanie innego numeru
E0508Numer telefonu chwilowo niedostępny w MB WAYSpróbuj ponownie za chwilę lub użyj innej metody płatności
E0099Operacja niedozwolona dla podanego numeruKlient powinien skontaktować się z obsługą MB WAY
E0103Niepoprawne dane żądaniaSprawdź format numeru telefonu (PT: 9 cyfr, prefix 351) oraz pozostałe pola
E0309Transakcja nie znalezionaSprawdź transactionId lub zainicjuj nową płatność
E0399Transakcja odrzuconaKlient odrzucił transakcję w aplikacji lub upłynął czas potwierdzenia
E0000Kod zastępczy - system nie zwrócił kodu błęduPotraktuj jak błąd generyczny; sprawdź error_description, przy powtórzeniach eskaluj do support
inne E*Generyczny błąd procesora MB WAYPole 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śćZnaczenieDziałanie
SUCCESSPłatność zakończonaPrzekieruj klienta na stronę sukcesu
FORMWymagane 3D SecureWyświetl formularz 3DS z redirectText (zakodowany Base64)
URLPrzekierowanie na adres zewnętrznyPrzekieruj klienta na adres z redirectText
DCC_OFFEROferta przewalutowania (DCC)Pokaż klientowi obie kwoty z pola dccOffer, po decyzji wywołaj endpoint ponownie z dccDecision (patrz DCC)

Kody odmowy kartowej

Odmowy kartowe zwracane przez API niosą obiekt z kodem odmowy - w odpowiedzi na operację kartową pod kluczem error, a w szczegółach transakcji pod kluczem cardError. Struktura obu jest identyczna:

PoleTypOpis
codestring|nullStabilny identyfikator przyczyny nadany przez dpay - patrz tabela poniżej. Nie zmienia się między operacjami ani w czasie, więc nadaje się na warunek w kodzie.
declineCodestring|nullDwuznakowy kod odpowiedzi sieci kartowej (ISO 8583) otrzymany od wydawcy karty. null, gdy odmowa nie pochodzi z autoryzacji (np. odrzucenie na etapie walidacji operacji).
declineMessagestring|nullOpis kodu declineCode po angielsku. Wartość jest deterministyczna - ta sama odmowa zawsze zwraca ten sam tekst, więc nadaje się do logowania i porównywania. Do prezentacji użytkownikowi tłumacz po declineCode, nie po tym polu.
Obiekt jest opcjonalny

Blok pojawia się wyłącznie wtedy, gdy odmowa niesie rozpoznany kod. Traktuj jego brak jako normalny przypadek i nie uzależniaj od niego obsługi błędu - message pozostaje źródłem komunikatu.

Wartości pola code

WartośćZnaczenieCo zrobić
payment_declinedWydawca karty odrzucił autoryzacjęSprawdź declineCode; przy 05/51 zaproponuj inną metodę płatności
invalid_cardNieprawidłowe dane karty lub nieobsługiwany typ kartyPoproś o poprawienie danych albo o inną kartę
card_already_registeredKarta jest już zapisana dla tej usługiUżyj istniejącego zapisu zamiast dodawać kartę ponownie
card_unavailableZapisana karta nie nadaje się do tej operacjiPoproś o ponowne dodanie karty
card_not_savedNie udało się zapisać kartyPowtórz zapis karty
refund_unavailableZwrot nie jest dostępny dla tej transakcjiZweryfikuj stan transakcji przed ponowieniem
transaction_not_foundWskazana transakcja nie istniejeSprawdź identyfikator transakcji
invalid_requestŻądanie nie przeszło walidacjiPopraw dane żądania
provider_unavailableChwilowa niedostępność przetwarzaniaPonów operację po chwili
payment_errorPłatności nie udało się przetworzyćPonów lub zaproponuj inną metodę płatności

Wartości pola declineCode

Kody odpowiedzi sieci kartowej (ISO 8583). Kolumna „Opis" zawiera dokładny tekst zwracany w polu declineMessage.

KodOpis (declineMessage)Znaczenie
01Refer to card issuerSkontaktuj się z wydawcą karty
03Invalid merchantNieprawidłowy akceptant
04Capture cardZatrzymaj kartę
05Do not honorTransakcja odrzucona przez wydawcę karty
08Honor with IDZatwierdzono po weryfikacji tożsamości
10Partial approvalTransakcja częściowo zatwierdzona
12Invalid transactionNieprawidłowa transakcja
13Invalid amountNieprawidłowa kwota
14Invalid card numberNieprawidłowy numer karty
15Invalid issuerNieprawidłowy wydawca karty
30Format errorBłąd formatu danych
41Lost cardKarta zgłoszona jako zagubiona
43Stolen cardKarta zgłoszona jako skradziona
46Closed accountKonto zostało zamknięte
51Insufficient funds or over credit limitNiewystarczające środki lub przekroczony limit kredytowy
54Expired cardKarta straciła ważność
55Invalid PINNieprawidłowy PIN
57Transaction not permitted to issuer or cardholderTransakcja niedozwolona dla wydawcy lub posiadacza karty
58Transaction not permitted to acquirer or terminalTransakcja niedozwolona dla agenta rozliczeniowego lub terminala
61Exceeds withdrawal amount limitPrzekroczono limit kwoty wypłaty
62Restricted cardKarta objęta ograniczeniami
63Security violationNaruszenie zasad bezpieczeństwa
65Exceeds withdrawal count limitPrzekroczono limit liczby wypłat
70Contact card issuerSkontaktuj się z wydawcą karty
71PIN not changedPIN nie został zmieniony
72Account not yet activatedKonto nie zostało jeszcze aktywowane
75Allowable number of PIN tries exceededPrzekroczono dozwoloną liczbę prób wprowadzenia PIN-u
76Invalid or nonexistent “To Account” specifiedWskazany rachunek docelowy jest nieprawidłowy lub nie istnieje
77Invalid or nonexistent “From Account” specifiedWskazany rachunek źródłowy jest nieprawidłowy lub nie istnieje
78Invalid or nonexistent account specifiedWskazany rachunek jest nieprawidłowy lub nie istnieje
79Life cycle (Mastercard only)Błąd cyklu życia transakcji (tylko Mastercard)
80System not availableSystem jest niedostępny
81Domestic debit transaction not allowedKrajowa transakcja kartą debetową jest niedozwolona
82Policy (Mastercard only)Odrzucono z powodu polityki Mastercard
83Fraud or security (Mastercard only)Podejrzenie oszustwa lub naruszenia bezpieczeństwa (tylko Mastercard)
84Invalid authorization life cycleNieprawidłowy cykl życia autoryzacji
85Not declinedTransakcja nie została odrzucona
86PIN validation not possibleWeryfikacja PIN-u nie jest możliwa
87Purchase amount only; no cash back allowedDozwolony jest tylko zakup, bez wypłaty gotówki
88Cryptographic failureBłąd kryptograficzny
89Unacceptable PIN; transaction declined; retryPIN nie został zaakceptowany; ponów transakcję
90Cutoff is in progressTrwa zamknięcie okresu rozliczeniowego
91Authorization system or issuer system inoperativeSystem autoryzacyjny lub system wydawcy jest niedostępny
92Unable to route transactionNie można wyznaczyć trasy transakcji
94Duplicate transaction detectedWykryto zduplikowaną transakcję
96System errorBłąd systemu
1ZAuthorization system or issuer system inoperativeSystem autoryzacyjny lub system wydawcy jest niedostępny
Nie prezentuj kodu odmowy płatnikowi

Kody 41 (karta zgubiona), 43 (karta skradziona) i 63 (naruszenie bezpieczeństwa) są sygnałami dla Ciebie, nie dla płatnika. Pokazuj wtedy ogólny komunikat o odrzuceniu płatności - szczegół podpowiada osobie posługującej się cudzą kartą, dlaczego transakcja nie przeszła.

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"
}
KomunikatHTTPPrzyczynaRozwiązanie
DCC_OFFER_EXPIRED200Decyzja wysłana po validUntil z oferty DCCPokaż "Oferta wygasła", wróć do ekranu metody płatności i rozpocznij nowy flow
INVALID_FLOW_STATE200dccDecision 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:

KomunikatHTTPPrzyczynaRozwiązanie
missing guid or value or url success/fail or chcksum400Brak jednego z wymaganych pól: guid, value, url_success, url_fail, checksumUzupełnij wszystkie wymagane pola zapytania
Could not find service by GUID400Nieznany identyfikator GUIDSprawdź GUID w panelu dpay.pl
Service not verified.401Punkt płatności nie przeszedł weryfikacjiDokończ weryfikację punktu płatności
Invalid checksum400Nieprawidłowa suma kontrolnaKwota 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śćStatusOpis
1PAIDPłatność zrealizowana
0PENDINGPłatność oczekuje na potwierdzenie
-1REJECTEDPłatność odrzucona
2REFUNDEDPłatność zwrócona

Statusy weryfikacji DCB

WartośćStatusOpis
1VERIFIEDNumer zweryfikowany
0NOT_VERIFIEDNumer niezweryfikowany
-1BLOCKEDNumer zablokowany
-2REQUIRES_CONTACTWymagany kontakt z obsługą

Statusy kodów SMS

WartośćStatusOpis
1USEDKod wykorzystany
0PENDINGKod oczekuje na użycie
-1REJECTEDKod odrzucony