Decline codes

When a payment is declined, the Charge records the reason in decline_code and decline_type, and the PaymentIntent returns to requires_payment_method. Confirming the PaymentIntent returns 402 with code PAYMENT_DECLINED and the same fields.

{
  "error": {
    "code": "PAYMENT_DECLINED",
    "message": "payment was declined",
    "type": "card_error",
    "decline_code": "insufficient_funds",
    "decline_type": "authorization",
    "retryable": true
  }
}

Where to read the code

Surface	Where the decline code appears
Confirming a PaymentIntent	The `402` error body: `decline_code`, `decline_type`, and `retryable`
A PaymentIntent retrieved later	The Charge at `latest_charge_id`, from Retrieve a charge
`payment_intent.payment_failed`	The event carries the PaymentIntent. Retrieve the Charge at `latest_charge_id`
Invoice collection	`failure_code` on each failed attempt from list an invoice’s payment attempts
Hosted checkout and hosted invoices	Ionic shows the buyer the message in the table below
Ionic Blocks	`confirmPayment` returns `payment_failed`. Your server reads the code from the Charge
Terminals	`failure_code` on the terminal payment. See Handle every status

A PaymentIntent’s charges list is ordered oldest first, so use latest_charge_id for the most recent attempt.

Decline types

`decline_type`	Meaning
`authorization`	The issuer declined for a card or funds reason.
`authentication`	The issuer reported a fraud signal, such as a lost or stolen card.
`infrastructure`	A processing or network problem prevented approval.

retryable: true means the same card could succeed on a later attempt, for example after funds are deposited or a limit resets. It does not mean an immediate retry will succeed.

Codes

Authorization declines

retryable

The card does not have enough available funds.

retryable

The card reached an amount or frequency limit.

retryable

The card reached a limit on the number of transactions.

retryable

The issuer declined without giving a reason.

retryable

The card was declined for an unspecified reason.

retryable

The card cannot be used for this payment, including when the cardholder stopped recurring payments to the merchant.

not retryable

The card has expired.

not retryable

The card number is invalid.

not retryable

The security code is incorrect.

not retryable

The payment was declined as a duplicate of a recent one.

Authentication declines

These codes report a fraud signal from the issuer.

not retryable

The card was reported stolen.

not retryable

The card was reported lost.

not retryable

The issuer suspects fraud.

not retryable

The issuer asked for the card to be retained.

not retryable

The card is restricted.

not retryable

The issuer reported a security violation.

Infrastructure declines

retryable

An error occurred while processing the payment.

retryable

The card issuer could not be reached.

retryable

The payment could not be completed now.

not retryable

The payment was rejected before it reached the card issuer, for example because the card type is not supported.

Messages the buyer sees

Ionic-hosted checkout and hosted invoice pages show the buyer one message per code.

Message	Codes
There aren’t enough funds available on this card. Try another card or contact your bank.	`insufficient_funds`
This card has reached a transaction limit. Try another card or try again later.	`card_velocity_exceeded`, `withdrawal_count_limit`
Your bank declined this payment. Try another card or contact your bank.	`do_not_honor`
This card can’t be used for this payment. Try another card or contact your bank.	`transaction_not_permitted` and every authentication code
This card is expired. Use a different card.	`expired_card`
The card number doesn’t look right. Check the number and try again.	`incorrect_number`
The security code doesn’t look right. Check the CVC and try again.	`incorrect_cvc`
This looks like a duplicate payment. Wait a moment before trying again.	`duplicate_transaction`
The payment couldn’t be processed right now. Try again in a moment.	`processing_error`
Your bank couldn’t be reached. Try again in a moment or use another card.	`issuer_not_available`
The payment couldn’t be completed right now. Try again in a moment.	`try_again_later`
The payment was declined. Try another card or contact your bank.	`generic_decline`, `processor_declined`, and any other code

Every authentication code shows the same neutral message, so the buyer does not learn which fraud signal the issuer reported. Use the same approach on payment pages you build.

Other payment outcomes

Code	Status	Meaning
`PAYMENT_DECLINED`	`402`	The card was declined. Read `decline_code`.
`PAYMENT_FAILED`	`402`	The payment could not be processed. The Charge is `failed`, has no `decline_code`, and carries a failure detail in `failure_message`.
`PAYMENT_PROCESSING`	`409`	Another confirmation of this PaymentIntent is in progress.
`GATEWAY_ERROR`	`502`	From confirming a PaymentIntent or creating a refund, no money moved. Try again with a new `Idempotency-Key`.
`GATEWAY_UNCERTAIN`	`504`	The outcome is not known yet. Retrieve the PaymentIntent before trying again.

See Errors for the error envelope and every status code.

Test declines

In test mode, a charge under $1.00 declines with generic_decline. To test how your integration handles a specific code on a subscription renewal, arm a collection scenario with that decline_code. See Test cards.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

Where to read the code

Decline types

Codes

Authorization declines

Authentication declines

Infrastructure declines

Messages the buyer sees

Other payment outcomes

Test declines

​Where to read the code

​Decline types

​Codes

​Authorization declines

​Authentication declines

​Infrastructure declines

​Messages the buyer sees

​Other payment outcomes

​Test declines

Where to read the code

Decline types

Codes

Authorization declines

Authentication declines

Infrastructure declines

Messages the buyer sees

Other payment outcomes

Test declines