Stripe Status failed: Charge Failed
The Charge object status indicating the charge attempt was declined or failed. Common causes include insufficient funds, invalid card details, or issuer decline. The merchant should prompt the customer to try a different payment method.
What it means
The `failed` status on a Stripe Charge object is a top-level payment outcome indicating that the transaction attempt was unsuccessful and no funds were captured. This status acts as an umbrella classification covering issuer declines, gateway rejections, risk-based blocks, and API errors. Because it is a broad indicator, merchants must examine the accompanying `failure_code` and `outcome` fields within the API response to understand the precise reason the payment did not succeed.
Classification & retryability
Because a `failed` status is a generic indicator, retryability depends entirely on the underlying `failure_code`. Transient issues like `insufficient_funds` or a generic `do_not_honor` may succeed upon subsequent automated retries. Permanent failures such as `invalid_card_number` or `lost_card` must never be retried with the same payment method. Note that a failed Charge object cannot be re-opened; retries require generating an entirely new payment attempt or PaymentIntent.
Common causes
- The customer's issuing bank declined the transaction due to insufficient funds, an expired card, or a general refusal to honor the payment.
- Stripe's internal risk and compliance systems blocked the payment before it reached the card network due to suspected fraud.
- The API request used to create the charge was malformed or missing required parameters, resulting in an immediate technical failure.
- The customer submitted incorrect payment details, such as a wrong card number, an invalid CVV, or an incorrect expiration date.
How to resolve it
Resolving a `failed` charge requires evaluating the granular `failure_code` and `outcome.reason` provided within the Stripe Charge object. Once an attempt is marked as failed, it enters a terminal state and will never transition to `succeeded`. To recover the payment, your system must trigger a completely new transaction. For soft declines, you can place the transaction in an automated retry queue. For hard declines or invalid API requests, automated retries should be bypassed in favor of prompting the customer to update their payment information or correcting your system's API payload.
For merchants
Inspect the `failure_code` and `failure_message` associated with the `failed` charge to identify the specific root cause. Configure your backend to listen for the `charge.failed` webhook so you can systematically update local invoice statuses. Depending on the underlying code, route the transaction into a SmartRetry schedule for transient errors, or immediately email the customer requesting a new payment method for hard declines.
For customers
Review the checkout form to ensure the card number, expiration date, and CVV were entered accurately. Verify that the linked bank account or credit line has sufficient available funds. If the payment details are correct and funds are available, contact the issuing bank to authorize the transaction or provide an entirely different payment method to complete the purchase.