> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Decline codes

> What each card decline code means, whether the same card can succeed later, and the message Ionic shows the buyer.

When a payment is declined, the [Charge](/concepts/key-concepts#how-the-objects-connect) 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.

```json theme={null}
{
  "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](/api-reference/charges/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](/api-reference/invoices/list-an-invoices-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](/guides/in-person-payments#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

<ResponseField name="insufficient_funds" type="retryable">
  The card does not have enough available funds.
</ResponseField>

<ResponseField name="card_velocity_exceeded" type="retryable">
  The card reached an amount or frequency limit.
</ResponseField>

<ResponseField name="withdrawal_count_limit" type="retryable">
  The card reached a limit on the number of transactions.
</ResponseField>

<ResponseField name="do_not_honor" type="retryable">
  The issuer declined without giving a reason.
</ResponseField>

<ResponseField name="generic_decline" type="retryable">
  The card was declined for an unspecified reason.
</ResponseField>

<ResponseField name="transaction_not_permitted" type="retryable">
  The card cannot be used for this payment, including when the cardholder stopped recurring payments to the merchant.
</ResponseField>

<ResponseField name="expired_card" type="not retryable">
  The card has expired.
</ResponseField>

<ResponseField name="incorrect_number" type="not retryable">
  The card number is invalid.
</ResponseField>

<ResponseField name="incorrect_cvc" type="not retryable">
  The security code is incorrect.
</ResponseField>

<ResponseField name="duplicate_transaction" type="not retryable">
  The payment was declined as a duplicate of a recent one.
</ResponseField>

### Authentication declines

These codes report a fraud signal from the issuer.

<ResponseField name="stolen_card" type="not retryable">
  The card was reported stolen.
</ResponseField>

<ResponseField name="lost_card" type="not retryable">
  The card was reported lost.
</ResponseField>

<ResponseField name="fraudulent" type="not retryable">
  The issuer suspects fraud.
</ResponseField>

<ResponseField name="pickup_card" type="not retryable">
  The issuer asked for the card to be retained.
</ResponseField>

<ResponseField name="restricted_card" type="not retryable">
  The card is restricted.
</ResponseField>

<ResponseField name="security_violation" type="not retryable">
  The issuer reported a security violation.
</ResponseField>

### Infrastructure declines

<ResponseField name="processing_error" type="retryable">
  An error occurred while processing the payment.
</ResponseField>

<ResponseField name="issuer_not_available" type="retryable">
  The card issuer could not be reached.
</ResponseField>

<ResponseField name="try_again_later" type="retryable">
  The payment could not be completed now.
</ResponseField>

<ResponseField name="processor_declined" type="not retryable">
  The payment was rejected before it reached the card issuer, for example because the card type is not supported.
</ResponseField>

## 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](/api-reference/errors) for the error envelope and every status
code.

## Test declines

In [test mode](/concepts/key-concepts#test-mode-and-live-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](/api-reference/test-clocks/arm-the-next-subscription-collection-outcome)
with that `decline_code`. See [Test cards](/guides/test-cards).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.