---
title: "Events and methods"
description: "What the form tells your page, and what your page can ask of the form."
image: "https://docs.ordercard.io/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ordercard.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and methods

## Events

Subscribe with `card.on(event, handler)` and unsubscribe with `card.off(event, handler)`.

| Event | Handler arguments | When |
| --- | --- | --- |
| `ready` | | The form has loaded. Calls made before this are queued. |
| `configured` | | Your options have been applied. |
| `paymentMethod` | `token`, `card` | A card was tokenized. `card` has `brand`, `first6`, `last4`, `exp_month`, `exp_year`, `type`, `issuer`, `country` and `prepaid`. |
| `errors` | `errors` | Validation or tokenization failed. |
| `validation` | `properties` | The answer to `validate()`. |
| `fieldEvent` | `name`, `type`, `activeElement`, `properties` | A field got focus, lost it, or changed. `properties` is set on input. |
| `cardMeta` | `meta` | The first eight digits identified the card: `brand`, `type` (`credit`, `charge`, `debit`, `prepaid`, `unknown`, or `pending` until eight digits are typed), `issuer`, `country`, `prepaid`. Send its `type` as `card_type` to [quote a surcharge](/payments/surcharging) before tokenizing. |
| `resize` | `{ height }` | The form changed height (already applied when `autoResize` is on). |
| `consoleError` | `{ msg }` | A problem worth logging, like a style that was ignored. |

`properties` describes the card as typed so far: `cardType`, `validNumber`, `validExpiry`, `validCvv`, `numberLength`, `cvvLength` and `iin` (the first digits).

## Errors

Errors come as a list of `{ attribute, key, message }`. `attribute` is the field (`number`, `expiry`, `cvv`, `name`, `postal_code`, or a billing address field such as `city`), a detail you passed to `tokenize()` (such as `email`), or `form`. The form shows field errors under their field, or once under their group in the `inline` layout, and anything else in a notice at the bottom. `key` is stable enough to translate:

| Key | Meaning |
| --- | --- |
| `errors.blank` | The field is empty. |
| `errors.invalid` | The value is not valid, for example a number that fails the check digit. |
| `errors.expired` | The expiry date is in the past. |
| `errors.rate_limited` | Too many attempts from this browser; try again in a few minutes. |
| `errors.busy` | A tokenization is already running. |
| `errors.configuration` | The key or origin is not set up to take cards. |

## Methods

| Method | Does |
| --- | --- |
| `tokenize(details)` | Validates and tokenizes. Resolves with `{ token, card }`, rejects with the error list. `details` is `{ billing, metadata }` with what your page already collected ([details from your own form](/hosted-fields/options#details-from-your-own-form)), never card data and never the customer: link cards to customers from your server. |
| `validate()` | Resolves with the current `properties` without tokenizing. |
| `update(options)` | Changes any `init()` options (layout, fields, theme, styles and so on) without reloading the form or clearing what the customer typed. |
| `setTheme(theme)` | Changes theme variables. |
| `setStyle(target, css)` | Adds CSS for a part of the form. |
| `setPlaceholder(field, text)` | Changes a placeholder. |
| `setLabel(field, text)` | Changes a label. |
| `setFieldType(field, type)` | `tel`, `text` or `number` for `number`, `expiry` or `cvv`. |
| `setNumberFormat(format)` | `pretty`, `plain` or `masked`. |
| `toggleMask()` | Shows or hides the number and security code. |
| `transferFocus(field)` | Moves focus into a field. |
| `setFont(font)` | Loads a Google font. |
| `reset()` | Clears the form. |
| `destroy()` | Removes the form and its listeners. |

`OrderCard.on(...)`, `OrderCard.tokenize(...)` and the other methods also exist on `OrderCard` itself and act on the most recently created form.

## How the page and the form talk

The page and the form exchange `postMessage` messages. The form only accepts messages from the origin it was loaded for, and only from the window that embedded it; your page only accepts messages from `secure.ordercard.io` and from its own iframe. Each `tokenize()` call carries an id, so its result can only be delivered once.

Source: https://docs.ordercard.io/hosted-fields/events/index.mdx