Overview

The Frame JavaScript SDK provides developers with a powerful toolkit for collecting sensitive payment details through customizable components. It's designed to integrate seamlessly with your web applications, offering a secure and efficient way to handle payments.

What is Frame.js?

Frame.js is a lightweight JavaScript SDK designed to seamlessly integrate Frame Payments functionality directly into your web applications. By embedding our compact library via our CDN into the <head> or <body> of your page, you can swiftly begin leveraging Frame.js to facilitate secure payment transactions.

You can kickstart your integration with Frame.js by including the following script tag within your HTML file:

<script src="https://js.framepayments.com/v1/index.js"></script>

At Frame Payments, we are committed to delivering ongoing updates to enhance functionality and elevate the developer experience. By regularly updating Frame.js, we ensure that you have access to the latest features and crucial security patches.

Important Note:

We strongly advise against self-hosting Frame.js, as this may result in missing out on new features and vital security enhancements. Opting for our CDN-hosted solution guarantees seamless integration and ensures you're always up-to-date with the latest improvements.

Installation

Our JavaScript SDK is conveniently distributed via our CDN, making installation as simple as adding a single script tag to your HTML file. You can place this script tag either within the <head> section or just before the closing </body> tag.

<script src="https://js.framepayments.com/v1/index.js"></script>

Note: It's imperative to always load the Frame.js script directly from https://js.framepayments.com rather than including it in a bundle or hosting it yourself.

Asynchronous loading of JavaScript is generally recommended, as it can improve the user experience of you site by not blocking DOM rendering during script loading. You can achieve this by using the async or defer attribute on the script tag. However, bear in mind that with asynchronous loading, any API calls must be made only after the script execution is complete.

Initializing Frame.js

After installation, initialize the JavaScript SDK with your publishable API key, which can be found in the Frame Developer section.

const frame = await Frame.init("<PUBLISHABLE_KEY>");

The provided publishable API key is essential as it identifies your website to Frame. Remember to replace the test key with your live key when you're ready to accept live payments in production.

It's important to note that using the same publishable API key and options, you should create and share a single instance of the Frame object to avoid potential performance issues.

Full example

Here's a complete example demonstrating the integration of Frame.js into your web application. You can simply copy and paste the code snippet below (replacing <PUBLISHABLE_KEY> with your actual publishable API key), run it in your environment, and begin accepting payments.

<body>
  <div id="app">
    <form>
      <div id="card-details"></div>
    </form>
  </div>
  <script src="https://js.framepayments.com/v1/index.js"></script>
  <script>
    (async () => {
      const frame = await Frame.init("<PUBLISHABLE_KEY>");
      const card = await frame.createElement("card", { theme: frame.themes("clean") });
      card.on("complete", payload => {
        console.log(payload)
      })
      card.mount("#card-details");
    })();
  </script>
</body>

Environments

Frame.js operates in two environments: sandbox and production. We strongly recommend using sandbox mode during development and transitioning to production once you're confident with your integration. The environment is determined by the API key you provide when initializing Frame.js.

If your API key begins with pk_sandbox, Frame.js is running in sandbox mode. Conversely, if it starts with pk_production, Frame.js is operating in production mode.

Be aware that in sandbox mode, you're restricted to using only test cards for payments. For more information on how to test your integration, refer to the testing by cards section.

Error Handling

Frame.js provides several types of errors that reflect the validity of each field. These errors can be accessed through the errors key in the payload. For more information, see the change event section.

Error handling typically occurs within the change event, which indicates field validity as values change. The following error types are available:

Type	Description
`invalid`	Applies to all fields. For example, leaving the `cvc` field empty triggers this error. This error type is also displayed in the UI.
`require_test_cards`	This is special error type for `number` field. This error type tell you that the entered card number is not a test card. This only be fire in `sandbox` mode.

The simplest way to handle errors is by listening to the change event and checking if the errors key is non-null. Here's a basic example:

card.on("change", (payload) => {
  if (payload.errors !== null) {
    // Implement error message display logic here
  }
});

Important

Due to some limitations, you should handle the require_test_cards error yourself. We strongly advise you to listen for the change event to catch and handle this error type.

API Reference

window.Frame.init(publishableKey)

The init method allows for asynchronous initialization of the SDK, accepting one parameter:

publishableKey: The Publishable API key obtained from the Frame Developer section.

const frame = await Frame.init("<PUBLISHABLE_KEY>");

Parameter	Type	Required	Description
`publishableKey`	`String`	yes	The Publishable API key. This can be found in the Frame Developer.

frame.createElement("card", options)

Initializes a Card UI Component, simplifying the collection of payment details.

const frame = await Frame.init("<PUBLISHABLE_KEY>");
const card = await frame.createElement("card", {
  theme: frame.themes("clean")
});

card.mount("#card-details");

options

Parameter	Type	Description
`theme`	`String`	Optional, valid options `clean`, `minimal`, or `material`
`autoFocus`	`Boolean`	If set to `true`, the component will automatically steal focus when it mounts.
`fields`	`String[]`	Allows you to configure the fields displayed in the component. Possible values are `name`, `number`, `expiry`, and `cvc`. By default only `number`, `expiry` and `cvc` will be shown.
`translations`	`Object`	Allows you to customize the text shown inside of the component.

