Kody odmów

Gdy płatność, zwrot albo wypłata się nie uda, obiekt w zdarzeniu webhook niesie pole failure ze stabilnym kodem dpay. Kod jest wspólny dla wszystkich metod płatności, więc jedną logiką obsłużysz odmowę BLIK, karty i przelewu. Oryginalny kod dostawcy przychodzi obok, do diagnozy.

Kody odmów a kody błędów

Kody błędów to odpowiedzi API na nieprawidłowe żądanie, zwracane od razu. Kody odmów opisują, dlaczego płatność, zwrot albo wypłata nie doszły do skutku - przychodzą w zdarzeniach payment.failed, refund.failed i payout.failed.

Obiekt failure

"failure": {
  "code": "insufficient_funds",
  "message": "Insufficient funds",
  "category": "customer",
  "retryable": true,
  "provider_code": "INSUFFICIENT_FUNDS"
}

Pole	Opis
code	Kod odmowy dpay z tabeli niżej. Na nim opieraj logikę.
message	Krótki opis po angielsku - do logów i dla zespołu. Klientowi pokaż własny komunikat.
category	Kto może usunąć przyczynę: customer, merchant, risk albo system.
retryable	true, gdy ponowienie tej samej płatności może się udać.
provider_code	Kod dostawcy (BLIK, operator kart, bank) albo null. Tylko do diagnozy - lista kodów dostawców się zmienia.

W zdarzeniach, które nie są odmową, failure ma wartość null.

Kategorie

Kategoria	Znaczenie	Co zrobić
customer	Przyczyna po stronie klienta: środki, limit, kod, bank, karta.	Poinformuj klienta i zaproponuj ponowienie albo inną metodę płatności.
merchant	Przyczyna po Twojej stronie: żądanie, warunki płatności cyklicznej, termin albo kwota zwrotu.	Popraw żądanie albo dane - samo ponowienie nie pomoże.
risk	Odmowa ze względów bezpieczeństwa.	Nie ponawiaj automatycznie i nie podawaj klientowi szczegółów.
system	Chwilowy błąd po stronie banku, dostawcy albo dpay.	Ponów później.

Ponowienie (retryable)

retryable: true znaczy, że ta sama płatność może się udać przy kolejnej próbie - np. gdy klient doładuje konto, poda nowy kod BLIK albo potwierdzi płatność na czas. Przy false ponowienie bez zmiany (innej karty, innej metody, poprawionego żądania) się nie uda.

Przy obciążeniach płatności cyklicznej ponawiaj automatycznie tylko odmowy z retryable: true i z rozsądnym odstępem. Odmowy z retryable: false wymagają kontaktu z klientem.

Tabela kodów

Kod	Kategoria	Ponowienie	Znaczenie
insufficient_funds	customer	tak	Brak środków na rachunku albo karcie.
limit_exceeded	customer	tak	Przekroczony limit klienta - kwotowy albo liczby transakcji.
customer_declined	customer	tak	Klient odrzucił płatność, np. w aplikacji banku.
customer_timeout	customer	tak	Klient nie potwierdził płatności na czas.
invalid_code	customer	tak	Nieprawidłowy, wygasły albo już użyty kod (np. BLIK).
expired	customer	tak	Płatność nie została opłacona w ciągu 7 dni.
app_update_required	customer	tak	Klient musi zaktualizować aplikację bankową.
issuer_declined	customer	nie	Odmowa banku albo wydawcy karty, także przy zamkniętym albo zablokowanym koncie.
card_invalid	customer	nie	Nieprawidłowa albo wygasła karta.
authentication_required	customer	nie	Silne uwierzytelnienie klienta (3-D Secure) nie powiodło się.
alias_invalid	customer	nie	Zapisany alias płatności (BLIK OneClick, płatność cykliczna) nie jest już ważny.
unsupported_by_bank	customer	nie	Bank klienta nie obsługuje tego rodzaju płatności.
generic_decline	customer	nie	Odmowa bez bliższej przyczyny. Dostaje go też każdy nowy albo nieznany kod dostawcy - zobaczysz go w provider_code.
security_declined	risk	nie	Odmowa ze względów bezpieczeństwa, np. system antyfraudowy albo karta zgłoszona jako utracona.
blocked	risk	nie	Płatności kodem czasowo zablokowane po serii błędnych kodów.
recurring_conditions_not_met	merchant	nie	Obciążenie nie spełnia warunków płatności cyklicznej, np. kwota ponad limit.
invalid_request	merchant	nie	Nieprawidłowe żądanie, np. alias już istnieje, błędny numer rachunku albo płatności cykliczne niewłączone dla serwisu.
refund_window_expired	merchant	nie	Minął termin na zwrot.
refund_amount_exceeded	merchant	nie	Kwota zwrotu przekracza kwotę możliwą do zwrotu.
payout_failed	merchant	nie	Wypłata nie została zrealizowana (patrz Wypłaty).
refund_failed	system	nie	Zwrot się nie powiódł.
processing_error	system	tak	Chwilowy błąd przetwarzania po stronie banku, dostawcy albo dpay.

