Skip to main content

Error Handling

Every error reaches your integration as a CheckoutError through onError, and render() rejects with one when the failure prevents mounting.

const { Checkout, CheckoutError } = await import(
'https://{cdn_host}/v1/main.js'
);

onError: (error) => {
if (error.userMessage) showToBuyer(error.userMessage);
else console.error(error.code, error.message, error.details);
}

CheckoutError extends Error and exposes:

PropertyTypeDescription
codestringOne of the codes below. This is what you switch on
messagestringTechnical description, for your logs
userMessagestring (optional)The buyer-facing text, already translated and with the merchant's configured copy applied. Show this one
detailsunknownExtra context. For BFF failures it carries the exact message_code and HTTP status
toJSON()() => { code, message, userMessage, details }Serializable payload

Which message the buyer sees is your decision​

The component hands you the text already resolved and does not draw it inside its iframe by default — the buyer-facing message normally belongs with the rest of your checkout's messages.

onError: (error) => {
// Already translated, with the merchant's configured copy applied.
if (error.userMessage) return showToBuyer(error.userMessage);

// No `userMessage` means the error is for you, not for the buyer: a mount timeout, a module
// this version cannot show, an `unmount()` in the middle of a render.
console.error(error.code, error.message);
}

Set errorDisplay: 'inline' if you want the component to draw it too — same text, so the two cannot disagree.

Two things the component always draws itself, because they cannot live outside it: per-field validation errors, which sit next to their input inside the iframe, and the panel that replaces the form when the session dies. Both still reach onError.

Codes, grouped by what to do about them​

What to doCodes
Ask your backend for a new session. The session does not exist, expired (15 min TTL) or was already usedSESSION_INVALID
Fix the integration. These show up while developing, not in productionSESSION_ID_INVALID, RENDER_FAILED
Ignore. The component was torn down before it finished mountingRENDER_ABORTED
Show the error and let the buyer retry. The form stays mounted and usable, and already carries a userMessageVALIDATION_FAILED, PAYMENT_INTENT_FAILED, ENCRYPTION_FAILED, TOKENIZATION_FAILED, TOKENIZATION_TIMEOUT
Retry, or report the service as unavailable. Not the card: something in the infrastructure failedSERVICE_UNAVAILABLE, NETWORK_ERROR, CONFIG_FETCH_FAILED, INIT_FAILED, MODULE_MOUNT_FAILED
Mount the component again with the same session, or tell the buyer. The bot-protection check failed and the component has already closed itself; the session is still usable. The first is the backend's verdict, the second the browser's (a blocker, the network)CAPTCHA_REJECTED, CAPTCHA_UNAVAILABLE
Review the merchant configuration. CONFIG_INVALID lists everything missing in details.missingMODULE_UNKNOWN, NO_MODULES_AVAILABLE, CONFIG_INVALID
Report it: the BFF did not return the public key, so the tenant is misconfiguredPUBLIC_KEY_INVALID
Update the component: the session uses a checkout mode this version does not supportSESSION_MODE_UNSUPPORTED

That is the complete list. A test in the component repository fails if a code is added, renamed or removed without this table changing, so it cannot silently drift.

Full reference​

CodeFatalMeaning
CAPTCHA_REJECTEDyesThe BFF did not accept the bot-protection check on submit. The component has already closed; the session is still usable. The exact message_code travels in details
CAPTCHA_UNAVAILABLEyesThe bot-protection check could not run in the browser — a blocker, the network, or Google's script not answering within 10 s — so the payment was not sent. The component has already closed; the session is still usable. details.cause says what failed
CONFIG_FETCH_FAILEDyesGET /config (with X-Session-Id) did not answer or failed. The form cannot mount without the merchant's configuration, so render() rejects
CONFIG_INVALIDyesGET /config answered, but something the form needs is missing: a text, the document rules, a module flag. The form does not mount. details.missing lists every missing path
ENCRYPTION_FAILEDnoA field could not be encrypted
INIT_FAILEDnoThe component could not be loaded from the CDN
MODULE_MOUNT_FAILEDnoA payment method loaded but did not become ready within 15 s. details says which one
MODULE_UNKNOWNnoThe merchant enabled a payment method this version cannot show. One per unknown name
NETWORK_ERRORnoThe request to the BFF failed at the network level
NO_MODULES_AVAILABLEyesNo mountable payment method was left. render() rejects
PAYMENT_INTENT_FAILEDnoThe BFF rejected the payment intent
PUBLIC_KEY_INVALIDnoThe BFF did not return the tenant's public key
RENDER_ABORTEDyesUnmounted before the module reported ready. Not a failure — see below
RENDER_FAILEDyesrender() could not run: the target container was not found, or the instance is already mounted
SERVICE_UNAVAILABLEnoA BFF dependency failed. Retryable — that is the whole difference with PAYMENT_INTENT_FAILED
SESSION_ID_INVALIDyesThe sessionId is missing or is not a non-empty string. An integration bug
SESSION_INVALIDyesThe BFF rejected the session. The form shuts down
SESSION_MODE_UNSUPPORTEDyesThe session was created with a checkout mode this version does not support. The form shuts down rather than guessing a mode, since a wrong guess would discard a tokenized card. Requires a newer component version
TOKENIZATION_FAILEDnoThe BFF could not tokenize the card
TOKENIZATION_TIMEOUTnoA field did not answer the encryption request within 10 s
VALIDATION_FAILEDnoThe entered data did not pass validation