translations

Parameter	Type	Description
`name.label`	`String`	Customize the label for the name field.
`name.placeholder`	`String`	Customize the placeholder for the name field.
`name.errors.invalid`	`String`	Customize the error message for when the name field is invalid.
`number.label`	`String`	Customize the label for the number field.
`number.placeholder`	`String`	Customize the placeholder for the number field.
`number.errors.invalid`	`String`	Customize the error message for when the number field is invalid.
`expiry.label`	`String`	Customize the label for the expiry field.
`expiry.placeholder`	`String`	Customize the placeholder for the expiry field.
`expiry.errors.invalid`	`String`	Customize the error message for when the expiry field is invalid.
`cvc.label`	`String`	Customize the label for the CVC field.
`cvc.placeholder`	`String`	Customize the placeholder for the CVC field.
`cvc.errors.invalid`	`String`	Customize the error message for when the CVC field is invalid.

card.mount()

Mounts the component to a specified DOM node.

card.mount("#card-details");

card.on("change")

Subscribes to changes made to the component. Access encrypted card details from the payload passed to the callback.

card.on("change", payload => {
  console.log(payload.card.number);
});

payload

	Type	Description
`card`	`Object`	Information about the entered card, including meta data as well as the encrypted number and CVC.
`card.name`	`String`	The card holder name.
`card.number`	`String`	The encrypted card number. This will only be present if the number is valid.
`card.brand`	`String`	The brand that issued the card.
`card.lastFour`	`String`	The last 4 digits of the card. This will only be present if the number is valid.
`card.bin`	`String`	The bin for the card. This will only be present if the number id valid.
`card.expiry.month`	`String`	The month for the card expiry field.
`card.expiry.year`	`String`	The year for the card expiry field.
`card.cvc`	`String`	The encrypted card CVC.
`errors`	`{ [field]: String }`	Validation errors related to the card details.
`isValid`	`Boolean`	Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the `.validate` method.
`isComplete`	`Boolean`	Whether or not all of the fields have been filled out successfully with valid values.

card.on("complete")

Fires once the user has successfully filled out all fields in the Card Component with valid values.

card.on("complete", payload => {
  console.log(payload.card.number);
});

payload

	Type	Description
`card`	`Object`	Information about the entered card, including meta data as well as the encrypted number and CVC.
`card.name`	`String`	The card holder name.
`card.number`	`String`	The encrypted card number. This will only be present if the number is valid.
`card.brand`	`String`	The brand that issued the card.
`card.lastFour`	`String`	The last 4 digits of the card. This will only be present if the number is valid.
`card.bin`	`String`	The bin for the card. This will only be present if the number id valid.
`card.expiry.month`	`String`	The month for the card expiry field.
`card.expiry.year`	`String`	The year for the card expiry field.
`card.cvc`	`String`	The encrypted card CVC.
`errors`	`{ [field]: String }`	Validation errors related to the card details.
`isValid`	`Boolean`	Whether or not there are any errors shown. Validation occurs as the user looses focus on a field. You can force validation to occur with the `.validate` method.
`isComplete`	`Boolean`	Whether or not all of the fields have been filled out successfully with valid values.

card.on("ready")

Fires once the component has fully loaded and is ready to be displayed.

card.on("ready", () => {
  document.getElementById("loading").addClass("hide");
  document.getElementById("card-details").removeClass("hide");
});

card.on("error")

Fires if the component fails to load. Use the change event to respond to validation errors instead.

card.on("error", () => {
  alert("Opps, something went wrong!");
});

card.update(options)

Updates the configuration for the component after initialization. Any arguments passed will be merged with the initial configuration.

card.update({
  translations: {
    number: {
      label: "Your card number"
    }
  }
});

options

Parameter	Type	Description
`theme`	`String`	Optional, valid options `clean`, `minimal`, or `material`
`autoFocus`	`Boolean`	If set to `true`, the component will automatically steal focus when it mounts.
`fields`	`String[]`	Allows you to configure the fields displayed in the component. Possible values are `name`, `number`, `expiry`, and `cvc`. By default only `number`, `expiry` and `cvc` will be shown.
`translations`	`Object`	Allows you to customize the text shown inside of the component.

translations

Parameter	Type	Description
`name.label`	`String`	Customize the label for the name field.
`name.placeholder`	`String`	Customize the placeholder for the name field.
`name.errors.invalid`	`String`	Customize the error message for when the name field is invalid.
`number.label`	`String`	Customize the label for the number field.
`number.placeholder`	`String`	Customize the placeholder for the number field.
`number.errors.invalid`	`String`	Customize the error message for when the number field is invalid.
`expiry.label`	`String`	Customize the label for the expiry field.
`expiry.placeholder`	`String`	Customize the placeholder for the expiry field.
`expiry.errors.invalid`	`String`	Customize the error message for when the expiry field is invalid.
`cvc.label`	`String`	Customize the label for the CVC field.
`cvc.placeholder`	`String`	Customize the placeholder for the CVC field.
`cvc.errors.invalid`	`String`	Customize the error message for when the CVC field is invalid.

card.validate()

Manually triggers validation for the card details fields.

card.validate();

card.unmount()

Removes the component from the DOM.

card.unmount();