Skip to main content

Lifecycle Hooks

The component communicates with your application through callbacks passed in the options object. All of them are optional.

HookSignatureFires when
onReady() => voidThe component finished mounting and accepts input
onSubmit({ module, result? }) => void | Promise<void>The mounted module finished its work
onError(error: CheckoutError) => voidAnything failed
onAmountChange(amount: number | null) => voidThe installment selection changed the total
onBinChange(info | null) => voidThe buyer completed or cleared the card BIN
onModuleEvent({ module, name, data? }) => voidAny of the above, and anything a module adds later

onReady​

Fired once the component has fetched its configuration, mounted the payment method and is ready for user interaction. Use it to hide your own loading state.

onReady: () => hideSpinner(),

onSubmit​

Fired when the mounted module finishes its work. What that means depends on the session mode (set on POST /sessions — see Saved cards and modes):

ModeIntentonSubmit
Hybrid (1) / Complete (2)204Session is ready to charge. Call your backend → POST /payment + X-Session-Id. No card payload in result
Mixed (0)200 with public fieldsCard saved — do not charge this session. result holds { payment_method_id, brand, last4, exp }
onSubmit: async ({ module, result }) => {
// The component has already unmounted itself. The container is yours.
if (result) {
// Mixed: the saved card's public fields only — never PAN/CVV
await fetch('/checkout/saved-card', {
method: 'POST',
body: JSON.stringify(result),
});
return;
}
showSuccessScreen();
await fetch('/checkout/charge', { method: 'POST' }); // your backend + JWT
},
FieldTypeDescription
modulestringId of the module that resolved, e.g. pci-card
resultunknown (optional)Whatever that payment method produces. Not interpreted by the component

Hybrid / Complete: payment/intent answers 204 — no result, token stays server-side.
Mixed: result carries the saved card's public fields (payment_method_id, brand, last4, exp). Never PAN or CVV.

The component closes itself first​

A submit ends the module's UI work: the SDK unmounts before calling you and leaves the container empty. Concretely:

  • Draw your success (or next) screen from onSubmit. The container is already yours.
  • You do not need unmount(). Calling it anyway is idempotent.
  • After a successful charge, mount again only with a new session (SESSION_USED).
  • After a declined charge with a saved card, you may remount the same session when the charge error includes retry.allowed: true — see Saved cards and modes.

If your backend takes a while to charge and you want to show something meanwhile, that something lives on your page: the component does not wait around.

The charge does not happen here. Step 5 is POST /api/v1.0/payment with header X-Session-Id and the same Bearer JWT used to create the session, executed by your backend — see Backend Integration.

onError​

Fired on any error during initialization, validation, tokenization or the call to the BFF. Always receives a CheckoutError — see Error Handling for the full code list.

onError: (error) => {
// `userMessage` is the buyer-facing text, already translated and with the merchant's
// configured copy applied. `message` is the technical detail, for your logs.
if (error.userMessage) showToBuyer(error.userMessage);
else console.error(error.code, error.message, error.details);

if (error.code === 'SESSION_INVALID') restartCheckout();
},

The two texts exist because they serve different purposes: userMessage is for the buyer, message is for your log. An error without userMessage is one the buyer cannot act on — a mount timeout, a payment method this version cannot show, an unmount() mid-render — so it belongs in the console, not on screen.

Where the buyer-facing text is displayed is your decision; the component does not draw it inside its iframe unless you ask it to with errorDisplay: 'inline'.

CAPTCHA_REJECTED and CAPTCHA_UNAVAILABLE arrive after the component closed itself, as with onSubmit: the container is empty and yours. The difference is that the session was not used, so you can mount the component again with the same session_id — see Error Handling.

CheckoutError is a real Error and serializes with error.toJSON() → { code, message, userMessage, details }.

onAmountChange​

Fired every time the installment selection changes, with the selected plan's total — what the buyer will pay, financing cost included. Receives null when the selection stops being valid.

onAmountChange: (amount) => {
totalElement.textContent = amount !== null ? `$ ${amount}` : '—';
},

This is the same figure the form shows on the selected row, so your checkout's order summary cannot end up displaying a different one.

It fires even when the buyer chooses nothing. When the merchant hides the installment selector, the form takes the first plan and reports it anyway: hiding the list is presentation, and that is precisely the case where you have no other way of knowing the total.

null arrives when the selection stops being valid — the list was emptied, or a different offer came in — so your checkout does not keep showing a total that no longer exists.

Until an earlier version this carried received_amount, the merchant's net after the financing cost: a smaller number, and the least useful one on a page where somebody is about to pay. Settlement figures are read on the backend, not here.

onBinChange​

Fired when the buyer completes or clears the card BIN. Receives null on clear.

onBinChange: (info) => {
if (info) console.log(info.bin, info.brand);
},
FieldTypeDescription
binstringThe first 6 digits, once complete
brandstringBrand detected locally from the number pattern: visa, mastercard, amex, maestro, diners, discover or unknown

brand is a browser-side estimate from the card number, not a server answer — which also means it arrives earlier, with two digits instead of a round trip. Brands not in that list report unknown.

cardType (credit/debit) used to be part of this payload and is gone: it came from the installments response of the previous contract and cannot be derived from the number.

onModuleEvent​

Generic channel: receives everything the mounted module emits, tagged with the id of whoever emitted it.

onModuleEvent: ({ module, name, data }) => {
console.log(`[${module}] ${name}`, data);
},
FieldTypeDescription
modulestringId of the module that emitted, e.g. pci-card
namestringThe event name. The card module emits bin-change and amount-change
dataunknown (optional)Opaque — its shape is defined by whoever emits the name

This is what keeps your snippet unchanged when a payment method is added: a new module emits new names through this single channel instead of requiring a new callback.

onBinChange and onAmountChange are sugar over the two names the card module emits today. They are a mapping, not a parallel path: both fire. Use the specific hooks for the card form, and this one to observe everything or to handle a module that ships later.