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.

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.update()

Use this method has the same functionality as the initialize method, but this method will update actual configuration.

Framepay.update({
  /* new configuration object */
});

The update priority. Any properties which were established and not passed in the new configuration - will stay.

Framepay.initialize({
  locale: Framepay.locale.es,
  icon: {
    display: true,
  },
  style: {
    base: {
      color: '#fff',
    },
  },
});

Framepay.update({ icon: { color: 'red', style: null } });

The actual Rebilly configuration will be:

{
    locale: 'es',
    icon: {
        display: true,
        color: 'red'
    },
    style: {} // default value
}

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 data-rebilly 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 Rebilly 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
        });
});

If a data-rebilly="token" hidden input field is detected in your form the payment token will be automatically injected. However, the payment token ID is available as token.id if you prefer manual handling.

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 data-rebilly input fields and can be provided as either form fields or as this object literal.

These options can be defined within:

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'
    },
    leadSource: {
        campaign: 'facebook',
    }
};
// 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
        });
});

data-rebilly Fields

See data-rebilly fields

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 Rebilly 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');

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:

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

2. Wrap the FramePay element within a <label>.

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

BBAN namespace

The bban namespace enables you to mount bank account (BBAN) specific fields. This will generate a FramePay element at the location you desire within your form.

Framepay.bban.mount()

After Rebilly initializes, mount BBAN elements into your form. This method requires two arguments, the first being a selector and the second being an element type.

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 bank field within.

// mount an account type element and return the instance
var accountType = Framepay.bban.mount('#account-type', 'accountType');

The supported element types for the second argument are:

• accountType: a set of inline buttons allowing the selection of the account type
• accountNumber: a simple element to enter the account number
• routingNumber: a simple element to enter the routing number
• bic: a simple element to enter the SWIFT or BIC Code
• bankName: a simple element to enter the bank name

You must include mount one of accountNumber, routingNumber into your form in order to create a token for a BBAN.

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>Account type</label>
    <div id="account-type">
      <!-- FramePay will inject the combined account type field here -->
    </div>
  </div>
  <button>Continue</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:

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

<label for="account-type">Account type</label>
<div id="account-type">
  <!-- FramePay will inject the combined account type field here -->
</div>

2. Wrap the FramePay element within a <label>.

<label
  >Account type
  <div id="account-type">
    <!-- FramePay will inject the account type field here -->
  </div>
</label>

IBAN namespace

The IBAN (International BBAN Number) namespace allows you to mount a field for accepting IBANs. This will generate a FramePay element at the location you desire within your form.

Framepay.iban.mount()

After Rebilly initializes, mount IBAN elements into your form. This method requires one or two arguments, the first being a selector and the second being an element type.

If the second argument did not pass, then it will be mounted the default element for IBAN account number.

The selector argument must be either 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 an IBAN field within.

// mount an account type element and return the instance
var iban = Framepay.iban.mount('#iban'); // mount iban field
var bic = Framepay.iban.mount('#iban-bic', 'bic'); // mount iban bic field
var bankName = Framepay.iban.mount('#iban-bank-name', 'bankName'); // mount iban Bank Name field

The supported element types for the second argument are:

• empty - mount main iban field element Framepay.iban.mount('#iban');
• bic: a simple element to enter the SWIFT or BIC Code
• bankName: a simple element to enter the Bank Name

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>IBAN number</label>
    <div id="iban">
      <!-- FramePay will inject the iban field here -->
    </div>
  </div>
  <button>Continue</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:

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

<label for="iban">IBAN number</label>
<div id="iban">
  <!-- FramePay will inject the iban field here -->
</div>

2. Wrap the FramePay element within a <label>.

<label
  >IBAN
  <div id="iban">
    <!-- FramePay will inject the iban field here -->
  </div>
</label>

PayPal Namespace

The PayPal namespace enables you to mount a PayPal button. This will generate a FramePay element at the location defined within your form.

For more information, see Set up PayPal.

Framepay.paypal.mount()

After Rebilly initializes, mount PayPal 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 PayPal field within.

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

PayPal callbacks

PayPal provides several callbacks. Access them using extraData on the mount.

// mount a PayPal element on a container `div`
var card = Framepay.paypal.mount('#paypal-container', {
    extraData: {
        onInit: () => {},
        onClick: () => {},
        onShippingChange: () => {},
        onApprove: () => {},
        onCancel: () => {},
        onError: () => {},
    }
});

Plaid namespace

The Plaid namespace enables you to mount a Plaid button. This will generate a FramePay element at the location defined within your form.

For more information, see Set up Plaid.

Framepay.plaid.mount()

After Rebilly initializes, mount Plaid 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 Plaid field within.

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

Google Pay namespace

The Google Pay namespace enables you to mount a Google Pay button. This generates a FramePay element at the location defined within your form.

For a complete set up guide, see Set up Google Pay.

Framepay.googlePay.mount()

After Rebilly initializes, mount the Google Pay element 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 attempts to resolve the element and generate a Google Pay field within.

// mount an Google Pay element on a container `div`
var googlePay = Framepay.googlePay.mount('#google-pay-container');

Apple Pay namespace

The Apple Pay namespace enables you to mount an Apple Pay button. This will generate a FramePay element at the location defined within your form.

For a complete set up guide, see Set up Apple Pay.

Framepay.applePay.mount()

After Rebilly initializes, mount the Apple Pay element 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 an Apple Pay field within.

// mount an Apple Pay element on a container `div`
var applePay = Framepay.applePay.mount('#apple-pay-container');

Samsung Pay namespace

The Samsung Pay namespace enables you to mount a Samsung Pay button. This will generate a FramePay element at the location defined within your form.

For a complete set up guide, see Set up Samsung Pay.

Framepay.samsungPay.mount()

After FramePay initializes, mount the Samsung Pay element 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 an Samsung Pay field within.

// mount an Samsung Pay element on a container `div`
var samsungPay = Framepay.samsungPay.mount('#samsung-pay-container');

Klarna BNPL namespace

The Klarna Buy Now Pay Later (BNPL) namespace enables you to mount the Klarna widget. This will generate a FramePay element at the location defined within your form.

For a complete set up guide, see Set up Klarna BNPL.

Framepay.klarna.mount()

After Rebilly initializes, mount the Klarna element 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 Klarna field within.

// mount the klarna widget on a container `div`
var klarna = Framepay.klarna.mount('#klarna-container');

errorCodes namespace

The errorCodes namespace is used for overriding default error messages. For more information, see configuration i18n.

Mount points

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

<form id="plaid-form">
  <div class="field">
    <input data-rebilly="firstName" value="Bob" placeholder="First Name" />
  </div>
  <div id="plaid-mounting-point">
    <!-- FramePay will inject the combined payment card field here -->
  </div>
</form>