Fixes
Stripe errors and fixes
Webhooks that fail or don’t update your database, subscriptions and access, Checkout, the customer portal, Apple Pay and Google Pay, and test versus live mode. Each page is checked against Stripe’s own docs and says what to try first.
51 Stripe fixes. Also see Payments and integrations.
Guide to these errors in one place: Stripe payment, webhook and subscription errors.
- Stripe webhook errorNo signatures found matching the expected signature for payloadUsually it’s the wrong signing secret. Each endpoint has its own, the Stripe CLI prints a different one, and the same endpoint has a different secret for test and live keys. Next most likely: your framework parsed or changed the request body before the signature check ran.
- Stripe fulfillment bugThe payment went through in Stripe, but the account was never upgradedMost often, the upgrade only runs on the success page after checkout. Stripe says you can’t rely on that page, because customers don’t always reach it. Grant access from a webhook instead, and check the webhook’s delivery log in the Dashboard for failed deliveries.
- Stripe Billing errorWhy is my Stripe subscription stuck as incomplete?A new subscription stays incomplete until its first invoice is paid, and the customer has 23 hours. If the PaymentIntent says requires_action, the card needs authentication: listen for invoice.payment_action_required, send the customer through it with stripe.handleNextAction, and give access only after invoice.paid or an active subscription. After 23 hours it becomes incomplete_expired and you need a new subscription.
- Stripe payment errorWhy does Stripe say the card was declined with generic_decline?Stripe’s docs say card issuers categorize most declines as generic, so the exact decline reason is often unclear. Check the payment in the Dashboard: if Radar blocked it, the outcome type is blocked and you can allow-list a legitimate payment; if the issuer declined it, read the decline code and the advice code, ask the customer to re-enter the card or use another one, and don’t keep retrying a charge the advice code says not to.
- Stripe BillingStripe subscription canceled, but access in the app is wrongWhen a customer cancels at period end, the subscription runs on until the period ends, cancel_at_period_end becomes true, and Stripe sends customer.subscription.updated. Access should continue until the period ends. When it ends, Stripe sends customer.subscription.deleted: that’s the event that should remove access. Removing access on the update cuts people off early; ignoring the deleted event never removes it.
- Stripe BillingThe Stripe customer portal isn’t workingSave the portal settings in the Dashboard for live mode as well as sandboxes, since each has its own. Create a new portal session on your server each time a signed-in customer clicks the button, because session links are short-lived, and pass a return_url unless a default is set. Then listen to subscription webhooks so the app follows what customers change.
- Stripe Billing errorStripe: “This customer has no attached payment source or default payment method”For a subscription invoice, Stripe uses the subscription’s default_payment_method; if that isn’t set, it uses the customer’s invoice_settings.default_payment_method or default_source. The error means none of them gave it a payment method to charge. Set the card as the customer’s invoice_settings.default_payment_method, and for new subscriptions set payment_settings.save_default_payment_method to on_subscription.
- Stripe go-live problemStripe checkout works in test mode but fails in live modeTest mode (Stripe now calls it a sandbox) and live mode have separate API keys, products, prices, customers and webhook endpoints, and nothing created in one exists in the other. Put the live keys in your production app’s settings, recreate your products and prices in live mode and switch their IDs in your code, add a live webhook endpoint with its own signing secret, then redeploy.
- Stripe webhook problemStripe shows the webhook delivered, but my database never updatedA 200 only means your endpoint received the event. Stripe asks you to answer quickly, before the slow work, so if the database write fails after that, Stripe still records a successful delivery and has nothing to retry. Your own server logs hold the error. Check them first, then the event types your endpoint receives, repeated or out-of-order events, and the database key your handler writes with.
- Stripe Connect errorStripe Connect: the seller finished onboarding, but charges or payouts are still disabledComing back to your return URL doesn’t mean onboarding is complete. Retrieve the account and read its requirements: as long as requirements.currently_due isn’t empty, it can be restricted. Send the seller back through a new Account Link when anything is due, create a fresh link from your refresh URL when one expires, and listen to account.updated so new requirements don’t surprise you.
- Stripe payments problemStripe: Apple Pay or Google Pay doesn’t show in the payment formRegister every domain and subdomain that shows the payment form on the Payment method domains page, in live mode as well as each sandbox. If the form sits in an iframe, register both domains. Then confirm the wallets are on in your Payment Method Configurations, and test on a device with a real card in the wallet, outside a private window.
- Stripe go-live errorStripe: “Invalid API Key provided”Check the key your production server actually sends. It must be a secret key (sk_live_) or a restricted key (rk_live_) from the Stripe account you mean, copied whole, and not one that was rolled or deleted. Copy the current key from the Dashboard into your host’s production environment variables, redeploy, and never put it in front-end code.
- Stripe payment errorStripe: “Your card has insufficient funds” (insufficient_funds)If the decline_code is insufficient_funds, the customer’s bank said no. Nothing in your code is broken: show a clear message and let them pay with another card or method. If the error code is balance_insufficient, or a refund is stuck as pending, your own available Stripe balance is too low: wait for pending funds to become available (or top up if a refund is pending), then retry.
- Stripe decline codeStripe: “The card doesn’t support this type of purchase” (card_not_supported)Don’t retry the same card. Show a message that asks the customer to use another card or payment method, or to contact their bank, and keep checkout open for a second try. For a renewal, ask the customer to update the saved card. If many customers hit it, look for a pattern in the declined payments in the Dashboard.
- Stripe Checkout errorStripe: “This Checkout Session has expired”Create a new Checkout Session each time the customer clicks to pay, and redirect to its URL straight away instead of storing or emailing that URL. Set expires_at if you need a shorter window. To win back customers whose session ran out, enable after_expiration.recovery and listen for the checkout.session.expired webhook.
- Stripe API errorStripe: payment_intent_authentication_failure (3D Secure failed)Catch the error after confirmPayment, show a message that the bank couldn’t confirm the payment, and keep the same PaymentIntent so the customer can try again or enter another card. For redirect flows, read the PaymentIntent on your return page and check for requires_payment_method. Test it with card 4000000000003220 and the Failure button.
- Stripe decline codeStripe: card declined with authentication_requiredCatch the decline, keep the PaymentIntent it returns, and email or notify the customer with a link to a page that calls confirmPayment with that PaymentIntent’s client secret. The bank then shows its check and the payment can succeed. If the same code comes back after a passed check, the customer has to call the bank.
- Stripe decline codeStripe: card declined with do_not_honorShow the customer a plain message that the bank declined the card and ask them to contact the bank or try another card. In the Dashboard, check the payment’s CVC and address checks and the advice code. Don’t retry the same card in a loop, because card networks limit how often one charge can be retried.
- Stripe decline codeStripe: incorrect_cvc (the card’s security code is incorrect)Catch the error after confirmPayment, check for code incorrect_cvc, and show a message on the CVC field instead of a generic decline. Keep the same PaymentIntent so the retry goes through the same payment. In tests, enter a CVC, because Stripe skips the check when it is empty, and use test card 4000000000000127 to see the decline.
- Stripe decline codeStripe: expired_card (the card has expired)Check error.code for expired_card, show a message that the card has expired, and ask for another one, keeping the same PaymentIntent. For renewals, send the customer to a page where they can replace the card, such as the Stripe customer portal, then pay the open invoice with stripe.invoices.pay. A wrong expiry typed at checkout returns invalid_expiry_month or invalid_expiry_year instead, which a retry with the right date fixes.
- Stripe decline codeStripe: processing_error (an error occurred while processing the card)Show a message that the payment didn’t go through and offer a retry with the same PaymentIntent. If it fails a second time, suggest another card. On the server, reuse an idempotency key only when you repeat the same request after a timeout, and use a new key for a new attempt. For subscriptions, Smart Retries or your retry schedule will try the renewal again.
- Stripe decline codeStripe: card_velocity_exceeded (card limit reached)Show a clear message that asks for another card or for the customer to contact the bank. Don’t retry the same card in a loop. For subscriptions, let your retry schedule try again later and email the customer a link to update the card.
- Stripe decline codeStripe: incorrect_zip (billing postal code didn’t match)Show a message that asks for the billing ZIP of the card, not the shipping address. Check that your form sends the postal code field the customer typed, and doesn’t prefill it from the shipping address or a profile. Then let the customer try again.
- Stripe decline codeStripe: lost_card and stolen_card declinesShow a generic “Your card was declined” message and ask for another payment method. Don’t reveal the lost or stolen reason, and don’t retry the card. Log the decline code for your own review, and check whether the account shows other signs of card testing.
- Stripe decline codeStripe: card declined, decline code fraudulentShow the same message as a generic decline and don’t retry the same card. Open the payment in the Dashboard and read the Radar outcome and risk insights. If many fraudulent declines arrive in a short time, treat it as card testing and add rate limits or a CAPTCHA to checkout.
- Stripe decline codeStripe: card declined, currency_not_supportedTell the customer the card can’t pay in this currency and ask for another card or payment method. A bad currency code gives an API error, not this decline. If many customers in one country hit it, offer their local currency, if your account supports it, or another payment method.
- Stripe BillingStripe: subscription stuck in past_dueListen for invoice.payment_failed and email the customer a link to update their card. Update the payment method on the field Stripe charges, then pay the open invoice. In Dashboard settings, choose what happens after the last retry: cancel, mark unpaid, or stay past_due.
- Stripe BillingStripe: a payment was disputed (chargeback)Open the dispute in the Dashboard and note the reason and the due date. If the customer is right, accept it. If not, gather evidence that matches the reason, such as receipts, login records and emails, and submit it all at once. Handle charge.dispute.created so you never miss a deadline.
- Stripe card errorStripe: incorrect_number, the card number is incorrectShow Stripe’s error message next to the card field and let the customer type the number again or pick another card. Collect cards with Stripe Elements or Checkout, which check the number as it is typed. Don’t retry the same card automatically.
- Stripe BillingStripe: webhook events fail to deliver to your endpointOpen the endpoint’s Event deliveries tab and read the status: a redirect, a 4xx, a 5xx, a TLS error or a timeout. Fix that, return 200 before slow work, then list events with delivery_success set to false and process what you missed.
- Stripe payout errorStripe: payout failedOpen the payout in the Dashboard, or read failure_code and failure_message from the API. Re-enter the bank details, or add a new account if the old one is closed. Stripe tries again at the next scheduled payout. If the details are right, contact the bank, then click Resume Payouts.
- Stripe errorStripe: setup_intent_authentication_failureShow the customer that the card could not be verified, and let them try again or enter another card on the same SetupIntent. Don’t save the payment method or start the subscription until the SetupIntent succeeds. In test mode, check the flow with the always-authenticate test card.
- Stripe payment errorStripe: charge_expired_for_captureThe held money is gone, so ask the customer to pay again, or charge a saved payment method with a new PaymentIntent if the customer agreed to that. Then fix the timing: store capture_before for each authorized charge and capture before it, or request an extended authorization when creating the PaymentIntent, where the card is eligible.
- Stripe Payments errorStripe: card_decline_rate_limit_exceededFor one customer, ask them to check their card details or use another card; the same card can be tried again after 24 hours. If many cards fail at once, check for card testing: refund suspicious payments, move to Stripe Checkout or the latest Payment Element, and limit how often your own endpoint can create payments.
- Stripe Billing errorStripe: invoice_payment_intent_requires_actionGet the PaymentIntent on the invoice and have the customer complete it on your site, for example by confirming it with Stripe.js while they are present. For off-session renewals, turn on “Send a Stripe-hosted link for customers to confirm their payments when required” in the Billing email settings.
- Stripe API errorStripe: stripe_tax_inactiveOpen the tax settings page in the Dashboard for the same account the secret key belongs to, click Get started, confirm the head office address, preset tax code and default tax behavior, and add a registration for each place the business is registered to collect tax. Then retry the request with automatic_tax.enabled=true. Existing invoices, subscriptions and payment links need automatic tax turned on one by one.
- Stripe API errorStripe: capability_not_activeRead the capabilities array in the error response to see which capability is missing. Retrieve that capability for the account and check its status and requirements. Request it if it is unrequested, collect everything listed in currently_due and past_due from the connected account, and retry once the status is active.
- Stripe API errorStripe: payment_method_not_availableShow the customer a clear message and offer another payment method, or retry later with the same one. If the server sends an idempotency key, a retry with the same key can return Stripe’s cached response (look for the Idempotent-Replayed: true header) instead of attempting the payment again.
- Stripe Connect errorStripe: payouts_not_allowedRetrieve the connected account and check payouts_enabled and the requirements hash. If requirements are currently_due or past_due, collect that information from the account holder and update the account. Watch account.updated events so the platform knows when payouts are enabled again.
- Stripe payment errorStripe: charge_exceeds_transaction_limitThis is an account limit, not a bug in your code. Contact Stripe Support to request a higher processing limit for the payment method in the error. Until it is raised, offer customers another payment method, such as a card, for payments that hit the limit, and show them a clear message instead of a generic failure.
- Stripe Payments errorStripe: refund_disputed_paymentLook up the dispute for the payment. To give the customer the money back, accept the dispute, which closes it in their favor. To fight it, submit evidence. Before any automatic refund, check the charge’s disputed flag, and handle the refund failure reason that appears when a dispute lands while a refund is still pending.
- Stripe Payments errorStripe: testmode_charges_onlyOpen the Stripe Dashboard with the account that owns the live key and finish setting up the account: verify the business and complete the account checklist. Answer any extra verification request. Until that is done, use test keys and test cards, and keep live keys out of the app.
- Stripe Payments errorStripe: balance_insufficientRetrieve the balance and use the available amount, in the right currency, as the limit for the transfer or payout. Funds from recent payments sit in pending until they become available. For Connect transfers paid from a specific charge, set source_transaction: the transfer goes through right away, and the seller can use the money once the charge’s funds become available.
- Stripe Payments errorStripe: api_key_expiredOpen the API keys page in the Dashboard and get the current key. In live mode Stripe shows a secret or restricted key only once, so if nobody saved it, rotate or create a new one. Then replace the old key in every place that sends it: the server environment, background jobs, webhook handlers and any no-code tools. Redeploy so the new value loads. If the code is platform_api_key_expired, see the Connect platform cause below.
- Stripe Payments errorStripe: payment_method_unactivatedTurn the payment method on in the Dashboard payment methods settings, in the same mode (test or live) and on the same account the code uses. Better still, stop listing payment_method_types in code and let the Dashboard decide which methods show, so the two can’t drift apart.
- Stripe ACH errorStripe: bank_account_verification_failedCheck which failure it was. If the customer ran out of attempts, ask for a different bank account, because Stripe says that one can no longer be verified or reused. If the deposits never arrived or the 10 days ran out, collect the bank details again. To skip microdeposits where possible, verify instantly with Financial Connections.
- Stripe checkout problemWhy did Stripe charge my customer twice?If it is one order, your checkout created a second payment for it. This can happen when the customer presses Pay twice, reloads the payment page, or your server retries a request. Refund the duplicate in the Stripe Dashboard, then fix the cause: create one PaymentIntent per order and reuse it, send an idempotency key based on the order ID with every create request, and disable the Pay button while a payment is in progress.
- Stripe Dashboard statusWhy do my Stripe payments say “Incomplete”?Incomplete means the payment has not finished: it still needs a payment method, a confirmation, or an action from the customer such as a 3D Secure check. Some are expected, because Stripe advises creating the payment as soon as checkout starts, so customers who leave are recorded too. Open a few, check the exact status in Workbench Inspector, and look for a pattern: many stuck at requires_action, or many with the same decline, point to something worth fixing.
- Stripe Billing problemWhy did Stripe charge a customer after they cancelled?Open the customer in the Stripe Dashboard and check three things: that the subscription itself shows as canceled, that the customer has no second active subscription, and whether the charge is a final invoice for prorations or pending invoice items. If the cancel only happened inside your app, Stripe never heard about it. Refund the payment from the Payments page, then fix the cancel flow so it cancels in Stripe.
- Stripe payments problemWhy aren’t my customers getting Stripe receipts?In the Dashboard, open Settings, then Business, then Customer emails, and turn on Successful payments. Then check that each payment has an email address, either a receipt email on the payment or an email on the Stripe Customer. Stripe sends no automatic receipt for test payments, and none for payments that failed. To send one by hand, open a successful payment, go to Receipt history, click the overflow menu and select Send receipt.
- Stripe Billing problemWhy did Stripe charge a customer when their free trial ended?A Stripe trial moves to the regular price automatically when it ends, and a card saved at signup is charged. To stop surprises, turn on the trial ending reminder email, make sure cancelling in your app cancels in Stripe, and for trials that take no card, choose to cancel or pause the subscription at the end instead of invoicing. Refund the payment from the Payments page if the customer didn’t mean to stay.
Looking for another platform? See the other fixes.
A different Stripe error?
Describe it and get a written quote
Send the error and what you were doing. You get a written scope, a fixed price and a timeline; Simon replies by email, usually within one business day.