Declines

Payments can fail for a variety of reasons, including some that help prevent fraudulent transactions. Stripe works to reduce decline rates across all supported payment methods. We work with issuers and networks to improve acceptance rates, often without affecting your integration.

There are three reasons why a payment might fail:

• Issuer declines
• Blocked payments
• Invalid API calls

You need to handle each type of payment failure differently. For every failure, you can use the Dashboard or API to review a payment’s details. When using the API, look at the Charge object’s outcome. This attribute covers the payment failure type and provides information about its cause.

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.

Issuer declines

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

If the card issuer declines a payment, Stripe shares with you all the decline information we receive. 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 through decline codes.

Blocked payments

Stripe Radar blocks high risk payments, such as those with mismatched CVC or postal code values. This automated fraud prevention product evaluates each payment, without requiring any action from you.

A payment that Radar declined

When Stripe blocks a payment, it obtains initial authorisation from the card issuer but refrains from charging the card. This precaution helps prevent potential fraudulent payments that might lead to disputes.

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

If a rule you configured blocks a payment you recognise 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 your other rules from blocking future payment attempts that match the list attribute.

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.

...
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"
},
...

Invalid API calls

In the API, you might see an invalid API call like the following:

curl https://api.stripe.com/v1/charges \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=2000 \
  -d currency=usd \
  -d source=tok_invalid \
  --data-urlencode description="Charge for jenny.rosen@example.com"

The invalid API call generates an error response that might look like this:

{
  "error": {
    "code": "invalid_number",
    "doc_url": "https://docs.stripe.com/error-codes#invalid-number",
    "message": "Your card number is incorrect.",
    "param": "card[number]",
    "type": "card_error"
  }
}

The outcome of a declined payment includes the type of payment failure and the reason, based on the card issuer’s decline code. The reason might contain information other than the issuer’s response code, for example, if a Radar rule evaluation blocked the charge.

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

As you develop your Stripe integration, continuously test it to identify any potential bugs that might lead to invalid API calls. Invalid API calls typically don’t result in a payment appearing in your Dashboard. However, you might see the payment appear in a few cases.

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