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:
| Property | Type | Description |
|---|---|---|
code | string | One of the codes below. This is what you switch on |
message | string | Technical description, for your logs |
userMessage | string (optional) | The buyer-facing text, already translated and with the merchant's configured copy applied. Show this one |
details | unknown | Extra 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 do | Codes |
|---|---|
| Ask your backend for a new session. The session does not exist, expired (15 min TTL) or was already used | SESSION_INVALID |
| Fix the integration. These show up while developing, not in production | SESSION_ID_INVALID, RENDER_FAILED |
| Ignore. The component was torn down before it finished mounting | RENDER_ABORTED |
Show the error and let the buyer retry. The form stays mounted and usable, and already carries a userMessage | VALIDATION_FAILED, PAYMENT_INTENT_FAILED, ENCRYPTION_FAILED, TOKENIZATION_FAILED, TOKENIZATION_TIMEOUT |
| Retry, or report the service as unavailable. Not the card: something in the infrastructure failed | SERVICE_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.missing | MODULE_UNKNOWN, NO_MODULES_AVAILABLE, CONFIG_INVALID |
| Report it: the BFF did not return the public key, so the tenant is misconfigured | PUBLIC_KEY_INVALID |
| Update the component: the session uses a checkout mode this version does not support | SESSION_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
| Code | Fatal | Meaning |
|---|---|---|
CAPTCHA_REJECTED | yes | The 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_UNAVAILABLE | yes | The 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_FAILED | yes | GET /config (with X-Session-Id) did not answer or failed. The form cannot mount without the merchant's configuration, so render() rejects |
CONFIG_INVALID | yes | GET /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_FAILED | no | A field could not be encrypted |
INIT_FAILED | no | The component could not be loaded from the CDN |
MODULE_MOUNT_FAILED | no | A payment method loaded but did not become ready within 15 s. details says which one |
MODULE_UNKNOWN | no | The merchant enabled a payment method this version cannot show. One per unknown name |
NETWORK_ERROR | no | The request to the BFF failed at the network level |
NO_MODULES_AVAILABLE | yes | No mountable payment method was left. render() rejects |
PAYMENT_INTENT_FAILED | no | The BFF rejected the payment intent |
PUBLIC_KEY_INVALID | no | The BFF did not return the tenant's public key |
RENDER_ABORTED | yes | Unmounted before the module reported ready. Not a failure — see below |
RENDER_FAILED | yes | render() could not run: the target container was not found, or the instance is already mounted |
SERVICE_UNAVAILABLE | no | A BFF dependency failed. Retryable — that is the whole difference with PAYMENT_INTENT_FAILED |
SESSION_ID_INVALID | yes | The sessionId is missing or is not a non-empty string. An integration bug |
SESSION_INVALID | yes | The BFF rejected the session. The form shuts down |
SESSION_MODE_UNSUPPORTED | yes | The 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_FAILED | no | The BFF could not tokenize the card |
TOKENIZATION_TIMEOUT | no | A field did not answer the encryption request within 10 s |
VALIDATION_FAILED | no | The 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.