Card validation errors - Elements SDK

Card fields validate as the shopper types and report state on every keystroke through the change event — there’s no separate “submit and see what’s wrong” step.

TL;DR: change fires with event.valid: false and an event.error → gate the Pay button on valid and show error.message inline.

When this happens

The shopper is still typing (incomplete number, expiry, or CVV).
The card number fails a brand/Luhn check, or the detected brand isn’t one you support.
The expiry date is invalid or already in the past.
The CVV doesn’t match the expected length for the detected brand.
On pre-15.4 Safari without BroadcastChannel, a split expiry/CVV field can’t relay its value to the primary field.

What you see

Signal	Value
Event	`change` — fires on every keystroke
`event.valid`	`false` while any field is invalid or empty — gate the Pay button on this
`event.error.code`	One of `required`, `incomplete_number`, `invalid_number`, `unsupported_brand`, `incomplete_expiry`, `invalid_month`, `invalid_year`, `expired_card`, `invalid_expiry`, `incomplete_cvv`, `invalid_cvv`
`event.error.field`	The Element the error belongs to — always `"card"` on the combined field, so use `code` (not `field`) to tell which cell failed
`event.error.message`	Display-safe text for that code
Safari fallback	`expiry_missing` / `cvv_missing` relay failure (split fields, pre-15.4 Safari)

What to do

Gate the pay button on valid

Disable submission until every mounted field reports valid: true. event.error can still be null here — it’s only set once blur-time validation runs — so don’t gate on error being absent. Don’t rely on a separate manual validation pass.

card.on("change", (event) => {
  payButton.disabled = !event.valid;
  if (event.error) {
    showFieldError(event.error.message);
  } else {
    clearFieldError();
  }
});

Show the error only while it's present

event.error is null once the field becomes valid again — clear your inline message in that case rather than leaving a stale error visible.

Handle the Safari fallback

If you support split fields and see repeated expiry_missing/cvv_missing on older Safari, either advise the shopper to update their browser or switch to the combined card element, which doesn’t need cross-iframe relay.

Prevent it

Prefer the combined card element unless you specifically need a custom layout — it has no BroadcastChannel dependency and one fewer iframe to coordinate.
Advertise supported card brands with supportedBrands so shoppers see upfront which cards you accept, before they type a full number.

Card fields and events

Element types, create options, events, and Safari notes.

Accept a card payment

Where the change event fits in the full charge flow.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Card validation errors - Elements SDK

When this happens

What you see

What to do

Prevent it

Card fields and events

Accept a card payment

​When this happens

​What you see

​What to do

​Prevent it

​Related

Card fields and events

Accept a card payment

When this happens

What you see

What to do

Prevent it

Related