End-to-end FramePay integration

This guide describes how to add the FramePay library to a checkout page and use it to tokenize payment card information. It also describes how to set up a simple server using the Rebilly JS SDK and use the token to complete a purchase transaction.

This guide uses Node.js (Express) as the server-side language for the implementation. The code described in this topic is available in the Rebilly framepay-integrated-example GitHub repository.

Prerequisites

To complete this guide, you must have an organization ID, a website ID, a secret API key, and a publishable API key.

You must also have a payment gateway configured in your Rebilly account. For sandbox testing, the TestProcessor gateway is pre-configured.

If you already have your IDs and API keys, continue to Step 1: Install the Rebilly JS SDK. If you do not, see Set up your environment.

Step 1: Install the Rebilly JS SDK

Import the Rebilly JS SDK

  1. Install the required dependencies in your project directory:

    npm install rebilly-js-sdk@^46.4.0 --save

    For more information, see JS SDK quickstart guide.

  2. Import the Rebilly JS SDK into your code.

Initialize the Rebilly JS SDK

Initialize the Rebilly JS SDK with your secret key and organization ID.

For more information, see Prerequisites.

Step 2: Create a transaction

Add an endpoint

Add an endpoint on your server that creates a transaction. This endpoint must receive the FramePay-generated token as the payload.

Create a customer

Create a customer using the billing address and the payment token.

Create a sale transaction

Create a sale transaction and use the customerId.

Handle the response

Handle the response from the POST /create-transaction endpoint.

Start the Express server

Start the Express.js server and listen for incoming requests.

Step 3: Create a checkout page

Include the FramePay stylesheet

Add the default styles for the FramePay library elements on the page.

Include the FramePay script

Expose the FramePay library in the global JS scope as Framepay.

Add CSS for your checkout form

Add CSS styles for your checkout form.

Create your checkout form

Create a checkout form on your page.

Define the data-rebilly attributes on your input fields. This instructs the FramePay library to automatically gather data from your checkout form.

Include HTML mounting points

Specify an empty placeholder div with a unique ID.

This is where the FramePay library will render the card field by injecting an iframe.

Step 4: Set up client-side script

Initialize FramePay

Initialize the FramePay library with a configuration object.

Provide your publishable API key to connect with the Rebilly API.

For more information, see FramePay configuration reference and Prerequisites.

Optional: Style the card input

Customize the card payment field to match the style of your checkout form.

To customize, add the style property in the configuration object.

For all available properties, see Style reference.

Get DOM elements

Create references to the form elements that will be used in the payment flow.

Mount the card field

Mount the payment card field. For more information, see:

Handle the form submit event

Listen for the form submit event to determine when the user is ready to make the payment.

Create a payment token

To send the form data to the FramePay library, call Framepay.createToken().

  • If the collected form data is valid, the library returns a successful result with a new payment token.
  • If the collected form data is not valid, the library returns an error explaining why.

For more information, see Framepay.createToken(form).

Send token to server

When the FramePay library returns the payment token, you can complete the purchase by making a request to the POST /create-transaction endpoint.

Pass the token as part of the request payload, together with other properties.

Handle the API response

If no error occurs, inform your customer that the payment is successful. This example redirects the customer to a thank you (success) page, or to an approvalUrl if it exists.

Handle errors and button state

Add error handling for issues that may occur during payment processing, and manage the submit button state to prevent multiple submissions.

Preview

This is an interactive example of an end-to-end FramePay integration, including a sample Express server file.

Complete the payment flow using this test card number: 4111 1111 1111 1111. Use any future expiration date and any 3 digits for the CVC number. For more test cards, see Test payment cards, IBANs, and ACH details.

const { Rebilly } = require("rebilly-js-sdk@^46.4.0");

const api = new Rebilly({
    secretKey: "sk_secretKey",
    organizationId: "org_organizationId",
});

app.post("/create-transaction", async (req, res) => {
    try {
        const { paymentToken, billingAddress: primaryAddress, currency, amount } = req.body;

        const { fields: customer } = await api.customers.create({
            data: {
                paymentToken,
                primaryAddress,
            },
        });

        const { fields: transaction } = await api.transactions.create({
            data: {
                type: "sale",
                websiteId: WEBSITE_ID,
                customerId: customer.id,
                currency,
                amount,
            },
        });

        res.status(201).send(transaction);
    } catch (error) {
        const message = err.details ?? "Internal Server Error";
        const code = err.status ?? 500;
        res.status(500).send({ code, message });
    }
});

app.listen(port, () => {
    console.log(`App listening at port: ${port}`);
});