Handle validation errors

Every element surfaces validation errors on two channels: onChange.errors while the shopper is typing, and onError.fieldErrors after a rejected submit(). Both use the same FieldError shape, so a single renderer covers both surfaces.

Error shape

interface FieldError {
  field: string;    // element-specific key, e.g. 'email', 'cardNumber'
  code: string;     // stable machine-readable code
  message: string;  // already localized, safe to render
  source?: string;  // Checkout-only: 'contact' | 'billingAddress' | 'shippingAddress' | 'paymentMethod' | 'customElement'
}

Gate submission on `complete`

The reliable signal for enabling your submit button is onChange.complete. It already accounts for required, format schemas, custom validate callbacks, and (for compound elements) sub-element state.

card.on('onChange', ({ complete }) => {
  submitBtn.disabled = !complete;
});

Do not infer validity from value !== null. Some elements emit partial typed shapes mid-typing; that is intentional and does not mean the value is valid.

Render inline errors from `onChange.errors`

email.on('onChange', ({ errors }) => {
  renderInlineErrors(errors ?? []); // errors is omitted when empty
});

The same FieldError[] appears on onError.fieldErrors after a rejected submit. Reuse the same renderer.

Render submit-time errors from `onError.fieldErrors`

card.on('onError', ({ code, message, fieldErrors, cause }) => {
  switch (code) {
    case 'validation_failed':
      paintFieldErrors(fieldErrors);
      break;
    case 'tokenization_failed':
      toast(`Card error: ${message}`);
      break;
    case 'network':
      toast('Network error. Try again.');
      break;
    default:
      toast(message);
  }
});

Switch on code (the union is closed but new codes are added in minor releases, so keep a default branch).
Render message as-is; it is already localized and shopper-safe.
Do not surface cause; it carries raw diagnostics intended for observability.

Layer custom rules with `validate`

To add rules on top of the built-ins, leave validate unset and gate your business logic elsewhere (a server-side check, or inside your own onChange handler). To replace the built-ins entirely, pass a validate callback:

overflow.text({
  name: 'giftMessage',
  label: 'Gift message',
  validate: (value) => {
    if (!value) return null; // optional field
    if (value.length > 140) return 'Keep it under 140 characters';
    return null;
  },
});

validate opts the element fully out of built-in checks; the callback owns the entire contract. See validate.

Bucket Checkout errors by `source`

Inside Checkout, every emitted FieldError carries a source string identifying which slot of the value envelope the field belongs to:

checkout.on('onChange', ({ errors }) => {
  const contactErrors = errors?.filter(e => e.source === 'contact');
  const paymentErrors = errors?.filter(e => e.source === 'paymentMethod');
  const customErrors = errors?.filter(e => e.source === 'customElement');
  paintContactErrors(contactErrors);
  paintPaymentErrors(paymentErrors);
  paintCustomErrors(customErrors);
});

Most source values map directly to a top-level key on CheckoutElementValue (contact, billingAddress, shippingAddress). Two do not: paymentMethod errors belong to whichever payment method is currently active — read them off value.card, value.bank, value.applePay, or value.googlePay, keyed by value.method. customElement errors belong to a specific key inside value.customElements.

Bank key rotation

If your server rejects an encrypted bank payload with a UNKNOWN_KID error (an expected condition during key rotation), call overflow.invalidateBankFieldEncryptionCache() and retry bank.submit() once. The same pattern applies inside Checkout — invalidate, then call checkout.submit() again from the same handler:

try {
  await postToBackend(bankValue);
} catch (err) {
  if (err.code === 'UNKNOWN_KID') {
    overflow.invalidateBankFieldEncryptionCache();
    bank.submit(); // or checkout.submit() from the Checkout bank path
    return;
  }
  toast('Something went wrong. Try again.');
}

For merchant-facing messaging during outages of this kind, prefer “manual bank entry may be temporarily unavailable” rather than exposing the underlying condition.

Get started

Elements

Options

Events

Theming

Guides

Error shape

Gate submission on `complete`

Render inline errors from `onChange.errors`

Render submit-time errors from `onError.fieldErrors`

Layer custom rules with `validate`

Bucket Checkout errors by `source`

Bank key rotation

See also

​Error shape

​Gate submission on complete

​Render inline errors from onChange.errors

​Render submit-time errors from onError.fieldErrors

​Layer custom rules with validate

​Bucket Checkout errors by source

​Bank key rotation

​See also

Error shape

Gate submission on `complete`

Render inline errors from `onChange.errors`

Render submit-time errors from `onError.fieldErrors`

Layer custom rules with `validate`

Bucket Checkout errors by `source`

Bank key rotation

See also