Frames reference

Our Frames reference is here to help you find those hard-to-find bits of information all in one place.

Configuration options

Here's a complete list of Frames configuration options.

Required

📘
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
`publicKey`	Your public key. You can find it in the Hub.

Optional

Javascript key	Description	Default
`debug`	Set to `true` to view console messages.	`false`
`namespace`	Customize the default Frames namespace.	`Frames`
`frameSelector`	The .class or #id of the parent elements in the Frames payment form.	none
`localization`	`localization` allows you to use one of the supported languages or a custom object. Refer to the customization guide for more information.	`EN-GB`
`style`	`style` allows customizing the look and feel of Frames' controlled fields. Refer to the customization guide for more information.	`{}`

Customer details

📘
cardholder is the only way to send customer details when using Frames.

Javascript key	Description	Default
`name`	The customer's name.	none
`billingAddress`	Transaction billing address: `{ addressLine1, addressLine2, zip, city, state, country, }` The `country` field only accepts two-letter ISO country codes. You can find a full list of these here.	none
`phone`	The customer's phone number	none

Javascript key

Description

Default

name

The customer's name.

none

billingAddress

Transaction billing address:

{
  addressLine1,
  addressLine2,
  zip,
  city,
  state,
  country,
}

The country field only accepts two-letter ISO country codes. You can find a full list of these here.

none

phone

The customer's phone number

none

Localization options

Javascript key	Description	Default
`localization`	Sets the language of the text used. The available options are: `EN-GB` (English) `ES-ES` (Spanish) `DE-DE` (German) `KR-KR` (Korean) `FR-FR` (French) `IT-IT` (Italian) `NL-NL` (Dutch)	`EN-GB`

Javascript key

Description

Default

localization

Sets the language of the text used.

The available options are:

EN-GB (English)
ES-ES (Spanish)
DE-DE (German)
KR-KR (Korean)
FR-FR (French)
IT-IT (Italian)
NL-NL (Dutch)

EN-GB

Events

Event name	JavaScript constant	When
`ready`	`READY`	Triggered when Frames is registered on the global namespace and safe to use.
`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.
`cardValidationChanged`	`CARD_VALIDATION_CHANGED`	Triggered when the state of the card validation changes. This will return: `isValid: true / false`
`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 this example: `{ type: card, token: tok_ubfj2q76miwundwlk72vxt2i7q, expires_on: 2019-10-07T16:54:21Z, expiry_month: 6, expiry_year: 2025, scheme: VISA, last4: 9996, bin: 454347, card_type: Credit, card_category: Consumer, issuer: GOTHAM STATE BANK, issuer_country: US, product_id: F, product_type: CLASSIC, billing_address: [...], phone: [...], name: Jack Napier }`
`cardTokenizationFailed`	`CARD_TOKENIZATION_FAILED`	Triggered if the card tokenization fails.

Adding an event handler

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

Frames.addEventHandler(Frames.Events.<EVENT_CONSTANT>, handler);

Frames.init({
  publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
  <eventName>: 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.

🚧
Internet Explorer 11 and below
We have identified some issues with Frames.submitCard().then in older browsers. We're working on resolving these as soon as possible, but recommend using the CARD_TOKENIZED event handler if you expect any of your users to be using Internet Explorer 11 and below.

<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 will be 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_test_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.

<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 will be 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_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      cardValidationChanged: function () {
        // if all fields contain valid information, the Pay now
        // button will be enabled and the form can be submitted
        form.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 example below uses Checkout as the namespace.

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

<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 will be 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_test_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 will be 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.

<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 will be 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_test_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: "623 Slade Street",
          addressLine2: "Apartment 8",
          zip: "31313",
          city: "Hinesville",
          state: "Georgia",
          country: "US",
        },
        phone: "9125084652"
      };

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

</body>

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].

Frames reference

Configuration options

Required

📘
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.

Optional

Customer details

📘
`cardholder` is the only way to send customer details when using Frames.

Localization options

Events

Adding an event handler

Actions

Functions

Examples

Using the submitCard Promise

🚧
Internet Explorer 11 and below

Using the cardTokenized handler

Loading Frames asynchronously

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

Including billing details

Can we help?

Configuration options

Required

📘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.

Optional

Customer details

📘cardholder is the only way to send customer details when using Frames.

Localization options

Events

Adding an event handler

Actions

Functions

Examples

Using the submitCard Promise

🚧Internet Explorer 11 and below

Using the cardTokenized handler

Loading Frames asynchronously

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

Including billing details

Can we help?

📘
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.

📘
`cardholder` is the only way to send customer details when using Frames.

🚧
Internet Explorer 11 and below

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