Frames reference

Last updated: February 28, 2024

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

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.

Here's a complete list of Frames configuration options.

Information

You can only create charges in currencies that have been enabled for your account. Please contact your Account Manager if you need to process payments in additional currencies.

JavaScript key	Description
`publicKey`	Bearer public API key.

JavaScript key	Description	Default
`acceptedPaymentMethods`	Allows you to provide the card schemes you accept to perform validation against the card number provided by customers. Accepted properties include: `1['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 for more information.	`EN-GB`
`namespace`	Customize the default Frames namespace.	`Frames`
`schemeChoice`	When set to `true`, Frames will detect 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 for more information.	`{}`

When you initialize Frames, you can use the modes array to customize the way Frames works and what is displayed.

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


1Frames.init({
2  publicKey: 'pk_sbox_XXXXXX',
3  modes: [Frames.modes.RIGHT_TO_LEFT],
4});

When paying out to a card, the CVV field is not mandatory, so you can initialize Frames with CVV_HIDDEN or CVV_OPTIONAL.


1Frames.init({
2  publicKey: 'pk_sbox_XXXXXX',
3  modes: [Frames.modes.CVV_HIDDEN],
4});


1Frames.init({
2  publicKey: 'pk_sbox_XXXXXX',
3  modes: [Frames.modes.CVV_OPTIONAL],
4});

Information

You can use either CVV_HIDDEN or CVV_OPTIONAL, but you cannot incorporate both.

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


1Frames.init({
2  publicKey: 'pk_sbox_XXXX',
3  modes: [Frames.modes.DISABLE_COPY_PASTE],
4});

JavaScript key Description Default

JavaScript key	Description	Default
`name`	The customer's name.	none
`billingAddress`	Transaction billing address: `1{ 2 addressLine1, 3 addressLine2, 4 zip, 5 city, 6 state, 7 country, 8}` The country field only accepts two-letter ISO country codes.	none
`phone`	The customer's phone number.	none

name

The customer's name.

none

billingAddress

Transaction billing address:


1{
2 addressLine1,
3 addressLine2,
4 zip,
5 city,
6 state,
7 country,
8}

The country field only accepts two-letter ISO country codes.

none

phone

The customer's phone number.

none

Information

When you enable Arabic as a locale, then right-to-left mode is activated by default.

JavaScript key Description Default

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

localization

Sets the language of the text used.

The available options are:

Arabic = AR
German = DE-DE
English = EN-GB
Spanish = ES-ES
Filipino = FIL-PH
French = FR-FR
Hindi = HI-IN
Indonesian = ID-ID
Italian = IT-IT
Japanese = JA-JP
Korean = KO-KR
Malay = MS-MY
Dutch = NL-NL
Chinese Simplified = ZH,CH
Chinese Traditional (Hong Kong) = ZH-HK
Chinese Traditional (Taiwan) = ZH-TW
Thai = TH-TH
Vietnamese = VI-VN

EN-GB

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 will contain data similar to the following example: `1bin: 42424242, 2scheme: VISA`
`cardSubmitted`	`CARD_SUBMITTED`	Triggered when the card form has been submitted.
`cardTokenized`	`CARD_TOKENIZED`	Triggered after a card is tokenized. The event will contain data following the example below. To view the full response schema: Go to Request a token. Scroll down to Responses. Expand 201 Reference token created successfully. 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. `1{ 2 "type": "card", 3 "token": "tok_ubfj2q76miwundwlk72vxt2i7q", 4 "expires_on": "2019-10-07T16:54:21Z", 5 "expiry_month": 6, 6 "expiry_year": 2025, 7 "scheme": "VISA", 8 "last4": 9996, 9 "bin": 454347, 10 "card_type": "CREDIT", 11 "card_category": "CONSUMER", 12 "issuer": "Test Bank", 13 "issuer_country": "US", 14 "product_id": "F", 15 "product_type": "CLASSIC", 16 "billing_address": ["..."], 17 "phone": ["..."], 18 "name": "John Smith" 19}`
`cardTokenizationFailed`	`CARD_TOKENIZATION_FAILED`	Triggered if the card tokenization fails.
`cardValidationChanged`	`CARD_VALIDATION_CHANGED`	Triggered when the state of the card validation changes. This will return: `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: `1isValid: true, 2paymentMethod: American Express, 3isPaymentMethodAccepted: false`
`ready`	`READY`	Triggered when Frames is registered on the global namespace and safe to use.

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


1Frames.addEventHandler(Frames.Events.EVENT_NAME, handler);


1Frames.init({
2  publicKey: 'pk_sbox_XXXXXX',
3  [Frames.Events.EVENT_NAME]: handler,
4});