Nowe kody

Lista kodów może się wydłużać. Nieznany code obsłuż według category i retryable, tak jak generic_decline.

Mapowanie kodów dostawców

W provider_code przychodzi oryginalny kod dostawcy. Poniżej kody, które zamieniamy na kody dpay. Kod spoza tych tabel (także od innych dostawców, np. przy przelewach online) daje generic_decline z tym kodem w provider_code.

BLIK

Kod dpay	Kody BLIK
insufficient_funds	INSUFFICIENT_FUNDS
limit_exceeded	LIMIT_EXCEEDED, LOW_LIMIT, LIMIT_LOCKED
customer_declined	USER_DECLINED
customer_timeout	TIMEOUT, USER_TIMEOUT, AM_TIMEOUT, LONG_TIMEOUT
invalid_code	BAD_PIN, ER_WRONG_TICKET, ER_TIC_EXPIRED, ER_TIC_USED
app_update_required	OLD_APK_VERSION
issuer_declined	ISSUER_DECLINED, ACCOUNT_CLOSED, ACCOUNT_DISABLED, BLIKL_DECLINED, LIMIT_NOT_APPROVED, LIMIT_IN_OTHER_BANK, LIMIT_ALREADY_ACTIVE, TFR_REJECTED
alias_invalid	ALIAS_DECLINED, ALIAS_NOT_FOUND, ALIAS_APP_NOT_FOUND, ALIAS_EXPIRED, ALIAS_NOT_AVAILABLE
unsupported_by_bank	OFFUS_NOT_ALLOWED, TXTYPE_USR_UNHANDLED, BLIK-L_NOTSUPPORTED, SPLITPAYMENT_UNHANDL
security_declined	SEC_DECLINED, TAS_DECLINED, SENDER_BLOCKED, SENDER_UNKNOWN, WRONG_DEVLOC_DATA, PEP_VERIFICATION, PESEL_RESTRICTED
blocked	TOO_MANY_TRIES
recurring_conditions_not_met	AUTOCONF_REQ_NOT_MET, AMOUNT_LIMIT_EXCEEDED
invalid_request	ALIAS_ALR_EXISTS, BAD_IBAN, RECURRING_NOT_ENABLED, ALIAS_APP_AMBIGUOUS
refund_window_expired	RET_LATE, TFR_LATE
refund_amount_exceeded	RET_AMT_EXCEEDED
processing_error	SYSTEM_ERROR, GENERAL_ERROR, ISS_OUTOFSERVICE, PESEL_SERVICE_FAILED, TX_NOTFOUND, TFR_NOT_POSSIBLE, INTERNAL_ERROR

Karty (ISO 8583)

Kod karty	Znaczenie	Kod dpay
51	Brak środków	insufficient_funds
61	Przekroczony limit kwoty	limit_exceeded
65	Przekroczony limit liczby transakcji	limit_exceeded
05	Odmowa wydawcy (do not honor)	issuer_declined
46	Konto zamknięte	issuer_declined
57	Transakcja niedozwolona dla posiadacza karty	issuer_declined
62	Karta z ograniczeniami	issuer_declined
14	Nieprawidłowy numer karty	card_invalid
54	Karta wygasła	card_invalid
04	Zatrzymaj kartę	security_declined
41	Karta zgubiona	security_declined
43	Karta skradziona	security_declined
59	Podejrzenie oszustwa	security_declined
03	Nieprawidłowy akceptant	invalid_request
12	Nieprawidłowa transakcja	invalid_request
13	Nieprawidłowa kwota	invalid_request
30	Błąd formatu	invalid_request
58	Transakcja niedozwolona dla terminala	invalid_request
91	Wydawca niedostępny	processing_error
96	Awaria systemu	processing_error

Kody dpay

Kod	Znaczenie	Kod dpay
SCA_REJECTED	Silne uwierzytelnienie (3-D Secure) odrzucone	authentication_required
WRONG_TICKET_BLOCKED	Płatności kodem BLIK czasowo zablokowane po serii błędnych kodów	blocked

Wypłaty

Odrzucona wypłata (payout.failed) ma zawsze kod payout_failed, a provider_code mówi, co stało się ze środkami:

provider_code	Znaczenie
refunded_to_dpay	Środki wróciły na saldo konta w dpay.
refunded_to_nrb	Środki zostały zwrócone na rachunek bankowy.
frozen	Środki są zamrożone.
blocked	Środki są zablokowane.
null	Bez dodatkowej informacji.

Szczegóły odrzuconej wypłaty wyjaśnisz z obsługą dpay.