Events and Error Handling

Before You Start

Read the following guides before proceeding:

Overview

Every element reports through callbacks and rejected promises. No callback and no rejection ever carries a
card value: events carry validity flags, the detected brand and tokenize results; errors carry a safe
message and, where a backend call was made, its HTTP status.

The Change Event

Collect elements report non-sensitive state while the user types.

onChange: state => {
  state.complete;   // boolean — every field of the profile passes validation
  state.brand;      // 'Visa' | 'MasterCard' | 'unknown'
  state.fields;     // { number: { valid, touched }, … }
}

Use it to enable your submit button and to drive brand-dependent UI. A field that has never been mounted
reports { valid: false, touched: false }.

Field Validation

The frames validate as the user types and render error messages inline, inside the frame, styled by
colorError and localized by strings. Do not re-implement card validation on your page.

Calling a tokenizer while a field is invalid rejects with a PciFrameRequestError whose message starts
with Validation failed. The inline message is already visible to the user, so the typical handler shows
nothing extra for that case:

import { PciFrameRequestError } from '@wirexapp/card-topup-web';

try {
  const result = await topUp.tokenizeTopUp({ billingDetails });
} catch (error) {
  const isFieldValidation =
    error instanceof PciFrameRequestError && error.message.startsWith('Validation failed');
  if (!isFieldValidation) {
    showToast('Failed to add card');
  }
}

The per-field variant reports which field failed: Validation failed — number: <message>,
Validation failed — missing <field> when a sibling field was never mounted, and
Validation failed — invalid <field> when a sibling holds an invalid value.

PciFrameRequestError

Every frame-request failure the frame itself reports — init and tokenize — rejects with this class.

The class is re-exported as a value by every capability package and by @wirexapp/card-react, so
instanceof works from whichever package you import.

Mount Failures

field(name).mount(container) and mount(container) reject when the frame document cannot load or refuses
to initialize. These reject with a plain Error, not a PciFrameRequestError.

try {
  await topUp.field('number').mount(el);
} catch {
  showToast('Failed to load the secure card form');
}

An unregistered parent origin is the most common mount failure. The browser blocks the frame through
frame-ancestors, the iframe renders empty, and the ready handshake never completes — so the symptom is a
timeout, not a CSP error in your own console.

Reveal State

The reveal element reports its lifecycle through onStateChange.

onStateChange: ({ status, errorMessage }) => {
  // status: 'loading' | 'ready' | 'error'
}

error covers a consumed or expired actionToken, an unknown card id, a card status that does not permit
the operation, and backend failures. A partial failure reports ready with an em dash in the failed rows —
see Reveal Card Details.

Lifecycle Rules

• Call destroy() on every element when its view unmounts. It removes the iframes and the message
  listeners.
• Elements are single-use. After destroy(), create a new element rather than remounting the old one.
• Field iframes report their own height and the SDK sizes them. Width and placement come from your
  containers.
• Appearance and strings are read at mount. Re-theming requires a new element.
• In React these rules are handled by the components — see React Bindings.

What Never Reaches Your Page

• The PAN, CVV and expiry as typed by the user, and the values fetched by a reveal element
• The frames' API endpoints, which the frame service injects server-side
• Clipboard content copied inside a reveal frame. onCopied carries the field name and nothing else
• Any event payload beyond validity flags, the detected brand, and tokenize results — cardId or
  externalCardId, brand, BIN, last 4 and expiry month and year