Signature	Description	Returns
`init(object)`	Initializes (or re-initializes) Frames. Examples: `init({ publicKey: '...' })` initializes with your configuration `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 `init({...})` reinitializes Frames with another configuration	`undefined`
`isCardValid()`	Returns the state of the card form validation. Example: `Frames.isCardValid()`	boolean
`submitCard()`	Submits the card form if all form values are valid. Example: `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. Example: `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. Example: `event: Events.CARD_TOKENIZED handler: function(event){}`	`boolean`
`removeAllEventHandlers(event)`	Removes all handlers added to the event specified. Example: `event: Events.CARD_TOKENIZED`	`boolean`
`enableSubmitForm()`	Retains the entered card details and allows you to resubmit the payment form.	`undefined`

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.

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


1<body>
2  {"<!--"} add frames script -->
3  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>
4
5  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
6    <div class="card-frame">{"<!--"} form will be added here --></div>
7    {"<!--"} add submit button -->
8    <button id="pay-button" disabled>PAY GBP 24.99</button>
9  </form>
10
11  <script>
12    var payButton = document.getElementById('pay-button');
13    var form = document.getElementById('payment-form');
14
15    Frames.init('pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14');
16
17    Frames.addEventHandler(Frames.Events.CARD_VALIDATION_CHANGED, function (event) {
18      console.log('CARD_VALIDATION_CHANGED: %o', event);
19
20      payButton.disabled = !Frames.isCardValid();
21    });
22
23    form.addEventListener('submit', function (event) {
24      event.preventDefault();
25      Frames.submitCard()
26        .then(function (data) {
27          Frames.addCardToken(form, data.token);
28          form.submit();
29        })
30        .catch(function (error) {
31          // handle error
32        });
33    });
34  </script>
35</body>

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


1<body>
2  {"<!--"} add frames script -->
3  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>
4
5  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
6    <div class="card-frame">{"<!--"} form will be added here --></div>
7    {"<!--"} add submit button -->
8    <button id="pay-button" disabled>PAY GBP 24.99</button>
9  </form>
10
11  <script>
12    var payButton = document.getElementById('pay-button');
13    var form = document.getElementById('payment-form');
14
15    Frames.init({
16      publicKey: 'pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14',
17      cardValidationChanged: function () {
18        // if all fields contain valid information, the Pay now
19        // button will be enabled and the form can be submitted
20        payButton.disabled = !Frames.isCardValid();
21      },
22      cardSubmitted: function () {
23        form.disabled = true;
24        // display loader
25      },
26      cardTokenized: function (data) {
27        Frames.addCardToken(form, data.token);
28        form.submit();
29      },
30      cardTokenizationFailed: function (event) {
31        // catch the error
32      },
33    });
34
35    form.addEventListener('submit', function (event) {
36      event.preventDefault();
37      Frames.submitCard();
38    });
39  </script>
40</body>

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

Information

Use window.CKOConfig to change the namespace, or to load Frames asynchronously.


1<body>
2  {"<!--"} add frames script -->
3  <script async src="https://cdn.checkout.com/js/framesv2.min.js"></script>
4
5  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
6    <div class="card-frame">{"<!--"} form will be added here --></div>
7    {"<!--"} add submit button -->
8    <button id="pay-button" disabled>PAY GBP 24.99</button>
9  </form>
10
11  <script>
12    var payButton = document.getElementById('pay-button');
13    var form = document.getElementById('payment-form');
14
15    window.CKOConfig = {
16      publicKey: 'pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14',
17      namespace: 'Checkout',
18      ready: function () {
19        // Frames is registered on the global namespace and safe to use
20        form.addEventListener('submit', function (event) {
21          event.preventDefault();
22          Checkout.submitCard();
23        });
24      },
25      cardValidationChanged: function (event) {
26        console.log('CARD_VALIDATION_CHANGED: %o', event);
27        // if all fields contain valid information, the Pay now
28        // button will be enabled and the form can be submitted
29        payButton.disabled = !Checkout.isCardValid();
30      },
31      cardSubmitted: function () {
32        payButton.disabled = true;
33        // display loader
34      },
35      cardTokenized: function (data) {
36        console.log('CARD_TOKENIZED: %o', event);
37        // add card token to the form
38        Checkout.addCardToken(form, data.token);
39        // submit the form
40        form.submit();
41      },
42    };
43  </script>
44</body>

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.


1<body>
2  {"<!--"} add frames script -->
3  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>
4
5  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
6    <div class="card-frame">{"<!--"} form will be added here --></div>
7    {"<!--"} add submit button -->
8    <button id="pay-button" disabled>PAY GBP 24.99</button>
9  </form>
10
11  <script>
12    var payButton = document.getElementById('pay-button');
13    var form = document.getElementById('payment-form');
14
15    Frames.init('pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14');
16
17    Frames.addEventHandler(Frames.Events.CARD_VALIDATION_CHANGED, function (event) {
18      console.log('CARD_VALIDATION_CHANGED: %o', event);
19
20      payButton.disabled = !Frames.isCardValid();
21    });
22
23    Frames.addEventHandler(Frames.Events.CARD_SUBMITTED, function () {
24      payButton.disabled = true;
25      // display loader
26    });
27
28    Frames.addEventHandler(Frames.Events.CARD_TOKENIZED, function (data) {
29      Frames.addCardToken(form, data.token);
30      form.submit();
31    });
32
33    Frames.addEventHandler(Frames.Events.CARD_TOKENIZATION_FAILED, function (error) {
34      // catch the error
35    });
36
37    form.addEventListener('submit', function (event) {
38      event.preventDefault();
39
40      Frames.cardholder = {
41        name: 'John Smith',
42        billingAddress: {
43          addressLine1: '123 Anywhere St.',
44          addressLine2: 'Apt. 456',
45          zip: '123456',
46          city: 'Anytown',
47          state: 'Alabama',
48          country: 'US',
49        },
50        phone: '5551234567',
51      };
52
53      Frames.submitCard();
54    });
55  </script>
56</body>

Frames reference

Supported browsers

Required configurations

Information

Optional configurations

Turn on optional modes

Right-to-left

Hide the CVV field

Information

Additional security

Customer details

Localization options

Information

Events

Adding an event handler

Actions

Functions

Examples

Using the submitCard Promise

Using the cardTokenized handler

Loading Frames asynchronously

Information

Including billing details