Get started with Frames

Last updated: April 29, 2022

This page explains what you need to get up and running with Frames, and the different ways you can customize it.

Make sure you have your Bearer public API key to practice API calls, and use the sandbox version of the endpoint.
You can set up webhooks so that, after you securely collect the card details with Frames and make a payment request, you are notified when the payment is captured (completed). You then continue the sales fulfillment flow.

Note

Use your public key on the client side. You should never include your secret key on the client side for security reasons. Only use the secret key on the server side.

To get started using Frames, you first need to get access to its built-in features. On this page, we will reference tags suitable for HTML webpages. See our Frames React wrapper for an alternative option.

Include the CDN package in a script tag on your relevant HTML page:


1<script src="https://cdn.checkout.com/js/framesv2.min.js"></script>

Frames can be rendered either as a single iframe (displayed as one input field) or as multiple iframes (displayed as multiple input fields).

We insert an iframe between each placeholder div you put in your payment form.

We will insert a single iframe in:


1<div class="card-frame">
2  <!-- form will be added here -->
3</div>

Download sample files (.zip)

We insert iframes in the following containers:


1<div class="card-number-frame">
2  <!-- card number will be added here -->
3</div>
4<div class="expiry-date-frame">
5  <!-- expiry date will be added here -->
6</div>
7<div class="cvv-frame">
8  <!-- cvv frame will be added here -->
9</div>

Download sample files (.zip)

Before the input fields appear on your website and app, you need to initialize Frames.

In your JavaScript file, call the init (short for initialize) action on the Frames object and include your public API key within the brackets.


1Frames.init('pk_sbox_XXXX');

Frames has a collection of events that are triggered when certain actions happen. This is how your application will know when a form has been submitted, or card details tokenized. They also help you tailor the experience you want to provide to your customers.

We have listed all configuration options.

Frames can be rendered either as a single iframe (displayed as one input field) or as multiple iframes (displayed as multiple input fields).

In the single iframe case, the JavaScript library will dynamically apply an --invalid modifier to the container element class; in the multiple iframes case, the library will dynamically apply an --invalid modifier to each container element class.

Your checkout page can contain CSS declarations for styling the containers, such as to change the border color. For example, you can use the invalid modifier to render a red border if an invalid card number is entered.

The default approach is to hide the borders of input fields within the iframe input fields and style them within the checkout page as explained above, however, custom styling can be passed into Frames at initialization as shown below. This includes base, invalid, and placeholder styling options.

Make your customers feel at home by using our localization settings to change the language of your payment form. Use one of our pre-defined languages or create your own.

If the language you would like to use appears in our pre-defined list, then just set the localization parameter, for example localization: 'FR-FR'.

The pre-defined languages are:

Arabic = AR
Chinese Simplified = ZH-CH
Chinese Traditional (Hong Kong) = ZH-HK
Chinese Traditional (Taiwan) = ZH-TW
Danish = DA-DK
Dutch = NL-NL
English = EN-GB
Filipino = FIL-PH
Finnish - FI-FI
French = FR-FR
German = DE-DE
Hindi = HI-IN
Indonesian = ID-ID
Italian = IT-IT
Japanese = JA-JP
Korean = KO-KR
Malay = MS-MY
Norwegian Bokmål = NB-NO
Spanish = ES-ES
Swedish = SV-SE
Thai = TH-TH
Vietnamese = VI-VN

Placeholders are defined by the selected localization. For further customization, you can pass an object to localization.


1Frames.init({
2  publicKey: 'pk_sbox_6ff46046-30af-41d9-bf58-929022d2cd14',
3  localization: {
4    cardNumberPlaceholder: 'Card number',
5    expiryMonthPlaceholder: 'MM',
6    expiryYearPlaceholder: 'YY',
7    cvvPlaceholder: 'CVV',
8  },
9});

If you want to override the default style of Frames and customize the input element's CSS, pass a style object to the init method.

Information

Each specified rule name must be in camel case. For example, fontSize not font-size.

The table below lists all the available options.

