Last updated 4 months ago

Rebilly namespace

Under the Rebilly namespace you will find methods for initializing FramePay and creating payment tokens from a form.

Rebilly.version

The latest FramePay version is: loading...

Rebilly.errorCodes

The errorCodes namespace, uses for overriding default error messages see configuration i18n

Rebilly.on()

The Rebilly namespace supports 2 events

  • ready
  • error

The ready event called when the Rebilly ready to mounting the elements. The error event called when the Rebilly has some api or cdn errors.

Rebilly.initialize({ /* configuration */ });
Rebilly.on('error', () => {
    // notification/re-initialize/re-mount functionality
});
Rebilly ready/error events
Rebilly.initialize({ /* configuration */ });

Rebilly.on('ready', () => {
    // will not be executed when the CDN have some errors in the initialization
    const card = Rebilly.card.mount('#mount-point');
})

Rebilly.on('error', (err) => {
    // err
    // {"code":"network-error","type":"error","message":"Initialization Error","details":[]}
})
Element mount error event
The elements also support the error event, see element-on.

Rebilly.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
Rebilly.initialize({
    publishableKey: 'pk_sandbox_1234567890',
    organizationId: 'your-organization-id', // no required property
});
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, visit Rebilly. 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
Rebilly.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',
            },
        },
    }
};

Rebilly.update()

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

Rebilly.update({/* new configuration object */})

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

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

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

The actual Rebilly configuration will be:

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

Rebilly.createToken()

Use this method to create a token from the contents of a form. FramePay will automatically look for all elements that were mounted and any input fields with a data-rebilly attribute will be parsed automatically and sent alongside the elements' data.

Alternatively you can provide an extraData object containing properties supported by the Rebilly API instead of including additional field in your form.

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

// optionally include extra data that is not found in the form
Rebilly.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();
    Rebilly.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 allows 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:

OptionDescription
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
objectoptional

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. Each item must include a label and value
  • emails, an array of objects representing email addresses. Each item must include a label and value

Required Values

Please note that the firstName and lastName values are required to create a payment token. If they are not present within your form's fields you must define them as extraData.

leadSource
objectoptional

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

  • source a UTM parameter
  • 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

Any and all of these parameters are optional.

Prevent Automatic Attribution

If you wish to prevent automatic lead source attribution from Google analytics UTM fields you can define this property as an emtpy object.

var extraData = {
   leadSource: {}
};
bic
string

the SWIFT/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 doesn't 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
Rebilly.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 allows 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, expiry and CVV in a single element for easier use
  • three separate elements for the card number, expiry or CVV

We recommend using the combined field because it is easier to integrate and provides a better user experience to your customers.

Rebilly.card.mount()

After Rebilly is initialized you can mount payment card elements into your form.

The first argument must be either 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 wish to mount three separate fields for the card number, expiry 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 = Rebilly.card.mount('#card');

// mount an expiration card element and return the instance
var cardExpiry = Rebilly.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 should be empty, their 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 wish 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 allows you to mount bank account (bban) specific fields. This will generate a FramePay element at the location you desire within your form.

Rebilly.bban.mount()

After Rebilly is initialized you can 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 either 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 = Rebilly.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/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 should be empty, their 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 wish 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.

Rebilly.iban.mount()

After Rebilly is initialized you can 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 didn't passed then will be mounted the default element for iban account number.

The selector argument must be either 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 = Rebilly.iban.mount('#iban'); // mount iban field
var bic = Rebilly.iban.mount('#iban-bic', 'bic'); // mount iban bic field
var bankName = Rebilly.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 Rebilly.iban.mount('#iban');
  • bic: a simple element to enter the SWIFT/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 should be empty, their 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 wish 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>