Payment Failure Reasons
Learn why a web payment failed (card declined, insufficient funds, expired card) and react with purchase callbacks that work on every platform.
When a Stripe purchase fails, purchase() tells you why in Superwall's own words: card_declined, insufficient_funds, expired_card and so on. The same reasons come back whichever payment method took the payment, so a paywall can branch on them without knowing Stripe's error codes. Use them to show the right message, offer another way to pay, or send the shopper back to your app from a teleport page.
import { usePurchase } from "superwall/hooks";
const { purchase } = usePurchase();
const result = await purchase("annual");
const failure = "failure" in result ? result.failure : undefined;
if (failure?.reason === "insufficient_funds") {
setMessage("Your card was short on funds. Try another card or Apple Pay.");
}Requirements
- A Stripe product bought through web checkout: the embedded sheet, Apple Pay, the hosted checkout or a teleport.
- The exact reason comes from the payment itself. Where that payment ran out of reach of the page, the reason arrives once Superwall's backend reports it, see What each purchase path reports.
- App Store, Play Store and custom store purchases report no reason, see the same table.
The reasons
failure.reason is a CheckoutFailureReason, one of:
| Reason | Meaning |
|---|---|
card_declined | The issuer declined and gave no more specific reason. |
insufficient_funds | Not enough money or credit on the card. |
expired_card | The card has expired. |
incorrect_card_details | A wrong number, CVC, expiry, postal code or PIN. |
authentication_failed | 3D Secure or another check by the bank failed or was cancelled. |
card_not_supported | The card cannot pay for this kind of purchase or in this currency. |
limit_exceeded | The card hit a spending, frequency or PIN-attempt limit. |
fraud_suspected | The issuer or Stripe flagged the payment, or the card is lost or stolen. |
processing_error | The issuer or the network failed; trying again may work. |
unknown | Nobody reported why, or the store gave a reason Superwall does not know. |
unknown is never a guess. A reason nobody reported stays unknown, so treat it as "something went wrong", not as any one of the others.
What a failure holds
A failed web purchase carries a CheckoutFailure:
| Field | Type | Meaning |
|---|---|---|
reason | CheckoutFailureReason | Why it failed, from the table above. |
store | "stripe" | The store that refused the payment. |
code | string, optional | The store's own error code, such as Stripe's card_declined. Absent when the store sent none. |
declineCode | string, optional | The issuer's decline code, such as Stripe's insufficient_funds. Absent when the store sent none. |
message | string, optional | The store's message for the customer. Absent when the store sent none. |
Branch on reason. code, declineCode and message are Stripe's raw values, there for logging and for the rare case you need a code Superwall folds into a broader reason.
It reaches you in three places:
purchase()resolves{ status: "failed", product, failure }.usePurchase().failureholds the last purchase that failed, withstatus: "failed"and theproduct, and clears when the next purchase starts.onFailurereceives it, see Callbacks.
What each purchase path reports
| Purchase | failure.reason |
|---|---|
| Stripe product, Apple Pay on the web (hosted web paywall, Web SDK, teleport page) | The exact reason, from Stripe as the wallet confirms the payment. |
Stripe product, embedded sheet (checkout: "sheet") | The exact reason once Superwall's backend reports the checkout's last failed payment, unknown until then. A subscription checkout may still report unknown: Stripe may not expose the failed payment while the sheet is open. |
Stripe product, hosted checkout (external, and every Stripe purchase inside an iOS app without teleport) | Not a supported path for reasons: the shopper pays on Superwall's page, and the framework only learns what the backend reports while it waits. Plan for unknown. |
| Stripe product, teleport, seen from the app | The page's own reason when the page returns to the app after the failure; otherwise what the backend reports on the teleport, unknown until then. |
| App Store product in the iOS SDK | unknown: the SDK reports a failure with no detail. superseded when a newer purchase of the same product, or a reopened paywall, replaced it. |
| Play Store product in the Android SDK | superseded as on iOS. Any other failure fires nothing: the Android SDK sends no failure message, see Purchases. |
| Custom store product | No reason and no callbacks. |
A store failure is a SuperwallPurchaseFailure (exported from superwall) with reason: "unknown" | "superseded" and no store field; a web failure is a WebCheckoutFailure. Both are a PurchaseFailure, so check "store" in failure before reading code or declineCode.
Callbacks
usePurchase takes five callbacks, each optional:
| Callback | Fires when | Platforms |
|---|---|---|
onStart(product) | The purchase started. | All |
onSubmit(product) | The shopper submitted payment in the sheet or authorized it in Apple Pay. | Web checkout only: the native SDKs do not report it |
onComplete(product) | The purchase was paid. | All |
onAbandon(product) | The shopper left the checkout or the store's sheet without paying. | All |
onFailure(failure) | A purchase failed, with why in failure.reason. | All |
They fire for App Store and Play Store products bought through the native SDK and for Stripe products bought on the web: the embedded sheet, Apple Pay, the hosted checkout and a teleport. Custom store products fire none of them.
Pass them in two places:
// Every purchase on the paywall, whichever component started it.
const { purchase } = usePurchase({
onFailure: (failure) => track("purchase_failed", { reason: failure.reason }),
});
// Only this one purchase, beside any passed to usePurchase.
await purchase("annual", {
onSubmit: () => setStatus("Processing…"),
onFailure: (failure) => setMessage(messageFor(failure.reason)),
});usePurchase(options)fires for every purchase on the paywall, from any component.purchase(product, options)fires only for that call's purchase, and only while it is in flight.
A few timings to know:
- Embedded sheet. A decline keeps the sheet open so the shopper can try another card.
onFailurefires on each decline, in order;purchase()waits and resolvescompletedif a later card pays, orfailedwith the latest failure if the shopper closes the sheet. - Teleport, in the app.
onFailurefires as soon as the browser's payment fails, while the shopper can still try again there. - Teleport page. Calling
useTeleport().returnToApp()fromonFailurereturns to the app withreason=failed, see Teleport.
A callback that throws is logged and does not stop the others.
Show a message per reason
import type { CheckoutFailureReason } from "superwall/hooks";
const MESSAGES: Record<CheckoutFailureReason, string> = {
card_declined: "Your card was declined. Try another card.",
insufficient_funds: "Your card was short on funds. Try another card or Apple Pay.",
expired_card: "That card has expired.",
incorrect_card_details: "Check the card number, expiry and CVC.",
authentication_failed: "Your bank couldn't confirm the payment. Try again.",
card_not_supported: "That card can't pay for this. Try another one.",
limit_exceeded: "Your card hit a limit. Try another card.",
fraud_suspected: "Your bank blocked this payment. Try another card.",
processing_error: "Something went wrong with the payment. Try again.",
unknown: "The payment didn't go through. Try again.",
};
const { failure } = usePurchase();
const reason = failure && "store" in failure ? failure.reason : undefined;
{reason && <p role="alert">{MESSAGES[reason]}</p>}Typing the map as Record<CheckoutFailureReason, string> makes TypeScript flag a reason you forgot.
Types
All from superwall/hooks, except SuperwallPurchaseFailure, which comes from superwall:
| Type | What it is |
|---|---|
CheckoutFailureReason | The ten reasons above. |
CheckoutFailure | reason, store, code, declineCode, message. |
WebCheckoutFailure | A CheckoutFailure with status: "failed" and the product. |
PurchaseFailure | A WebCheckoutFailure or a store SuperwallPurchaseFailure; what onFailure and usePurchase().failure carry. |
SuperwallPurchaseFailure | A store purchase that failed: reason: "unknown" | "superseded". |
PurchaseCallbacks | The five callbacks. |
UsePurchaseOptions | What usePurchase() takes: the callbacks. |
PurchaseOptions | What purchase() takes: checkout, prepaidCards, postPurchase, stripeMetadata and the callbacks. |
Related
- Purchases: the three outcomes and restoring.
- Web Checkout: modes, Apple Pay and the hosted checkout.
- Teleport: send the shopper back to the app after a failed payment.
- Hooks reference:
usePurchasein full.
How is this guide?