DocsDecline codes

Decline codes

When a payment is declined, MAXFI returns one code from the list below. The code is the same whichever bank or payment network processed the payment: MAXFI never passes on a processor’s own codes or texts. The message next to the code is a fixed English text for that code; show your customer your own text based on the code.

Where the code appears

error.code and error.message in the response to POST /v2/payments when the payment is declined at once.
error_code and error_message in GET /v2/payments/{id} and GET /v2/payments/checkout/{id}.
data.error_code and data.error_message in the payment.failed and payment.expired webhook events. payment.failed always carries a code.

Codes

Code	Meaning	Retry?
card_declined	The card was declined. No more detail is available.	Another card
do_not_honor	The card issuer declined the payment. The customer should contact their bank.	Another card
insufficient_funds	Not enough money on the card or account.	Another card
expired_card	The card has expired.	Another card
incorrect_cvc	The security code (CVC) is wrong.	Yes
invalid_card	The card number or expiry date is wrong.	Yes
card_restricted	The issuer does not allow this payment with this card (for example, online payments are switched off, or the card is blocked).	Another card
limit_exceeded	The payment exceeds a card, account or daily limit.	Another card
issuer_unavailable	The card issuer could not be reached. Try again later.	Yes
3ds_failed	3-D Secure authentication failed or was not completed.	Yes
user_cancelled	The customer cancelled the payment.	Yes
session_expired	The customer did not complete the payment in time.	Yes
timeout	The confirmation (for example, in a wallet app) timed out.	Yes
wallet_declined	The wallet declined the payment.	Another card
fraud_detected	The payment was blocked by risk checks.	No
amount_invalid	The amount is below the minimum or above the maximum allowed.	No
amount_exceeds_captured	The amount is larger than the amount available for this operation.	No
operation_not_allowed	The operation is not allowed for the payment in its current state.	No
duplicate_transaction	A payment with these details was already submitted.	No
processing_error	A processing error, or a reason that has no code of its own. The customer can try again.	Yes
outcome_unknown	The result is not confirmed yet. Do not charge the customer again; check the payment later.	No
reconcile_timeout	In payment.expired: no final result arrived in time. Check the payment before you fulfil or refund it.	No

How to handle them

Branch on error_code, not on the message: the message text can change.
Treat a code you do not know as processing_error. New codes can be added; existing codes keep their meaning.
Do not show fraud_detected to the customer as “fraud”: say the payment could not be completed.
After outcome_unknown do not create a new payment for the same order until GET /v2/payments/{id} shows a final status.

Testing

Test cards and test phone numbers return these codes in test mode — see Quickstart.