Payment reason codes

Reason codes explain the current status of a payment. Use the code value for programmatic handling. The cause explains what happened; the integration next action explains what your integration should do.

Getpaid normalizes result codes across routes so you can act on a pre-defined set of known codes.

Action required

Action required does not represent a failure mode, but an additional requirement that is needed to continue with the payment process within the same payment attempt.

Code	Cause	Integration next action
authentication_required	Buyer authentication is required.	Complete the required authentication by following the flow.next_step.
mandate_required	A payment mandate is required.	Use the flow.next_step mandate form details and required fields to collect and submit the mandate.

Declined or failed reasons

Code	Cause	Integration next action
3ds_failed	3DS authentication failed.	Start a new payment attempt or use another payment method.
3ds_not_enrolled	The card is not enrolled for required 3DS.	Use another payment method.
3ds_not_supported	The payment path or method does not support required 3DS version.	Use a 3DSv2-capable payment method.
3ds_rejected	The issuer rejected 3DS authentication.	Start a new payment attempt or use another payment method.
3ds_required	The payment was attempted without required 3DS.	Start a new payment attempt that completes 3DS.
3ds_technical_failure	The related 3DS transaction is missing or failed.	Retry 3DS by starting a new payment attempt.
3ds_timeout	3DS authentication timed out.	Start a new payment attempt.
3ds_unavailable	A transient 3DS service condition prevented authentication.	Retry later.
buyer_abandoned	The buyer did not complete the payment flow.	Start a new payment attempt if the buyer wants to retry.
cancelled_by_buyer	The buyer cancelled the payment.	Start a new payment attempt only if the buyer wants to retry.
declined_by_acquirer	The acquirer declined the payment.	Use another payment method. Contact support to understand the decline reasons behind.
declined_by_issuer	The issuer declined the payment.	Use another payment method or ask the buyer to contact the issuer.
duplicate_transaction	The processor identified a possible duplicate.	Verify original payment before creating another attempt. Use idempotency.
expired	A payment or authentication step expired.	Start a new payment attempt.
expired_card	The card has expired.	Check method.card; collect updated card details or use another payment method.
insufficient_funds	The card or account has insufficient funds.	Ask the buyer to use a different payment method.
invalid_amount	The amount is invalid for the payment.	Check amount and currency; correct the amount and start a new payment attempt.
invalid_card	The card or its linked account cannot be used for this payment.	Ask the buyer to use another payment method. Collect corrected card details.
invalid_payer_details	The buyer details are invalid.	Correct the buyer details and start a new payment attempt.
payer_details_required	Required buyer details for the transaction were missing.	Collect the required details and start a new payment attempt.
invalid_security_code	The card security code is invalid.	Collect a new security code and start a new payment attempt.
limit_exceeded	An issuer, payment method, or transaction limit was exceeded.	Ask the buyer for another payment method or lower the amount.
lost_card	The card is reported lost.	Check method.card; do not retry with this card.
mandate_mismatch	The mandate does not match the payment details.	Check the mandate and payment details, then start a new payment attempt.
merchant_configuration_error	The merchant configuration cannot route or process this payment.	Correct the merchant configuration or contact Getpaid support.
restricted_card	Card restrictions prevent the payment.	Check method.card; do not retry with this card.
stolen_card	The card is reported stolen.	Check method.card; do not retry with this card.
suspected_fraud	Fraud controls rejected the payment.	Do not expose the specific cause to the buyer; offer another payment method.
unsupported_bank_country	The bank account country is not supported for this payment.	Use a bank account from a supported country or another payment method.
unsupported_currency	The currency cannot be processed for this payment at this time.	Use a payment method in a different currency.
unsupported_issuer	The issuer is not supported.	Check method.card; use another payment method.
unsupported_payment_method	The selected payment method cannot process the payment.	Use a different payment method.
updated_card	The card details are outdated.	Check method.card; collect updated card details.

Failed

Code	Cause	Integration next action
merchant_not_configured	The merchant is not configured for this payment or the requested currency.	Contact Getpaid support or update the payment configuration.
unavailable	A downstream payment service is unavailable.	Retry later. Contact Getpaid support if it persists.
unexpected	An unexpected processing error occurred.	Do not repeatedly retry. Contact Getpaid support with the payment id.
provider_unavailable	A downstream provider is unavailable.	Retry later. Contact Getpaid support if it persists.
unknown_error	An unknown error occurred.	Retry later. Contact Getpaid support with the payment id if it persists.