Concepts

Failure codes

A failure code explains why an attempt or payment failed. It is the reason, not the status: always take the outcome from the payment status.

Where codes appear

Payment reads and webhooks: nullable failureCode and failureMessage.
Pay and confirm attempts: failureCode and message, with attemptsLeft.

Match codes, not message text. While a payment is still pending, the reason for a retryable attempt may not appear on the payment.

Decline codes

Code	Category	Meaning
`card_declined` `issuer_declined` `declined` `do_not_honor` `generic_decline`	Card or issuer decline	The card was declined; another method may be needed.
`insufficient_funds`	Insufficient funds	The card has insufficient funds.
`expired_card`	Expired card	The card has expired.
`incorrect_cvc` `invalid_cvc`	Invalid security code	The security code is wrong.
`incorrect_number`	Invalid card number	The card number is wrong.
`transaction_not_allowed`	Transaction restricted	The card does not support this transaction.
`fraudulent`	Risk rejection	Risk checks declined the payment. This does not prove fraud.
`lost_card` `stolen_card` `pickup_card`	Issuer restriction	Declined; the customer should contact their bank.
`invalid_account`	Invalid account	Use another card or contact the bank.
`payment_intent_authentication_failure`	Authentication failure	3D Secure failed; try again or use another method.
`try_again_later`	Temporary rejection	Wait or use another method. Wegopay does not retry automatically.
`card_velocity_exceeded`	Card limit	Wait or contact the bank.
`test_mode_live_card`	Test card required	A real card was used in sandbox.
`expired`	Session expired	The checkout session expired. Different from `expired_card`.
`processing_error`	Processing failure	The payment network could not process the payment.

Code	Meaning
`provider_declined`	A generic decline when no specific code is available.
`card_token_rejected`	The card token was rejected. Fix capture before another attempt.
`processor_unavailable`	A generic checkout failure. Read the payment and checkout state before retrying.

failureCode is an open string, not a closed list. Other codes such as error, failed or canceled can appear. Show a generic message, keep the code for support, and take the outcome from the payment status. No code, including processing_error, by itself means you should charge again.

Mapping examples

What you see	Show the customer
Attempt `insufficient_funds`, checkout `failed_retryable`, payment `pending`	Payment pending. Last attempt: insufficient funds.
Checkout `expired` with `checkout_expired`, payment `pending`	Checkout expired; payment unresolved.
Payment `failed`	Payment failed.

See payment status for statuses and checkout states.

Where codes appear

Decline codes

Fallback codes

Mapping examples