Handling Declines

When a transaction does not result in an approval, the response and the Transaction Processed Webhook carry four fields that explain the outcome. Understanding the difference between them is essential for building reliable decline-handling logic.

Response Fields

Every transaction response and webhook payload includes the following outcome fields:

Field	Source	Stability	Intended Use
processing_code	Gateway (normalized)	Stable, enumerated	Primary field for branching integration logic.
response_message	Gateway (normalized)	Stable, human-readable	Display-safe summary matching processing_code.
payment_provider_response_code	Upstream PSP (raw)	Varies per provider and over time	Logging, support investigations, reconciliation.
payment_provider_response_message	Upstream PSP (raw)	Varies per provider and over time	Logging and diagnostics only — do not branch on this value.

Recommendation

Always map your decline-handling logic to processing_code. The gateway normalizes upstream PSP responses into a stable, enumerated set of processing codes. PSP codes differ between providers, change over time, and are not guaranteed to be stable — use them for logs and support tickets, not for logic.

Processing Code Reference

Processing codes are grouped into families by the leading digit. Handling guidance for each family is summarized below the table.

0000 — Approved

Code	Description
0000	Transaction approved successfully

1xxx — Transaction lifecycle and basic declines

Code	Description
1000	Transaction declined (generic decline from the issuer/PSP)
1001	Transaction failed
1002	Transaction pending (not yet in a terminal state)
1003	Transaction canceled
1004	Transaction declined — insufficient funds
1005	Session expired

2xxx — Invalid request

Validation and configuration errors. These will not succeed on retry with the same input.

Code	Description
2000	Invalid request (generic)
2001	Payment method expired
2002	Payment method invalid
2003	Payment method not found or invalid
2004	Payment method type not supported
2005	Payment method blocked
2006	Payment method inactive
2007	Installments not supported for this payment method
2008	Payment link expired
2009	Payment link not found
2010	Transaction type not supported
2011	Transaction feature not supported
2012	Installments not supported
2013	Terminal not found
2014	Terminal inactive
2015	Terminal not accepting payments
2016	Terminal does not support installments
2017	Merchant inactive
2018	Feature not enabled
2019	Merchant does not support tokenization
2020	Card CVV invalid
2021	Payment provider account inactive
2022	Shop (location) inactive
2023	Account inactive
2024	Payment provider inactive

3xxx — Authentication (3DS)

Code	Description
3000	Authentication not performed or incomplete
3001	Authentication rejected by the issuer
3002	Authentication unavailable

4xxx — Risk

Declined by the gateway's risk engine before reaching the PSP. Retrying the same transaction will produce the same result.

Code	Description
4100	Blacklist rule matched (customer, card, or merchant)
4101	Fraud check failed
4200	Velocity check failed (generic)
4201	Velocity check failed — customer limit exceeded
4202	Velocity check failed — merchant limit exceeded
4203	Velocity check failed — PSP limit exceeded

Handling Guidance

Use the following patterns to map processing codes to user-facing behavior:

Family	Retryable?	Recommended action
0000	—	Treat the transaction as successful.
1000, 1001, 1004	Sometimes	Prompt the customer to try a different payment method or contact their issuer. Do not retry the same card automatically.
1002	Wait	Do not finalize the order. Wait for the terminal webhook (transaction:approved / :declined) or poll the Transaction Status API.
1003	No	Transaction was canceled; offer the customer to start a new checkout.
1005	No	The checkout session has expired — start a new session.
2001, 2002, 2003, 2020	No (same input)	Prompt the customer to correct card details or use a different card.
2004, 2005, 2006, 2007, 2010, 2011, 2012, 2019	No	Offer an alternative payment method. The selected method/feature is not supported for this transaction.
2008, 2009	No	The payment link is no longer valid. Generate a new payment link.
2013 – 2018, 2021 – 2024	No (configuration)	Non-retryable configuration issues. Log the response and contact Finrelay support.
3000, 3001, 3002	No (as-is)	3DS authentication did not succeed. Prompt the customer to retry authentication or use a different card.
4xxx	No	The transaction was blocked by the risk engine. Do not retry automatically. Inform the customer and, where appropriate, escalate to support.

Logging PSP details

Always persist payment_provider_response_code and payment_provider_response_message alongside processing_code in your transaction records. These raw values are invaluable when reconciling with PSPs or when contacting Finrelay support about a specific decline.