# How declines work

Understand issuer declines, blocked payments, and invalid API calls.

An issuer decline occurs when your customer’s card issuer or payment provider refuses a payment. Payments can also fail because Stripe blocks them or because an API request is invalid. Each case needs a different response:

- [Issuer declines](https://docs.stripe.com/declines/how-declines-work.md#issuer-declines)
- [Blocked payments](https://docs.stripe.com/declines/how-declines-work.md#blocked-payments)
- [Invalid API calls](https://docs.stripe.com/declines/how-declines-work.md#invalid-api-calls)

Review a payment’s details in the [Dashboard](https://dashboard.stripe.com/payments). If the payment has a `Charge` object, inspect its [outcome](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) in the API for the failure type and cause. If Stripe rejects a request before creating a payment, inspect the API error response instead.

To track declines over time, use [Acceptance analytics](https://dashboard.stripe.com/acceptance) in the Dashboard. Select **Deduplicated** to group retries and calculate acceptance rates from each group’s final outcome. See [raw and deduplicated rates](https://docs.stripe.com/payments/analytics/acceptance.md?payment-attempt=deduplicated-rate#specify-raw-rate-deduplicated-rate) for how this changes your analysis.

## Issuer declines 

When your customer’s card issuer or payment provider receives a charge, their automated systems and models decide whether to authorize it. These tools analyze signals such as spending habits, account balance, and card data (expiration date, address information, and CVC).

Stripe handles non-card payment method declines similarly to card declines. Stripe sends you a response code that includes information about the decline, for example, if it’s due to insufficient funds, a lost or stolen card, or another reason.

If the card issuer or payment provider declines a payment, Stripe shares with you the decline information it receives through [Stripe decline codes](https://docs.stripe.com/declines/codes.md). This information is available in the Dashboard and through the API.

When issuers provide specific explanations, such as an incorrect card number or low funds, these explanations return to Stripe as [network decline codes](https://docs.stripe.com/declines/network-codes.md).

For example, this `Charge` outcome shows an issuer decline for an expired card. The `type` identifies an issuer decline, and the `reason` gives the Stripe decline code:

```json
...
"outcome": {
  "network_decline_code": "54",
  "network_advice_code": "03",
  "network_status": "declined_by_network",
  "reason": "expired_card",
  "advice_code": "confirm_card_data",
  "risk_level": "normal",
  "seller_message": "The bank returned the decline code `expired_card`.",
  "type": "issuer_declined"
},
...
```

## Blocked payments 

*Stripe Radar* (Stripe Radar helps detect and block fraud by using machine learning. It's built into Stripe and requires no additional setup to get started) blocks high risk payments, including those that violate your custom rules or have high risk scores. This automated fraud prevention product evaluates each payment, without requiring any action from you.

When Stripe blocks a payment, it doesn’t obtain authorization from the card issuer. This precaution helps prevent potential fraudulent payments that might lead to disputes.

For some card types, customers might see the card issuer’s authorization for the payment amount on their statement. However, Stripe hasn’t charged this amount or withdrawn funds. The card issuer typically removes this authorization from the customer’s statement within a few days.

If a rule you configured blocks a payment you recognize as legitimate, you can lift the block by locating the payment in the Dashboard and clicking **Add to allow list**. This action doesn’t retry the payment. Instead, it overrides all of your other rules from blocking future payment attempts that match the list attribute.

> If you don’t see **Add to allow list** on the payment details page, [contact Stripe](https://support.stripe.com/email) to add this feature to your Radar account.

When using the API, the `outcome` of a blocked payment reflects the type of payment failure and the reason for it, along with the evaluated risk level.

```json
...
"outcome": {
  "network_decline_code": null,
  "network_advice_code": null,
  "network_status": "not_sent_to_network",
  "reason": "highest_risk_level",
  "advice_code": "do_not_try_again",
  "risk_level": "highest",
  "seller_message": "Stripe blocked this charge as too risky.",
  "type": "blocked"
},
...
```

For users with [IC+ pricing](https://support.stripe.com/questions/understanding-blended-interchange-pricing), Adaptive Acceptance blocks certain payments to help you avoid unnecessary network costs. For example, Adaptive Acceptance helps you avoid excessive retry penalties. Adaptive Acceptance can also help you avoid network costs by blocking payments that have low likelihood of authorization.

```json
...
"outcome": {
  "network_decline_code": null,
  "network_advice_code": null,
  "network_status": "not_sent_to_network",
  "reason": "low_probability_of_authorization",
  "advice_code": "do_not_try_again",
  "risk_level": "normal",
  "seller_message": "Stripe blocked this payment as it is unlikely to be authorized.",
  "type": "blocked"
},
...
```

## Invalid API calls 

Invalid API calls can fail because of missing or invalid parameters, or because an operation isn’t allowed in the object’s current state. Stripe returns an `invalid_request_error` with details about the request. For example, this error response excerpt indicates a missing required parameter:

```json
{
  "error": {
    "code": "parameter_missing",
    "type": "invalid_request_error"
  }
}
```

Use the error’s `code`, `message`, and `param`, when present, to identify what to fix. See [invalid request errors](https://docs.stripe.com/error-handling.md#invalid-request-errors) and the [error code reference](https://docs.stripe.com/error-codes.md#parameter-missing) for guidance. [Test your integration](https://docs.stripe.com/testing.md) to catch invalid requests before accepting payments.

If validation fails before Stripe creates a `Charge`, inspect the API error response because no `Charge` outcome exists. Separately, an invalid payment attempt that creates a `Charge` can have the following outcome:

```json
...
"outcome": {
  "network_decline_code": null,
  "network_advice_code": null,
  "network_status": "not_sent_to_network",
  "type": "invalid"
},
...
```

## See also

- [Card declines](https://docs.stripe.com/declines/card.md)
- [Test declined payments](https://docs.stripe.com/testing.md#declined-payments)
- [Refund and cancel payments](https://docs.stripe.com/refunds.md)
