FramePay reference

This section describes the methods exposed by the Framepay namespace.

Framepay.initialize()

Use this method to initialize FramePay with your publishable API key and customize the look and feel of elements.

It accepts a single configuration object.

// the basic configuration must contain your publishable API key
Framepay.initialize({
  publishableKey: 'pk_sandbox_1234567890',
  organizationId: 'your-organization-id', // no required property
});

For an overview of the configuration options, see configuration reference.

Use your own publishable key You must replace the key pk_sandbox_1234567890 with your own. We recommend starting with a sandbox key. To create a publishable key, see Create an API key. A key is specific to either the sandbox or live environment.

The configuration must contain at a publishableKey otherwise an error will be thrown. It can optionally define CSS styles and className names to overwrite the style of FramePay.

For the configuration details please take a look at configuration.

// first call
Framepay.initialize(config);

// where config is
const config = {
  icon: {
    // icon for combined field
    display: true, // false to hide
  },
  classes: {}, // when needed,
  style: {
    base: {
      // shared `base` state
      color: '#fff', // generic JS property for DOM style
      '::placeholder': {
        // access to pseudo-element
        color: 'gray', // overwrite placeholder color only
      },
    },
    invalid: {
      color: 'red',
      '::placeholder': {
        color: 'firebrick',
      },
    },
  },
};

Framepay.on()

FramePay uses events to notify of state changes or errors, see Events.

Framepay.createToken()

Use this method to create a payment token.

For payment methods that use a form, FramePay parses input fields with a token data attributes and collects its values when you pass the form to the Framepay.createToken() method.

Optionally, instead of including an additional field in your form, provide an extraData object containing properties supported by the Framepay API.

// create a token from the fields within a form
Framepay.createToken(form);

// optionally include extra data that is not found in the form
Framepay.createToken(form, extraData);

This method returns a Promise with a single argument representing the API result of the operation. Validation or network errors can be caught using a catch() handler and displayed to the customer.

var form = document.querySelector('form');
form.addEventListener('submit', function (event) {
  event.preventDefault();
  Framepay.createToken(form)
    .then(function (token) {
      // if we have a token field in the form
      // we can submit directly
      form.submit();
    })
    .catch(function (error) {
      // see error.code and error.message
    });
});

The payment token ID is available as token.id.

In order for the token creation to work you must mount fields before triggering createToken.

Extra data

The extraData argument is optional and enables you to define specific values to include in your payment token request. The billing address values match the properties supported by token data input fields and can be provided as either form fields or as this object literal.

These options can be defined within:

Option	Description
method string	When provided, FramePay will attempt to process the form data to generate a payment token for this method. We recommended always defining this property. Multiple methods: This property is required when using multiple payment methods at the same time in a form or when using methods other than payment-card or ach. Accepts any of the methods supported by PaymentsAI.
billingAddress object (optional)	This object defines the billing address of the customer. These keys can be provided: firstName lastName organization address address2 city region country postalCode phoneNumbers an array of objects representing phone numbers with label and value emails an array of objects representing email addresses with label and value. Required values Note that the firstName and lastName values are required to create a payment token. If they are not present within the fields of your form, you must define them as extraData.
bic string	The SWIFT or BIC Code. Only for the BBAN and IBAN methods, allowed in the token data fields.
bankName string	Bank name. Only for the BBAN and IBAN methods, allowed in the token data fields.

For example, if your form gathered the customer's name at a previous step and does not include the fields in the form used to create the token, then you would define it as extra data:

// within the event listener for the form submit
var extraData = {
  billingAddress: {
    firstName: 'John',
    lastName: 'Doe',
  },
};
// define extra data as the second argument
Framepay.createToken(form, extraData)
  .then(function (token) {
    // if we have a token field in the form
    // we can submit directly
    form.submit();
  })
  .catch(function (error) {
    // see error.code and error.message
  });

Card namespace

The card namespace enables you to mount payment card specific fields. This will generate a FramePay element at the location you desire within your form.

You can choose to use either:

• a combined element, that includes the number, expiration and CVV in a single element for easier use
• three separate elements for the card number, expiration or CVV We recommend using the combined field because it is easier to integrate and provides a better user experience to your customers.

Framepay.card.mount()

After FramePay initializes, mount payment card elements into your form.

The first argument must be: a DOM element, a valid string DOM selector, or an instance of a jQuery or Zepto object that wraps an element within the page. FramePay will attempt to resolve the element and generate a card field within.

By default a combined card element will be generated. However if you want to mount three separate fields for the card number, expiration and CVV you can provide a second argument to define the type of element to generate.

// mount a combined card element on a container `div`
var card = Framepay.card.mount('#card');

// mount an expiration card element and return the instance
var cardExpiration = Framepay.card.mount('#card-expiration', 'cardExpiration');

Field events

The card element instances can be used to subscribe to events and complete additional actions afterwards. The supported element types for the second argument are:

cardNumber, a payment card element with automatic formatting cardExpiration, an expiration month and expiration year element with automatic formatting cardCvv, a CVV element Please note that when specifying the element types you must include one of each type in your form.

Mounting points

The mounting points within your form must be empty. Any existing content will be replaced with the FramePay element.

<form method="post" action="/process">
  <div className="field">
    <label>Payment card</label>
    <div id="card">
      <!-- FramePay will inject the combined payment card field here -->
    </div>
  </div>
  <button>Checkout</button>
</form>

Labels

When a <label> is present in your form and you want to automatically focus on the FramePay element once the label is clicked. There are 2 different ways to achieve this:

Add the for attribute to the <label>, referencing the ID of your container.

<label for="card">Payment card</label>
<div id="card">
  <!-- FramePay will inject the combined payment card field here -->
</div>

Wrap the FramePay element within a <label>.

<label
  >Payment card
  <div id="card">
    <!-- FramePay will inject the combined payment card field here -->
  </div>
</label>