"Fatal" means the component cannot continue: render() rejects, the form shuts down, or the component closes itself.

The ones worth knowing in detail​

SESSION_INVALID​

The failure the session model introduces, and the only one whose fix is on your side. The BFF rejected the session: it does not exist, it expired, or it was already used. The form shuts down, because no later call could work.

onError: async (error) => {
if (error.code === 'SESSION_INVALID') {
const { session_id } = await fetch('/checkout/session', { method: 'POST' }).then(r => r.json());
form.unmount();
form = new Checkout(session_id, options);
await form.render(container);
}
}

The exact message_code (SESSION_NOT_FOUND, SESSION_EXPIRED, SESSION_USED) travels in details.

CAPTCHA_REJECTED and CAPTCHA_UNAVAILABLE​

When bot protection is active, the component runs an invisible reCAPTCHA check each time the buyer presses the submit button, right before the payment intent (see Security → Bot protection). If the check fails, the component closes itself before calling onError, the same way it does before onSubmit: the container is empty and yours. Unlike a submit, the session was not used, so you can mount the component again with the same session_id:

onError: async (error) => {
if (error.code === 'CAPTCHA_REJECTED' || error.code === 'CAPTCHA_UNAVAILABLE') {
showToBuyer(error.userMessage);
form = new Checkout(sessionId, options); // same session; no unmount() needed
await form.render(container);
}
}

Both carry a userMessage. Show it yourself: the component is already gone, so errorDisplay: 'inline' has nowhere to draw it. CAPTCHA_UNAVAILABLE usually means something in the buyer's browser blocked Google's script; if it repeats, suggest disabling the blocker or trying another network.

CONFIG_INVALID​

The component has no texts or settings of its own: everything comes from the merchant's configuration in GET /config. If something is missing, the form does not mount and details.missing lists every missing path — for example modules[pci-card].labels.cardNumber.error — not just the first one. The fix is in the tenant configuration, not in your integration.

RENDER_ABORTED​

Not a failure: unmount() was called before the component finished mounting, so the render() in flight never completed. It has its own code so a catch can ignore it without ignoring a real timeout.

Ignoring the promise does not produce an unhandled rejection in the console. A mount timeout or a real failure, on the other hand, does show up — and also arrives through onError.

MODULE_UNKNOWN​

The merchant has a payment method enabled that this version of the component cannot show. Not fatal: one error arrives per unknown name and the checkout continues with the ones that do resolve. The normal case is an older release looking at a newer configuration. Nothing to do at runtime; if you need that method, update to a version that ships it.

NO_MODULES_AVAILABLE​

No mountable payment method was left, and render() rejects. This is configuration: either the merchant has no methods enabled, or none of them is supported by this version.

If config does not answer, the component does not fall back to built-in texts — it has none. It still tries the card form, which reads config on its own; if that read fails too, the form does not mount and render() rejects with CONFIG_FETCH_FAILED.

Getting more granularity than these codes​

The exact message_code from the BFF always travels in details, so you do not need a dedicated code per failure mode:

onError: (error) => {
console.error(error.code, error.details?.messageCode, error.details?.status);
}

What does not arrive here​

Issuer rejections — insufficient funds, invalid card, "call for authorization" — never reach the component. They are returned by POST /payment (with X-Session-Id), which your backend calls. The component stops at payment/intent, which only leaves the session ready to charge. See Backend Integration.

If that charge fails for a saved card and the response includes retry.allowed: true, remount the same session so the buyer can enter CVV again — do not treat it as a permanent SESSION_INVALID. Details: Saved cards and modes → CVV retry.