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:

ReasonMeaning
card_declinedThe issuer declined and gave no more specific reason.
insufficient_fundsNot enough money or credit on the card.
expired_cardThe card has expired.
incorrect_card_detailsA wrong number, CVC, expiry, postal code or PIN.
authentication_failed3D Secure or another check by the bank failed or was cancelled.
card_not_supportedThe card cannot pay for this kind of purchase or in this currency.
limit_exceededThe card hit a spending, frequency or PIN-attempt limit.
fraud_suspectedThe issuer or Stripe flagged the payment, or the card is lost or stolen.
processing_errorThe issuer or the network failed; trying again may work.
unknownNobody 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:

FieldTypeMeaning
reasonCheckoutFailureReasonWhy it failed, from the table above.
store"stripe"The store that refused the payment.
codestring, optionalThe store's own error code, such as Stripe's card_declined. Absent when the store sent none.
declineCodestring, optionalThe issuer's decline code, such as Stripe's insufficient_funds. Absent when the store sent none.
messagestring, optionalThe 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().failure holds the last purchase that failed, with status: "failed" and the product, and clears when the next purchase starts.
  • onFailure receives it, see Callbacks.

What each purchase path reports

Purchasefailure.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 appThe 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 SDKunknown: 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 SDKsuperseded as on iOS. Any other failure fires nothing: the Android SDK sends no failure message, see Purchases.
Custom store productNo 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:

CallbackFires whenPlatforms
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. onFailure fires on each decline, in order; purchase() waits and resolves completed if a later card pays, or failed with the latest failure if the shopper closes the sheet.
  • Teleport, in the app. onFailure fires as soon as the browser's payment fails, while the shopper can still try again there.
  • Teleport page. Calling useTeleport().returnToApp() from onFailure returns to the app with reason=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:

TypeWhat it is
CheckoutFailureReasonThe ten reasons above.
CheckoutFailurereason, store, code, declineCode, message.
WebCheckoutFailureA CheckoutFailure with status: "failed" and the product.
PurchaseFailureA WebCheckoutFailure or a store SuperwallPurchaseFailure; what onFailure and usePurchase().failure carry.
SuperwallPurchaseFailureA store purchase that failed: reason: "unknown" | "superseded".
PurchaseCallbacksThe five callbacks.
UsePurchaseOptionsWhat usePurchase() takes: the callbacks.
PurchaseOptionsWhat purchase() takes: checkout, prepaidCards, postPurchase, stripeMetadata and the callbacks.

How is this guide?

On this page