Card reference

Factory

overflow.card(options?: CardElementOptions): CardElement

Options

All keys are optional.

Key	Type	Default	Description
`disabled`	`boolean`	`false`	Disables every input inside the element. To fully suppress input, call `unmount()`.
`readOnly`	`boolean`	`false`	Cascades to `holderName` and `postalCode`.
`id`	`string`	auto	DOM id on the host wrapper.
`ariaLabel`	`string`	none	Sets `aria-label` and `role="group"` on the host wrapper when supplied.
`locale`	`string`	Overflow instance locale	BCP-47 locale for field labels.
`fieldLayout`	`CardFieldLayout`	`['cardNumber', { inlineRow: ['cardExpiration', 'cardSecurityCode'] }, 'holderName', 'postalCode']`	Array of field keys defining vertical order. Wrap field keys in `{ inlineRow: [...] }` to render them on one row where space allows.
`fields`	see below	`{}`	Per-input customization.

`fieldLayout` shape

type CardFieldKey =
  | 'cardNumber'
  | 'cardExpiration'
  | 'cardSecurityCode'
  | 'holderName'
  | 'postalCode';

type CardFieldLayout = Array<CardFieldKey | { inlineRow: CardFieldKey[] }>;

Example — stack every field:

overflow.card({
  fieldLayout: ['cardNumber', 'cardExpiration', 'cardSecurityCode', 'holderName', 'postalCode'],
});

Example — inline expiration and security code (the default layout):

overflow.card({
  fieldLayout: [
    'cardNumber',
    { inlineRow: ['cardExpiration', 'cardSecurityCode'] },
    'holderName',
    'postalCode',
  ],
});

Every visible card field is required and validated. Suppress optional atoms with fields.holderName.hidden, fields.postalCode.hidden, or fields.cardSecurityCode.hidden.

`fields`

`cardNumber`

Key	Type	Default
`label`	`string`	`'Card number'`
`placeholder`	`string`	none
`iconStyle`	`'default' \| 'solid'`	`'default'`
`autoFocus`	`boolean`	`false`
`acceptedBrands`	`'auto' \| CardBrand[]`	`'auto'`
`acceptedBrandsPlacement`	`'inline' \| 'stacked' \| 'hidden'`	`'inline'`

Set fields.cardNumber.autoFocus: true to focus the card number field on mount. Use acceptedBrands to restrict the brand icons that render alongside the card number ('auto' uses every brand your merchant configuration supports). acceptedBrandsPlacement controls where the brand row renders: 'inline' alongside the input, 'stacked' below it, or 'hidden' to omit it.

`cardExpiration`

Key	Type	Default
`label`	`string`	`'Expiration'`
`placeholder`	`string`	`'MM / YY'`

`cardSecurityCode`

Key	Type	Default
`label`	`string`	`'Security code'`
`placeholder`	`string`	none
`hidden`	`boolean`	`false`

Hide the security code only for card programs that do not require CVC (for example, some private-label or corporate cards). Hiding it removes the field from validation.

`holderName`

Key	Type	Default
`label`	`string`	`'Name on card'`
`placeholder`	`string`	none
`disabled`	`boolean`	inherits element `disabled`
`hidden`	`boolean`	`false`
`id`	`string`	auto
`ariaLabel`	`string`	none

The card element does not autofocus on mount unless fields.cardNumber.autoFocus: true.

`postalCode`

Same shape as holderName. Default label 'Postal code'.

Value

The card element emits an encrypted value envelope on onSubmit. Sensitive fields are encrypted before they reach your handler.

type CardElementValue = {
  encryptedCardNumber: string;
  encryptedExpiryMonth: string;
  encryptedExpiryYear: string;
  encryptedSecurityCode: string;
  riskData: { clientData: string };
  browserInfo: {
    acceptHeader: string;
    colorDepth: number;
    language: string;
    javaEnabled: boolean;
    screenHeight: number;
    screenWidth: number;
    timeZoneOffset: number;
    userAgent: string;
  };
  holderName?: string;
  postalCode?: string;
};

Forward the full envelope to your server verbatim; do not try to unpack or transform the encrypted* fields. holderName and postalCode are present only when the corresponding field is visible and non-empty. encryptedSecurityCode is always present — it is an empty string ('') when fields.cardSecurityCode.hidden is true.

Card error codes

Card onError events surface validation_failed, not_mounted, network, tokenization_failed, and unknown. See Error codes.

Events

Every element event is supported: onReady, onChange, onSubmit, onError, onFocus, onBlur, onEscapeKeyPressed. See Events overview.

`FieldError.field` values

'cardNumber', 'cardExpiration', 'cardSecurityCode', 'holderName', 'postalCode'.

Methods

card.mount(selector)
card.update(partialOptions)
card.submit(): void — validates and emits onSubmit (encrypted envelope) or onError.
card.unmount()
card.destroy()
card.on(event, handler) — subscribe to events.

Get started

Elements

Options

Events

Theming

Guides

Factory

Options

`fieldLayout` shape

`fields`

`cardNumber`

`cardExpiration`

`cardSecurityCode`

`holderName`

`postalCode`

Value

Card error codes

Events

`FieldError.field` values

Methods

​Factory

​Options

​fieldLayout shape

​fields

​cardNumber

​cardExpiration

​cardSecurityCode

​holderName

​postalCode

​Value

​Card error codes

​Events

​FieldError.field values

​Methods

Factory

Options

`fieldLayout` shape

`fields`

`cardNumber`

`cardExpiration`

`cardSecurityCode`

`holderName`

`postalCode`

Value

Card error codes

Events

`FieldError.field` values

Methods