Understanding Declines and Failed Payments

    Learn why some payments fail and what you can do to decrease your decline rate. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

    Payments can fail for a variety of reasons and it’s frustrating whenever they represent a loss of legitimate business. Certain failures are actually preventative measures–working to minimize the possibility of a fraudulent payment that otherwise may have resulted in a dispute.

    There are three possible reasons why a payment might fail, and there is a different way of handling each failure. The reason for a payment’s failure is provided within the payment’s details in the Dashboard and through the API as part of the Charge object’s outcome. This parameter includes the type of payment failure, along with additional information about the reason for it.

    Bank-declined payments

    When a charge is submitted to the bank or card issuer of your customer’s card, they have automated systems that determine whether or not to authorize it. These systems take various signals into account, such as your customer’s spending habits, account balance, and card information like the expiration date and CVC.

    If your customer’s bank or card issuer declines a payment, Stripe shares with you as much information explaining the decline as we receive, both within the Dashboard and through the API. In some cases, banks also provide helpful explanations, such as the card number or expiration date being incorrect, or that the customer does not have enough funds available to make the payment. The bank may provide one of these more specific reasons to Stripe through the use of a decline code.

    Unfortunately, most declines are categorized as “generic” so it’s not always possible to know exactly why a payment was declined. If all of the card information seems correct, it is best to have your customer contact their bank and ask for more information. For privacy and security, banks and card issuers can only discuss the specifics of a declined payment with their cardholders–they cannot discuss this with the merchant.

    Through the API, the outcome of a bank-declined charge contains the type of payment failure that’s occurred and provides the reason using the decline code received by the bank:

    ...
    outcome:
    {
      network_status: "declined_by_network"
      reason: "expired_card"
      risk_level: "normal"
      seller_message: "The bank returned the decline code `expired_card`."
      type: "issuer_declined"
    },
    ...
    

    Reducing bank declines

    Bank declines arising from incorrect card information (e.g., incorrect card number or expiration date) are best handled by guiding your customer to correct the error or even using another card or payment method. For instance, Checkout can provide feedback to the customer if the card they’re attempting to use is declined, allowing them to try again or use an alternative payment method.

    Banks’ suspicions of fraudulent activity are more challenging to manage, but having customers provide the CVC and ZIP code when checking out can significantly decrease the number of declines you’re experiencing. The influence of other data that you collect, like the full address, varies by card brand and country. If you are still experiencing a higher-than-expected number of declined payments, consider collecting this additional data.

    Blocked payments

    Stripe’s automated fraud prevention toolset, Radar, blocks any payments that we identify as being high-risk. Radar can help you most effectively combat fraud, with features such as rules that block payments if the CVC or ZIP code doesn’t match the information on file with your customer’s bank.

    Using the API, the outcome of a blocked payment reflects the type of payment failure and the reason for it, along with the risk level that was evaluated.

    ...
    outcome:
    {
      network_status: "not_sent_to_network"
      reason: "highest_risk_level"
      risk_level: "highest"
      seller_message: "Stripe blocked this charge as too risky."
      type: "blocked"
    },
    ...
    

    Invalid API calls

    As you develop your Stripe integration, good testing should identify any potential bugs that would lead to invalid API calls. Consequently these failures should be rare in production. Invalid API call typically don’t result in a payment appearing in your Dashboard. However, in a few edge cases you may see the payment appear.

    ...
    outcome:
    {
      network_status: "not_sent_to_network"
      type: "invalid"
    },
    ...
    

    Managing payment failures programmatically

    If you would like your integration to respond to payment failures automatically, you can access a charge’s outcome in two ways.

    • Handle the API error returned when a payment fails. For blocked and bank-declined payments, the error includes the charge’s ID, which you can then use to retrieve the charge

    • Make use of webhooks to listen for event notifications. When a payment fails, the charge.failed event is triggered, containing the Charge object

    When developing your integration, we recommend writing code that gracefully handles all possible API exceptions, including unanticipated errors.

    Bank decline codes

    If a payment is declined by the bank or card issuer, the bank may provide a decline code with a more detailed reason. Below is a list of possible decline codes that can be returned.

    Decline Code Explanation Next Steps
    approve_with_id The payment cannot be authorized The payment should be attempted again. If it still cannot be processed, the customer needs to contact their bank.
    call_issuer The card has been declined for an unknown reason The customer needs to contact their bank for more information.
    card_not_supported The card does not support this type of purchase The customer needs to contact their bank to make sure their card can be used to make this type of purchase.
    card_velocity_exceeded The customer has exceeded the balance or credit limit available on their card. The customer should contact their bank for more information.
    currency_not_supported The card does not support the specified currency. The customer needs check with the issuer that the card can be used for the type of currency specified.
    do_not_honor The card has been declined for an unknown reason The customer needs to contact their bank for more information.
    do_not_try_again The card has been declined for an unknown reason The customer should contact their bank for more information.
    fraudulent The payment has been declined as the issuer suspects it is fraudulent The customer should contact their bank for more information.
    generic_decline The card has been declined for an unknown reason The customer needs to contact their bank for more information.
    insufficient_funds The card has insufficient funds to complete the purchase The customer should use an alternative payment method.
    invalid_account The card, or account the card is connected to, is invalid The customer needs to contact their bank to check that the card is working correctly.
    invalid_amount The payment amount is invalid, or exceeds the amount that is allowed If the amount appears to be correct, the customer needs to check with their bank that they can make purchases of that amount.
    invalid_pin The PIN entered is incorrect. This decline code only applies to payments made with a card reader. The customer should try again using the correct PIN.
    issuer_not_available The card issuer could not be reached, so the payment could not be authorized The payment should be attempted again. If it still cannot be processed, the customer needs to contact their bank.
    lost_card The payment has been declined because the card is reported lost The specific reason for the decline should not be reported to the customer. Instead, it needs to be presented as a generic decline.
    new_account_information_available The card, or account the card is connected to, is invalid The customer needs to contact their bank for more information.
    no_action_taken The card has been declined for an unknown reason The customer should contact their bank for more information.
    not_permitted The payment is not permitted The customer needs to contact their bank for more information.
    pickup_card The card cannot be used to make this payment (it is possible it has been reported lost or stolen) The customer needs to contact their bank for more information.
    reenter_transaction The payment could not be processed by the issuer for an unknown reason. The payment should be attempted again. If it still cannot be processed, the customer needs to contact their bank.
    restricted_card The card cannot be used to make this payment (it is possible it has been reported lost or stolen) The customer needs to contact their bank for more information.
    revocation_of_all_authorizations The card has been declined for an unknown reason The customer should contact their bank for more information.
    revocation_of_authorization The card has been declined for an unknown reason The customer should contact their bank for more information.
    security_violation The card has been declined for an unknown reason The customer needs to contact their bank for more information.
    service_not_allowed The card has been declined for an unknown reason The customer should contact their bank for more information.
    stolen_card The payment has been declined because the card is reported stolen The specific reason for the decline should not be reported to the customer. Instead, it needs to be presented as a generic decline.
    stop_payment_order The card has been declined for an unknown reason The customer should contact their bank for more information.
    testmode_decline A Stripe test card number was used A genuine card must be used to make a payment.
    transaction_not_allowed The card has been declined for an unknown reason The customer needs to contact their bank for more information.
    try_again_later The card has been declined for an unknown reason Ask the customer to attempt the payment again. If subsequent payments are declined, the customer should contact their bank for more information.
    withdrawal_count_limit_exceeded The customer has exceeded the balance or credit limit available on their card. The customer should use an alternative payment method.