Deposit form integration ExperimentalThis feature is experimental and may change.

This guide describes how to integrate an embedded deposit form into your website using the Rebilly Instruments JavaScript library, Rebilly JS SDK, and Express JS.

In this guide, you configure the deposit form to retrieve a customer JWT from a backend endpoint and use that JWT to authenticate the customer in the frontend.

Use deposit forms to allow customers to deposit funds into their accounts.

Prerequisites

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

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: Set up the server. If you do not, create a customer and get your IDs and API key in Set up your environment.

Step 1: Set up the server

Set up an Express node app to authenticate the client.

Declare dependencies

  1. Install the required dependencies in your project directory:

    npm install express rebilly-js-sdk body-parser --save
  2. Declare Express and the Rebilly SDK as dependencies.

Configure the server

Configure an Express.js web server to serve static files and parse JSON requests.

Provide credentials

Provide your secret key, website ID, and organization ID. For more information, see Prerequisites.

Initialize Rebilly JS SDK

Set up the Rebilly JS SDK, and provide sandbox mode and API key.

Define route for GET requests

Define a route for handling HTTP GET requests to the /deposit endpoint. For more information, see Express example.

Step 2: Configure the endpoint

This step describes how to define a basic endpoint for customer authentication.

Define route for POST requests

Define a route for handling HTTP POST requests to the /deposit-request endpoint. You can use any endpoint name. In this example, it is called deposit-request.

Rebilly passwordless login

In the request body, provide a customerId.

Provide that value along with mode: "passwordless" to rebilly.customerAuthentication.login.

Rebilly exchange token

Use the token provided by the passwordless login and exchange it for a JWT that will be used by Rebilly Instruments within the client.

ACL scope data

In the scope object, provide your organization ID.

For more information, see Prerequisites

ACL permissions data

In the permissions array, provide operation IDs for all actions that will be used in the Rebilly Instruments client.

ACL customClaims data

In the customClaims object, provide your website ID.

For more information, see Prerequisites

Create a deposit request

Create an asynchronous function that creates a deposit request and provides the required data.

Set deposit request response

Update the response object values.

Set endpoint response

Respond with the JWT token that is provided by the token exchange.

Listen for requests

Start an Express server on port 3000, listen for host and port information from the server, and log messages to the console.

Step 3: Set up the client

This step describes how to set up the client using a Content Delivery Network (CDN).

For this guide, deposit.html and deposit.js must be placed in a directory named client in the root folder of the project.

Install the library

Include the Rebilly Instruments library using a CDN:

https://cdn.rebilly.com/instruments/@latest/core.js

Specify mounting controls

The default mounting points are: rebilly-instruments and rebilly-instruments-summary.

To provide custom mounting points, pass a valid CSS class or HTML element to the RebillyInstrument.mount() function as a parameter.

Step 4: Configure the library

Gather values

Gather the customerId from URLSearchParams of the page hosting. Provide this value to the server endpoint to exchange it for a customer JWT.

For demonstration purposes, this tutorial uses a hardcoded customerId value in deposit.js. Use the customer ID value you created in the Prerequisites.

In a production environment, you must obtain the customerId value from the URLSearchParams of the hosting page.

Mount

Initialize the library and configure the experience. This method returns a Promise and accepts a single configuration object.

For more information, see RebillyInstrument.mount().

Provide deposit data

Provide the apiMode, depositRequestId, and the JWT token.

For more information, see Provide purchase data to Rebilly Instruments.

Step 5: Optional: Include listeners

Use the instrument-ready and purchase-completed to connect to the lifecycle of the library.

instrument-ready

Indicates when an instrument token is created, and provides access to the instrument response.

For more information, see RebillyInstruments.on('instrument-ready').

purchase-completed

Indicates when a purchase is completed, and provides access to the transaction response.

For more information, see RebillyInstruments.on('purchase-completed').

Step 6: View the form in your browser

Run server.js. When the server is running, open a browser and navigate to http://localhost:3000/deposit.

For more information, see Prerequisites.

node server.js
Preview

This is an interactive example of a deposit form that uses the Rebilly Instruments library. To complete the payment flow, enter any 3-digits for the CVC number. For more test cards, see Test payment cards, IBANs, and ACH details

const express = require("express");
const bodyParser = require("body-parser");
const RebillyAPI = require("rebilly-js-sdk").default;

const app = express();
const port = 3000;
app.use(express.static("client"));
app.use(express.json());
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

const REBILLY_API_SECRET_KEY = "REBILLY_API_SECRET_KEY";
const REBILLY_WEBSITE_ID = "REBILLY_WEBSITE_ID";
const REBILLY_ORGANIZATION_ID = "REBILLY_ORGANIZATION_ID";

const rebilly = RebillyAPI({
    sandbox: true,
    organizationId: REBILLY_ORGANIZATION_ID,
    apiKey: REBILLY_API_SECRET_KEY,
});

app.get("/deposit", async (req, res) => {
    res.redirect(301, "/deposit.html");
});

app.post("/deposit-request", async function (req, res) {

    const { customerId } = req.body;
    const response = {};
    const data = {
        mode: "passwordless",
        customerId,
    };
    const { fields: login } = await rebilly.customerAuthentication.login({
        data,
    });

    const { fields: exchangeToken } = await rebilly.customerAuthentication.exchangeToken({
        token: login.token,
        data: {
            acl: [
                {
                    scope: {
                        organizationId: [REBILLY_ORGANIZATION_ID],
                    },
                    permissions: [
                        "PostToken",
                        "PostDigitalWalletValidation",
                        "StorefrontGetAccount",
                        "StorefrontPatchAccount",
                        "StorefrontPostPayment",
                        "StorefrontGetTransactionCollection",
                        "StorefrontGetTransaction",
                        "StorefrontGetPaymentInstrumentCollection",
                        "StorefrontPostPaymentInstrument",
                        "StorefrontGetPaymentInstrument",
                        "StorefrontPatchPaymentInstrument",
                        "StorefrontPostPaymentInstrumentDeactivation",
                        "StorefrontGetWebsite",
                        "StorefrontGetInvoiceCollection",
                        "StorefrontGetInvoice",
                        "StorefrontGetProductCollection",
                        "StorefrontGetProduct",
                        "StorefrontPostReadyToPay",
                        "StorefrontGetPaymentInstrumentSetup",
                        "StorefrontPostPaymentInstrumentSetup",
                        "StorefrontGetDepositRequest",
                        "StorefrontGetDepositStrategy",
                        "StorefrontPostDeposit",
                    ],
                },
            ],
            customClaims: {
                websiteId: REBILLY_WEBSITE_ID,
            },
        },
    });

    const requestDepositData = {
        websiteId: REBILLY_WEBSITE_ID,
        customerId,
        currency: "USD",
        amounts: [50, 100],
    };

    const { fields: depositFields } = await rebilly.depositRequests.create({
        data: requestDepositData,
    });

    response.token = exchangeToken.token;
    response.depositRequestId = depositFields.id;

    res.send(response);
});

app.listen(port, () => {
    console.log(`Sandbox listening on port ${port}`);
});