Skip to content

Frames reference

Last updated: 13th January 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:

  • Internet Explorer (IE11+) and Edge
  • Chrome, Safari and Firefox on all devices

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.

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 keyDescription

publicKey

Your public key.

You can find it in the Hub.


Optional configurations

Javascript keyDescriptionDefault

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.

{}


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.

    1
    2
    3
    4
    Frames.init({
    publicKey: "pk_test_8ac41c0d-fbcc-4ae3-a771-31ea533a2beb",
    modes: [ Frames.modes.CVV_HIDDEN]
    });

    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.

    1
    2
    3
    4
    Frames.init({
    publicKey: "pk_test_8ac41c0d-fbcc-4ae3-a771-31ea533a2beb",
    modes: [ Frames.modes.DISABLE_COPY_PASTE ]
    });

    Customer details

    Javascript keyDescriptionDefault

    name

    The customer's name.

    none

    billingAddress

    Transaction billing address:

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

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

    none

    phone

    The customer's phone number.

    none


    Localization options

    Javascript keyDescriptionDefault

    localization

    Sets the language of the text used.

    The available options are:

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

    EN-GB


    Events

    Event nameJavascript constantDescription

    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 the example below.

    To view the full response schema:

    1. Go to Request a token.
    2. Scroll down to Responses.
    3. Expand 201 Reference token created successfully.
    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.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    {
    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: Bruce Wayne
    }

    cardTokenizationFailed

    CARD_TOKENIZATION_FAILED

    Triggered if the card tokenization fails.

    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:

    1
    2
    bin: 42424242,
    scheme: VISA

    Adding an event handler

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

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

      Actions

      SignatureDescriptionReturns

      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

      GetterSetterDescription

      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
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      <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.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      <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
      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 example below uses Checkout as the namespace.

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

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      <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.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68
      69
      70
      71
      72
      73
      74
      <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>