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();