Set up a payment card method

This topic describes how to add FramePay to a checkout form and use it to tokenize payment card information.

For an interactive example of this implementation, see Interactive example.

1. Include FramePay

1.1 Include FramePay script

To enable FramePay, include the following line in your checkout page. This exposes the library in the global JS scope as Rebilly.

Copy
Copied
<script src="https://framepay.rebilly.com/rebilly.js"></script>
Automatic updates

Backward-compatible updates will be made available automatically without the need to change this URL.

1.2 Optionally, include default css styles

By default, FramePay does not inject CSS styles for the elements that are generated into your checkout form. However, we provide a CSS file that you can use to give elements a default look.

To enable default FramePay styles, include the following line in your checkout page:

Copy
Copied
<link href="https://framepay.rebilly.com/rebilly.css" rel="stylesheet">

Here is an example of a basic payment card element that is styled using the default rebilly.css:

2. Create your checkout form

2.1 Add customer information inputs to your form

FramePay automatically gathers data from your checkout form.

To enable this, you must use data-rebilly attributes on your input fields.

Create a basic customer information form:

Copy
Copied
<form>
    ...
    <!-- FramePay will automatically gather these input field's values. -->
    <input data-rebilly="firstName" placeholder="First Name">
    <input data-rebilly="lastName" placeholder="Last Name">
    ...
</form>

2.2 Add a mounting point to your form

You must specify empty HTML elements where FramePay will render the payment card inputs.

Edit your checkout form to add a new html element with a unique id, for example, a div with an id value of mounting-point:

Copy
Copied
<form>
    ...
    <input data-rebilly="firstName" placeholder="First Name">
    <input data-rebilly="lastName" placeholder="Last Name">
    ...
     <div id="mounting-point">
        <!-- FramePay will inject the payment card field here -->
     </div> 
    ...
</form>

3. Initialize FramePay

In an earlier step, you included the rebilly.js script in your checkout page. In this step you will access the globally exposed Rebilly object to initialize it.

  1. If you do not have a sandbox API key, create one.
  2. Include the following line in the JS of your checkout page, and replace the publishableKey value with your API key:
Copy
Copied
Rebilly.initialize({
        // Use your own publishable key:
        publishableKey: 'pk_sandbox_Lvl5rm8lLrtAV6iSL3CIdYLAburumF4Ld8b1KDs',
});

You must replace the key pk_sandbox_Lvl5rm8lLrtAV6iSL3CIdYLAburumF4Ld8b1KDs with your own. We recommend starting with a sandbox key. To create a publishable key, check API keys section.

4. Mount the payment card element

After initializing, FramePay will emit a ready event.

Use Rebilly.on to listen to the 'ready' event and determine when to mount the payment card method using Rebilly.card.mount:

Copy
Copied
 Rebilly.on('ready', function () {
            // #mounting-point is the unique id of the div that you added in the previous step  
            const card = Rebilly.card.mount('#mounting-point');
            // Here you can inspect your first mounted FramePay element
            console.log('💳 Payment card element: ', card);
        });

5. Create the payment card token

Once you have mounted your card element, your customer will be able to complete the form.

To send the form data to FramePay, call Rebilly.createToken.

  • If the collected form data is valid, you will receive a successful result with a new payment token.
  • If the collected form data is not valid, you will receive an error explaining why.
Copy
Copied
// create a token from the fields within a form
try {
    const paymentToken = await Rebilly.createToken(form);
    // Use this paymentToken in your subsequent Rebilly API calls to complete your checkout process
    console.log(paymentToken); 
} catch (error) {
    // Inspect this error to understand why the token creation failed
    console.log('❌ Create token error:', error);
}

6. Use the token

Use the generated token to complete the integration.

Interactive example

This is an interactive example of a basic checkout form which uses FramePay to tokenize payment cards. It is the result of the previous steps. (Click here to open it in a new window where you will be able to check console.log messages):