Property name	Description
`base`	The default style.
`hover`	Rules applied when the element is hovered over.
`focus`	Rules applied when the element is focused.
`valid`	Rules applied when the element is valid.
`invalid`	Rules applied when the element is invalid.
`placeholder`	Accepts an object with `base` and `focus`.

We accept the majority of CSS rules (in camel case format), and the generated class names follow the BEM naming convention.

For example, an instance of Frames initialized with these values:


1Frames.init({
2  publicKey: 'YOUR-API-KEY',
3  style: {
4    base: {
5      color: 'black',
6      fontSize: '18px',
7    },
8    autofill: {
9      backgroundColor: 'yellow',
10    },
11    hover: {
12      color: 'blue',
13    },
14    focus: {
15      color: 'blue',
16    },
17    valid: {
18      color: 'green',
19    },
20    invalid: {
21      color: 'red',
22    },
23    placeholder: {
24      base: {
25        color: 'gray',
26      },
27      focus: {
28        border: 'solid 1px blue',
29      },
30    },
31  },
32});

Produces the following CSS rules:


1.card-number {
2  color: black;
3  font-size: 18px;
4}
5.card-number:-webkit-autofill {
6  background-color: yellow;
7}
8.card-number--autofilled {
9  background-color: yellow;
10}
11.card-number--hover {
12  color: blue;
13}
14.card-number--focus {
15  color: blue;
16}
17.card-number--valid {
18  color: green;
19}
20.card-number--invalid {
21  color: red;
22}
23input.card-number::-webkit-input-placeholder {
24  color: gray;
25}
26input.card-number::-moz-placeholder {
27  color: gray;
28}
29input.card-number:-ms-input-placeholder {
30  color: gray;
31}
32input.card-number--focus::-webkit-input-placeholder {
33  border: solid 1px blue;
34}
35input.card-number--focus::-moz-placeholder {
36  border: solid 1px blue;
37}
38input.card-number--focus:-ms-input-placeholder {
39  border: solid 1px blue;
40}
41
42.expiry-date {
43  color: black;
44  font-size: 18px;
45}
46.expiry-date:-webkit-autofill {
47  background-color: yellow;
48}
49.expiry-date--autofilled {
50  background-color: yellow;
51}
52.expiry-date--hover {
53  color: blue;
54}
55.expiry-date--focus {
56  color: blue;
57}
58.expiry-date--valid {
59  color: green;
60}
61.expiry-date--invalid {
62  color: red;
63}
64input.expiry-date::-webkit-input-placeholder {
65  color: gray;
66}
67input.expiry-date::-moz-placeholder {
68  color: gray;
69}
70input.expiry-date:-ms-input-placeholder {
71  color: gray;
72}
73input.expiry-date--focus::-webkit-input-placeholder {
74  border: solid 1px blue;
75}
76input.expiry-date--focus::-moz-placeholder {
77  border: solid 1px blue;
78}
79input.expiry-date--focus:-ms-input-placeholder {
80  border: solid 1px blue;
81}
82
83.cvv {
84  color: black;
85  font-size: 18px;
86}
87.cvv:-webkit-autofill {
88  background-color: yellow;
89}
90.cvv--autofilled {
91  background-color: yellow;
92}
93.cvv--hover {
94  color: blue;
95}
96.cvv--focus {
97  color: blue;
98}
99.cvv--valid {
100  color: green;
101}
102.cvv--invalid {
103  color: red;
104}
105input.cvv::-webkit-input-placeholder {
106  color: gray;
107}
108input.cvv::-moz-placeholder {
109  color: gray;
110}
111input.cvv:-ms-input-placeholder {
112  color: gray;
113}
114input.cvv--focus::-webkit-input-placeholder {
115  border: solid 1px blue;
116}
117input.cvv--focus::-moz-placeholder {
118  border: solid 1px blue;
119}
120input.cvv--focus:-ms-input-placeholder {
121  border: solid 1px blue;
122}

You can customize customer experiences further using the configuration options in Frames reference.

Get started with Frames

Before you begin

Note

Access Frames

Choose single or multiple iframes

Initialize Frames

Set up Frames events

Customize Frames

Single and multiple iframes

Localization

Pre-defined localization

Custom placeholders

Custom CSS

Information