Last updated

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

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

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.
leadSource
object (optional)
A lead source is Rebilly's term for the marketing campaign responsible for a customer interaction (typically a customer purchasing something).
There are two ways to collect lead source information: either you provide it explicitly within the extraData option or let FramePay collect Google UTM parameters from the web address hosting it.
If the lead source parameter is defined, all UTM parameters from the web address will be ignored.

Lead source parameters
A lead source is just some additional metadata that attaches to the customer’s record and contains attributes common from both Google analytics (UTM) and affiliate tracking applications.

All and any of the following above parameters are optional:
  • medium (a UTM parameter)
  • campaign (a UTM parameter)
  • content (a UTM parameter)
  • term (a UTM parameter)
  • affiliate (an affiliate tracking parameter)
  • subAffiliate (an affiliate tracking parameter)
  • clickId (an affiliate tracking parameter)
  • salesAgent (a sales tracking parameter)
  • currency and amount: the cost of the lead.
bic
string
The SWIFT or BIC Code.
Only for the BBAN and IBAN methods, allowed in the data-rebilly fields.
bankName
string
Bank name.
Only for the BBAN and IBAN methods, allowed in the data-rebilly 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'
    },
    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');
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:

  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>
  1. 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');
Field events
The bank element instances can be used to subscribe to events and complete additional actions afterwards.

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>
  1. 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
Field events
The `iban` element instances can be used to subscribe to events and complete additional actions afterwards.

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>
  1. 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');
Field events
PayPal element instances do not emit any events which can be subscribed to.

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: () => {},
    }
});
Event nameTrigger
onInitThe UI finishes loading.
onClickA customer clicks a button.
onShippingChangeA customer changes shipping address.
onApproveA customer approves the transaction on paypal.com. The token-ready event is also triggered by this event.
onCancelA customer cancels an approval.
onErrorPayPal experiences an error.

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');
Field events
Plaid element instances do not emit any events which can be subscribed to.

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');
Field events
Google Pay element instances do not emit any events which can be subscribed to.

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');
Field events
Apple Pay element instances do not emit any events which can be subscribed to.

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');
Field events
Klarna element instances do not emit any events which can be subscribed to.

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>