Skip to content
Integrate / Frames / Frames reference

Frames reference

Last updated: 14th July 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

Bearer public API key.

Optional configurations

Javascript keyDescriptionDefault

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
3
4
5
6
7
8
9
10
[
  "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

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.

1
2
3
4
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 is not mandatory, so you can initialize Frames with CVV_HIDDEN or CVV_OPTIONAL.

    1
    2
    3
    4
    Frames.init({
      publicKey: "pk_sbox_XXXXXX",
      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_sbox_XXXX",
      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. You can find a full list of these here.

    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 keyDescriptionDefault

    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

    Events

    Event nameJavascript constantDescription

    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

    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
    20
    21
    22
    23
    {
       "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.

    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:

    1
    2
    3
    isValid: true, 
    paymentMethod: American Express,
    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.

      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

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

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

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

      </body>

      On this page

      Supported browsers
      Required configurations
      Optional configurations
      Turn on optional modes
      Customer details
      Localization options
      Events
      Adding an event handler
      Actions
      Functions
      Examples