Lifecycle Hooks
The component communicates with your application through callbacks passed in the options object. All of them are optional.
| Hook | Signature | Fires when |
|---|---|---|
onReady | () => void | The component finished mounting and accepts input |
onSubmit | ({ module, result? }) => void | Promise<void> | The mounted module finished its work |
onError | (error: CheckoutError) => void | Anything failed |
onAmountChange | (amount: number | null) => void | The installment selection changed the total |
onBinChange | (info | null) => void | The buyer completed or cleared the card BIN |
onModuleEvent | ({ module, name, data? }) => void | Any 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):
| Mode | Intent | onSubmit |
|---|---|---|
Hybrid (1) / Complete (2) | 204 | Session is ready to charge. Call your backend → POST /payment + X-Session-Id. No card payload in result |
Mixed (0) | 200 with public fields | Card 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
},
| Field | Type | Description |
|---|---|---|
module | string | Id of the module that resolved, e.g. pci-card |
result | unknown (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);
},
| Field | Type | Description |
|---|---|---|
bin | string | The first 6 digits, once complete |
brand | string | Brand 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);
},
| Field | Type | Description |
|---|---|---|
module | string | Id of the module that emitted, e.g. pci-card |
name | string | The event name. The card module emits bin-change and amount-change |
data | unknown (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.