API Reference

Our reference library for integrating with our API


Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Frames customization guide

Customize Frames

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

Single iframe

In the single iframe case, Frames' JavaScript library will dynamically apply an --invalid modifier to the container element class.

Multiple iframes

In the multiple iframes case, Frames' JavaScript 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.

Pre-defined localization

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:

  • English = EN-GB
  • Dutch = NL-NL
  • French = FR-FR
  • German = DE-DE
  • Italian = IT-IT
  • Korean = KO-KR
  • Spanish = ES-ES

Custom placeholders

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

  publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
  localization: {
    cardNumberPlaceholder: "Card number",
    expiryMonthPlaceholder: "MM",
    expiryYearPlaceholder: "YY",
    cvvPlaceholder: "CVV",

Custom CSS

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.

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

The table below lists all the available options.

Property nameDescription
baseThe default style.
hoverRules applied when the element is hovered over.
focusRules applied when the element is focused.
validRules applied when the element is valid.
invalidRules applied when the element is invalid.
placeholderAccepts 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:

  publicKey: "YOUR-API-KEY",
  style: {
    base: {
      color: "black",
      fontSize: "18px"
    autofill: {
      backgroundColor: "yellow"
    hover: {
      color: "blue"
    focus: {
      color: "blue"
    valid: {
      color: "green"
    invalid: {
      color: "red"
    placeholder: {
      base: {
        color: "gray"
      focus: {
        border: "solid 1px blue"

Produces the following CSS rules:

.card-number {color: black;font-size: 18px;}
.card-number:-webkit-autofill {background-color: yellow;}
.card-number--autofilled {background-color: yellow;}
.card-number--hover {color: blue;}
.card-number--focus {color: blue;}
.card-number--valid {color: green;}
.card-number--invalid {color: red;}
input.card-number::-webkit-input-placeholder {color: gray;}
input.card-number::-moz-placeholder {color: gray;}
input.card-number:-ms-input-placeholder {color: gray;}
input.card-number--focus::-webkit-input-placeholder {border: solid 1px blue;}
input.card-number--focus::-moz-placeholder {border: solid 1px blue;}
input.card-number--focus:-ms-input-placeholder {border: solid 1px blue;}

.expiry-date {color: black;font-size: 18px;}
.expiry-date:-webkit-autofill {background-color: yellow;}
.expiry-date--autofilled {background-color: yellow;}
.expiry-date--hover {color: blue;}
.expiry-date--focus {color: blue;}
.expiry-date--valid {color: green;}
.expiry-date--invalid {color: red;}
input.expiry-date::-webkit-input-placeholder {color: gray;}
input.expiry-date::-moz-placeholder {color: gray;}
input.expiry-date:-ms-input-placeholder {color: gray;}
input.expiry-date--focus::-webkit-input-placeholder {border: solid 1px blue;}
input.expiry-date--focus::-moz-placeholder {border: solid 1px blue;}
input.expiry-date--focus:-ms-input-placeholder {border: solid 1px blue;}

.cvv {color: black;font-size: 18px;}
.cvv:-webkit-autofill {background-color: yellow;}
.cvv--autofilled {background-color: yellow;}
.cvv--hover {color: blue;}
.cvv--focus {color: blue;}
.cvv--valid {color: green;}
.cvv--invalid {color: red;}
input.cvv::-webkit-input-placeholder {color: gray;}
input.cvv::-moz-placeholder {color: gray;}
input.cvv:-ms-input-placeholder {color: gray;}
input.cvv--focus::-webkit-input-placeholder {border: solid 1px blue;}
input.cvv--focus::-moz-placeholder {border: solid 1px blue;}
input.cvv--focus:-ms-input-placeholder {border: solid 1px blue;}