/ /

Frames reference

Last updated: October 26, 2022

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

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. Please contact your Customer Success manager if you need to process payments in additional currencies.

Javascript key Description

Javascript key	Description
`publicKey`	Your public key. You can find it in the Hub.

publicKey

Your public key.

You can find it in the Hub.

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. Accepted properties include: `1[ 2 "Visa", 3 "Maestro", 4 "Mastercard", 5 "American Express", 6 "Diners Club", 7 "Discover", 8 "JCB", 9 "Mada" 10]`	`{}`
`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`
`style`	Allows you to customize the look and feel of Frames' controlled fields. Refer to the Frames customization guide for more information.	`{}`

Turn on optional modes

When you 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.

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

Hide the CVV field

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_test_XXXXXX",
3  modes: [ Frames.modes.CVV_HIDDEN]
4});

Information

Please note that either the CVV_HIDDEN or CVV_OPTIONAL can be used. You cannot incorporate both.

Additional security

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

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

Customer details

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

Localization options

Arabic language and right-to-left mode

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

Javascript key	Description	Default
`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`

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 will contain data similar to the following example: `1bin: 42424242, 2 scheme: 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": "GOTHAM STATE BANK", 13 "issuer_country": "US", 14 "product_id": "F", 15 "product_type": "CLASSIC", 16 "billing_address": { 17 "address_line1": "Checkout.com", 18 "address_line2": "90 Tottenham Court Road", 19 "city": "London", 20 "state": "London", 21 "zip": "W1T 4TJ", 22 "country": "GB" 23 }, 24 "phone": { 25 "number": "4155552671", 26 "country_code": "+1" 27 }, 28 "name": "Bruce Wayne" 29}
`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.

Adding an event handler

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

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

Actions

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`

Functions

Getter	Setter	Description
`publicKey`	`publicKey = value`	Your public key. You can find it in the Hub.
`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 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">
7      <!-- form will be added here -->
8    </div>
9    <!-- add submit button -->
10    <button id="pay-button" disabled>
11      PAY GBP 24.99
12    </button>
13  </form>
14
15  <script>
16    var payButton = document.getElementById("pay-button");
17    var form = document.getElementById("payment-form");
18
19    Frames.init("pk_test_6ff46046-30af-41d9-bf58-929022d2cd14");
20
21    Frames.addEventHandler(
22      Frames.Events.CARD_VALIDATION_CHANGED,
23      function (event) {
24        console.log("CARD_VALIDATION_CHANGED: %o", event);
25
26        payButton.disabled = !Frames.isCardValid();
27      }
28    );
29
30    form.addEventListener("submit", function (event) {
31      event.preventDefault();
32      Frames.submitCard()
33        .then(function (data) {
34          Frames.addCardToken(form, data.token);
35          form.submit();
36        })
37        .catch(function (error) {
38          // handle error
39        });
40    });
41  </script>
42</body>

Using the cardTokenized handler

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">
7      <!-- form will be added here -->
8    </div>
9    <!-- add submit button -->
10    <button id="pay-button" disabled>
11      PAY GBP 24.99
12    </button>
13  </form>
14
15  <script>
16    var payButton = document.getElementById("pay-button");
17    var form = document.getElementById("payment-form");
18
19    Frames.init({
20      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
21      cardValidationChanged: function () {
22        // if all fields contain valid information, the Pay now
23        // button will be enabled and the form can be submitted
24        payButton.disabled = !Frames.isCardValid();
25      },
26      cardSubmitted: function () {
27        form.disabled = true;
28        // display loader
29      },
30      cardTokenized: function (data) {
31        Frames.addCardToken(form, data.token)
32        form.submit()
33      },
34      cardTokenizationFailed: function (event) {
35        // catch the error
36      }
37    });
38
39    form.addEventListener('submit', function (event) {
40      event.preventDefault();
41      Frames.submitCard();
42    });
43  </script>
44</body>

Loading Frames asynchronously

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

Tip

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

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

1<body>
2
3  <!-- add frames script -->
4  <script src="https://cdn.checkout.com/js/framesv2.min.js"></script>
5
6  <form id="payment-form" method="POST" action="https://merchant.com/charge-card">
7    <div class="card-frame">
8      <!-- form will be added here -->
9    </div>
10    <!-- add submit button -->
11    <button id="pay-button" disabled>
12      PAY GBP 24.99
13    </button>
14  </form>
15
16  <script>
17    var payButton = document.getElementById("pay-button");
18    var form = document.getElementById("payment-form");
19
20    Frames.init("pk_test_6ff46046-30af-41d9-bf58-929022d2cd14");
21
22    Frames.addEventHandler(
23      Frames.Events.CARD_VALIDATION_CHANGED,
24      function (event) {
25        console.log("CARD_VALIDATION_CHANGED: %o", event);
26
27        payButton.disabled = !Frames.isCardValid();
28      }
29    );
30
31    Frames.addEventHandler(
32      Frames.Events.CARD_SUBMITTED,
33      function () {
34        payButton.disabled = true;
35        // display loader
36      }
37    );
38
39    Frames.addEventHandler(
40      Frames.Events.CARD_TOKENIZED,
41      function (data) {
42        Frames.addCardToken(form, data.token);
43        form.submit();
44      }
45    );
46
47    Frames.addEventHandler(
48      Frames.Events.CARD_TOKENIZATION_FAILED,
49      function (error) {
50        // catch the error
51      }
52    );
53
54    form.addEventListener("submit", function (event) {
55      event.preventDefault();
56
57      Frames.cardholder = {
58        name: "John Smith",
59        billingAddress: {
60          addressLine1: "623 Slade Street",
61          addressLine2: "Apartment 8",
62          zip: "31313",
63          city: "Hinesville",
64          state: "Georgia",
65          country: "US",
66        },
67        phone: "9125084652"
68      };
69
70      Frames.submitCard();
71    });
72  </script>
73
74</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

Arabic language and right-to-left mode

Events

Adding an event handler

Actions

Functions

Examples

Using the submitCard Promise

Using the cardTokenized handler

Loading Frames asynchronously

Tip

Including billing details

On this page

We've made some changes to our API