Declines

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.

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, working 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

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. 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.

Blocked payments

Stripe Radar 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.

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

For users with IC+ 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.

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

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

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_...:" \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_chargeDeclinedIncorrectCvc \
  -d confirm=true

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

{
  "error": {
    "code": "incorrect_cvc",
    "doc_url": "https://docs.stripe.com/error-codes#incorrect-cvc",
    "message": "Your card's security code is incorrect.",
    "param": "cvc",
    "type": "card_error"
  }
}

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

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

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