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:

INCLUDE FRAME.JS

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

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.

FRAME.JS SCRIPT TAG

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

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

INITIALIZE FRAME.JS

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.

Elements

Frame.js provides the following elements for building your payment experience:

Card — Secure card input. Optionally configurable to include a billing address form and identity fields (name, email, phone)
Terms of Service — Customizable TOS acceptance component
Payment Request Button — Apple Pay and Google Pay wallet buttons

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 Card element 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.

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.

FRAME.INIT EXAMPLE

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.