# Frames reference

> **Note**
>
> Frames will be deprecated on June 30, 2026. [Upgrade to Flow](https://www.checkout.com/docs/payments/accept-payments/upgrade-to-flow-from-frames/upgrade-from-frames-for-web.md), our pre-built, customizable payment user interface. Flow provides a more flexible, scalable, and feature-rich integration, as well as access to additional payment methods.

Our Frames reference outlines all possible configuration options so you can tailor your customers' experience.

---

## Supported browsers

Frames is a critical payment service, which requires up-to-date security. For this reason, we support all major browsers that are still officially maintained and receiving security updates.

We support:

- Chrome, Chrome Mobile, Firefox, and Microsoft Edge
- Safari on desktop and iOS

If you discover any issues with the supported browsers, or would like to report a bug, please [get in touch](https://www.checkout.com/contact-us).

---

## Required configurations

Here's a complete list of Frames configuration options.

> **Information**
>
> You can only create charges in currencies that have been enabled for your account. Contact your account manager if you need to process payments in additional currencies.

| JavaScript key | Description |
| --- | --- |
| `publicKey` | Bearer public API key. |

---

## Optional configurations

| JavaScript key | Description | Default |
| --- | --- | --- |
| `acceptedPaymentMethods` | Allows you to provide the card schemes you accept to perform validation against the card number provided by customers.<br>Accepted properties include:<br><br>`['Visa', 'Maestro', 'Mastercard', 'American Express', 'Diners Club', 'Discover', 'JCB', 'Mada'];` | `{}` |
| `debug` | Set to `true` to view console messages. | `false` |
| `frameSelector` | The `.class` or `#id` of the parent elements in the Frames payment form. | none |
| `localization` | Allows you to use one of the supported languages or a custom object. Refer to the [Frames customization guide](https://www.checkout.com/docs/integrate/frames/frames-customization-guide.md#Localization) for more information. | `EN-GB` |
| `namespace` | Customize the default Frames namespace. | `Frames` |
| `schemeChoice` | When set to `true`, Frames detects if the customer is using a co-branded card and automatically display their card scheme choice. | `false` |
| `style` | Allows you to customize the look and feel of Frames' controlled fields. Refer to the [Frames customization guide](https://www.checkout.com/docs/integrate/frames/frames-customization-guide.md) for more information. | `{}` |

---

## Turn on optional modes

When you [initialize Frames](https://www.checkout.com/docs/integrate/frames/get-started.md#Initialize_Frames), you can use the `modes` array to customize the way Frames works and what is displayed.

### Right-to-left

Configure Frames to support right-to-left languages by specifying `RIGHT_TO_LEFT` in the modes array in the `Frames.init` object.

```javascript
Frames.init({
  publicKey: 'pk_sbox_XXXXXX',
  modes: [Frames.modes.RIGHT_TO_LEFT],
});
```

### Hide the CVV field

When paying out to a card, the [CVV field](https://www.checkout.com/docs/payments/authenticate-payments/card-verification.md) is not required, so you can initialize Frames with `CVV_HIDDEN` or `CVV_OPTIONAL`.

**CVV_HIDDEN**

```javascript
Frames.init({
  publicKey: 'pk_sbox_XXXXXX',
  modes: [Frames.modes.CVV_HIDDEN],
});
```

**CVV_OPTIONAL**

```javascript
Frames.init({
  publicKey: 'pk_sbox_XXXXXX',
  modes: [Frames.modes.CVV_OPTIONAL],
});
```

> **Information**
>
> You can use either `CVV_HIDDEN` or `CVV_OPTIONAL`, but you cannot incorporate both.

#### Additional security

To prevent copy pasting of card details within the iframe, you can use `DISABLE_COPY_PASTE`.

```javascript
Frames.init({
  publicKey: 'pk_sbox_XXXX',
  modes: [Frames.modes.DISABLE_COPY_PASTE],
});
```

---

## Customer details

| JavaScript key | Description | Default |
| --- | --- | --- |
| `name` | The customer's name. | none |
| `billingAddress` | Transaction billing address:<br><br>`{`<br>` addressLine1,`<br>` addressLine2,`<br>` zip,`<br>` city,`<br>` state,`<br>` country,`<br>`}`<br><br>The country field only accepts two-letter [ISO country codes](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes.md). | none |
| `phone` | The customer's phone number. | none |

---

## Localization options

> **Information**
>
> When you enable Arabic as a locale, then [right-to-left mode](#Right-to-left)  is activated by default.

| JavaScript key | Description | Default |
| --- | --- | --- |
| `localization` | Sets the language of the text used.<br><br>The available options are:<br><br>- Arabic – AR<br>- German – DE-DE<br>- English – EN-GB<br>- Spanish – ES-ES<br>- Filipino – FIL-PH<br>- French – FR-FR<br>- Hindi – HI-IN<br>- Indonesian – ID-ID<br>- Italian – IT-IT<br>- Japanese – JA-JP<br>- Korean – KO-KR<br>- Malay – MS-MY<br>- Dutch – NL-NL<br>- Chinese Simplified – ZH,CH<br>- Chinese Traditional (Hong Kong) – ZH-HK<br>- Chinese Traditional (Taiwan) – ZH-TW<br>- Thai – TH-TH<br>- Vietnamese – VI-VN | `EN-GB` |

---

## Events

| Event name | JavaScript constant | Description |
| --- | --- | --- |
| `cardBinChanged` | `CARD_BIN_CHANGED` | Triggered when the user inputs or changes the first 8 digits of a card. The event contains data similar to the following example:<br><br>`bin: 42424242,`<br>`scheme: VISA` |
| `cardSubmitted` | `CARD_SUBMITTED` | Triggered when the card form has been submitted. |
| `cardTokenized` | `CARD_TOKENIZED` | Triggered after a card is tokenized. The event contains the data in the following example.<br><br>To view the full response schema:<br><br>1. Go to [Request a token](https://api-reference.checkout.com/tag/Tokens/#operation/requestAToken).<br>2. Scroll down to _Responses_.<br>3. Expand _201 Reference token created successfully_.<br>4. Select _card_ from the _type_ dropdown in the schema. You can also see a full example under _Response samples_ by making the same selection on that dropdown.<br><br>`{`<br>`  "type": "card",`<br>`  "token": "tok_ubfj2q76miwundwlk72vxt2i7q",`<br>`  "expires_on": "2024-10-07T16:54:21Z",`<br>`  "expiry_month": 6,`<br>`  "expiry_year": 2025,`<br>`  "scheme": "VISA",`<br>`  "last4": 9996,`<br>`  "bin": 454347,`<br>`  "card_type": "CREDIT",`<br>`  "card_category": "CONSUMER",`<br>`  "issuer": "Test Bank",`<br>`  "issuer_country": "US",`<br>`  "product_id": "F",`<br>`  "product_type": "CLASSIC",`<br>`  "billing_address": ["..."],`<br>`  "phone": ["..."],`<br>`  "name": "John Smith"`<br>`}` |
| `cardTokenizationFailed` | `CARD_TOKENIZATION_FAILED` | Triggered if the card tokenization fails. |
| `cardValidationChanged` | `CARD_VALIDATION_CHANGED` | Triggered when the state of the card validation changes. This returns: `isValid: true / false`. |
| `frameActivated` | `FRAME_ACTIVATED` | Triggered when the form is rendered. |
| `frameFocus` | `FRAME_FOCUS` | Triggered when an input field receives focus. Use it to check the validation status and apply the wanted UI changes. |
| `frameBlur` | `FRAME_BLUR` | Triggered after an input field loses focus. Use it to check the validation status and apply the wanted UI changes. |
| `frameValidationChanged` | `FRAME_VALIDATION_CHANGED` | Triggered when a field's validation status has changed. Use it to show error messages or update the UI. |
| `paymentMethodChanged` | `PAYMENT_METHOD_CHANGED` | Triggered when a valid payment method is detected based on the card number being entered. Use this event to change the card icon or validate the input against accepted card schemes, similar to the following example:<br><br>`isValid: true,`<br>`paymentMethod: American Express,`<br>`isPaymentMethodAccepted: false` |
| `ready` | `READY` | Triggered when Frames is registered on the global namespace and safe to use. |

---

## Adding an event handler

There are two ways to add an event handler: using the standard approach or using configuration options.

**Method 1: Standard approach**

```javascript
Frames.addEventHandler(Frames.Events.EVENT_NAME, handler);
```

**Method 2: Configuration options**

```javascript
Frames.init({
  publicKey: 'pk_sbox_XXXXXX',
  [Frames.Events.EVENT_NAME]: handler,
});
```

---

## Actions

| Signature | Description | Returns |
| --- | --- | --- |
| `init(object)` | Initializes (or re-initializes) Frames.<br>Examples:<br><br>- `init({ publicKey: '...' })` initializes with your configuration<br>- `init()` reinitializes Frames with the current configuration (if there is one) and empties the fields. This is useful, for example, in single page apps where you want to reinitialize with a clean slate without reloading<br>- `init({...})` reinitializes Frames with another configuration | `undefined` |
| `isCardValid()` | Returns the state of the card form validation.<br>Example:<br>`Frames.isCardValid()` | boolean |
| `submitCard()` | Submits the card form if all form values are valid.<br>Example:<br>`Frames.submitCard()` | Promise |
| `addEventHandler(event, handler)` | Adds a handler that is called when the specified event is triggered. Call the `Frames.Events` object to retrieve the list of accepted events.<br>Example:<br>`event: Events.CARD_TOKENIZED handler: function(event){}` | `undefined` |
| `removeEventHandler(event, handler)` | Removes a previously added handler from an event by providing the event name and handler as arguments in the method.<br>Example:<br>`event: Events.CARD_TOKENIZED handler: function(event){}` | `boolean` |
| `removeAllEventHandlers(event)` | Removes all handlers added to the event specified.<br>Example:<br>`event: Events.CARD_TOKENIZED` | `boolean` |
| `enableSubmitForm()` | Retains the entered card details and allows you to resubmit the payment form. | `undefined` |

---

## Functions

| Getter | Setter | Description |
| --- | --- | --- |
| `publicKey` | `publicKey = value ` | Bearer public API key. |
| `debugMode` | N/A | Returns `true` if in debug mode. |
| `namespace` | N/A | Returns `Frames` or a custom namespace. |
| `version` | N/A | Returns the Frames version number. |
| `cardholder` | `cardholder = value` | The customer's name, billing details and phone number. |
| `localization` | N/A | Returns the selected language or the path to the localization file. |
| `config` | N/A | Returns the configuration of Frames. |

---

## Examples

### Using the submitCard Promise

This example uses a JavaScript Promise to tokenize a customer's payment details. The card token is posted via the URL specified in the form's `action` attribute.

```html
<body>
  {"<!--"} add frames script -->
  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>

  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
    <div class="card-frame">{"<!--"} form is added here --></div>
    {"<!--"} add submit button -->
    <button id="pay-button" disabled>PAY GBP 24.99</button>
  </form>

  <script>
    var payButton = document.getElementById('pay-button');
    var form = document.getElementById('payment-form');

    Frames.init('pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14');

    Frames.addEventHandler(Frames.Events.CARD_VALIDATION_CHANGED, function (event) {
      console.log('CARD_VALIDATION_CHANGED: %o', event);

      payButton.disabled = !Frames.isCardValid();
    });

    form.addEventListener('submit', function (event) {
      event.preventDefault();
      Frames.submitCard()
        .then(function (data) {
          Frames.addCardToken(form, data.token);
          form.submit();
        })
        .catch(function (error) {
          // handle error
        });
    });
  </script>
</body>
```

### Using the cardTokenized handler

This example uses `cardTokenized` handler to gain a payment token for your customers' card details.

```html
<body>
  {"<!--"} add frames script -->
  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>

  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
    <div class="card-frame">{"<!--"} form is added here --></div>
    {"<!--"} add submit button -->
    <button id="pay-button" disabled>PAY GBP 24.99</button>
  </form>

  <script>
    var payButton = document.getElementById('pay-button');
    var form = document.getElementById('payment-form');

    Frames.init({
      publicKey: 'pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14',
      cardValidationChanged: function () {
        // if all fields contain valid information, the Pay now
        // button is enabled and the form can be submitted
        payButton.disabled = !Frames.isCardValid();
      },
      cardSubmitted: function () {
        form.disabled = true;
        // display loader
      },
      cardTokenized: function (data) {
        Frames.addCardToken(form, data.token);
        form.submit();
      },
      cardTokenizationFailed: function (event) {
        // catch the error
      },
    });

    form.addEventListener('submit', function (event) {
      event.preventDefault();
      Frames.submitCard();
    });
  </script>
</body>
```

### Loading Frames asynchronously

If you load Frames asynchronously, you can change the namespace to a name other than `Frames`. The following example uses `Checkout` as the namespace.

> **Information**
>
> Use `window.CKOConfig` to change the namespace, or to load Frames asynchronously.

```html
<body>
  {"<!--"} add frames script -->
  <script async src="https://cdn.checkout.com/js/framesv2.min.js"></script>

  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
    <div class="card-frame">{"<!--"} form is added here --></div>
    {"<!--"} add submit button -->
    <button id="pay-button" disabled>PAY GBP 24.99</button>
  </form>

  <script>
    var payButton = document.getElementById('pay-button');
    var form = document.getElementById('payment-form');

    window.CKOConfig = {
      publicKey: 'pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14',
      namespace: 'Checkout',
      ready: function () {
        // Frames is registered on the global namespace and safe to use
        form.addEventListener('submit', function (event) {
          event.preventDefault();
          Checkout.submitCard();
        });
      },
      cardValidationChanged: function (event) {
        console.log('CARD_VALIDATION_CHANGED: %o', event);
        // if all fields contain valid information, the Pay now
        // button is enabled and the form can be submitted
        payButton.disabled = !Checkout.isCardValid();
      },
      cardSubmitted: function () {
        payButton.disabled = true;
        // display loader
      },
      cardTokenized: function (data) {
        console.log('CARD_TOKENIZED: %o', event);
        // add card token to the form
        Checkout.addCardToken(form, data.token);
        // submit the form
        form.submit();
      },
    };
  </script>
</body>
```

### Including billing details

Use cardholder and `billingAddress` attributes to send the customer's details. In the example, we have added the customer's billing details to a Frames form.

```html
<body>
  {"<!--"} add frames script -->
  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>

  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
    <div class="card-frame">{"<!--"} form is added here --></div>
    {"<!--"} add submit button -->
    <button id="pay-button" disabled>PAY GBP 24.99</button>
  </form>

  <script>
    var payButton = document.getElementById('pay-button');
    var form = document.getElementById('payment-form');

    Frames.init('pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14');

    Frames.addEventHandler(Frames.Events.CARD_VALIDATION_CHANGED, function (event) {
      console.log('CARD_VALIDATION_CHANGED: %o', event);

      payButton.disabled = !Frames.isCardValid();
    });

    Frames.addEventHandler(Frames.Events.CARD_SUBMITTED, function () {
      payButton.disabled = true;
      // display loader
    });

    Frames.addEventHandler(Frames.Events.CARD_TOKENIZED, function (data) {
      Frames.addCardToken(form, data.token);
      form.submit();
    });

    Frames.addEventHandler(Frames.Events.CARD_TOKENIZATION_FAILED, function (error) {
      // catch the error
    });

    form.addEventListener('submit', function (event) {
      event.preventDefault();

      Frames.cardholder = {
        name: 'John Smith',
        billingAddress: {
          addressLine1: '123 Anywhere St.',
          addressLine2: 'Apt. 456',
          zip: '123456',
          city: 'Anytown',
          state: 'Alabama',
          country: 'US',
        },
        phone: '5551234567',
      };

      Frames.submitCard();
    });
  </script>
</body>
```