Integrate a withdrawal form ExperimentalThis feature is experimental and may change.

This guide describes how to integrate and embed a customizable, white-label withdrawal form into your website using the Cashier JavaScript library, Rebilly JS SDK, and Express JS.

In this guide, you configure the withdrawal form to retrieve a cashier token from a backend endpoint and use that token to mount the Cashier JavaScript library in the frontend.

Use the withdrawal form to allow customers to request withdrawals from their account balance. When a customer submits a withdrawal, a payout request is created. A payout request is a customer request to withdraw funds. In the withdrawal form, customers select a withdrawal amount, choose or add a payment instrument, and confirm the withdrawal. Payouts must be approved and allocated before the approved amount is transferred to the payment instrument. For more information, see Payout requests.

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 to process payout requests. For sandbox testing, the TestProcessor gateway is pre-configured.

If your website uses a Content Security Policy (CSP), configure it before you embed the withdrawal form. For more information, see Configure content security policy.

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.

To process payout requests, configure at least one gateway for payouts and configure payout methods to display in the form. For more information, see Configure a gateway to manage payout requests and Configure payout methods displayed in payout forms.

Step 1: Set up the server

This section describes how to set up your server-side code. This guide uses an Express node app to authenticate the client.

Install and initialize dependencies

  1. Install the required dependencies in your project directory:

    npm install express rebilly-js-sdk --save

  2. Initialize Express and the Rebilly SDK.

Provide credentials

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

Store your secret key in a secrets manager, not in your code.

Initialize Rebilly JS SDK

Set up the Rebilly JS SDK and provide your secret API key. Set sandbox to true to test in the sandbox environment.

Define route for POST requests

Define a route for handling HTTP POST requests to the /create-cashier endpoint.

For more information, see the Create a cashier API operation and this Express example.

Provide a customer ID

Provide the ID of a customer.

For more information, see Prerequisites.

Provide currency

Provide the currency of the transaction.

Step 2: Set up the form

This section describes the basic setup for mounting the withdrawal form.

For this guide, index.html and withdraw.js must be placed in a public directory in the root of your project.

Install the library

Include the Cashier JavaScript library using a CDN:

https://cdn.rebilly.com/cashier/@latest/main.js

Add custom styling (optional)

Optionally, use Cashier library CSS variables or classes to customize the appearance of the withdrawal form.

For more information, see Customize.

Add a container element

Define an empty container element to hold the withdrawal form. This element is provided to the Cashier library renderWithdraw method to mount the withdrawal form.

Any HTML element may be used to contain the withdrawal form.

Render the withdrawal form

Send a request to the /create-cashier server endpoint you created in Step 1: Set up a server, and use the returned cashierToken to mount the withdrawal form on the page.

Handle withdrawal form completion (optional)

To handle withdrawal form completion, use RebillyCashier.on() to listen for the withdrawal-completed event.

Handle withdrawal result action (optional)

To run custom logic when the customer presses Continue on the result screen of the withdrawal or reverse withdrawal form, instead of redirecting to a URL, pass a completeAction callback to RebillyCashier.renderWithdraw(). The callback receives a type value of withdrawal or reverse-withdrawal. The withdrawal form displays the reverse withdrawal option when the customer has pending payout requests.

Step 3: View the withdrawal form

This section describes how to view the withdrawal form in a web browser.

Run the example

Run server.js. When the server is running, open a browser and visit http://localhost:8080.

For more information, see Prerequisites.

node server.js
Preview

This is an interactive example of a withdrawal form that uses the Cashier JavaScript library.

import express from "express";
import RebillyAPI from "rebilly-js-sdk";

const app = express();

const API_SECRET_KEY = "SECRET_KEY";
const ORGANIZATION_ID = "ORGANIZATION_ID";
const WEBSITE_ID = "WEBSITE_ID";

const rebilly = RebillyAPI({
    organizationId: ORGANIZATION_ID,
    sandbox: true,
    apiKey: API_SECRET_KEY,
    timeout: 5000,
});

app.use(express.static("public"));

app.post("/create-cashier", async (req, res) => {
    try {
        const response = await rebilly.cashiers.create({
            data: {
                websiteId: WEBSITE_ID,
                customerId: "{{ CUSTOMER_ID }}",
                currency: "{{ CURRENCY }}",
            },
        });

        const cashierToken = response.fields.cashierToken;

        res.send({ cashierToken });
    } catch (error) {
        if (error?.response?.data) {
            console.error(error.response.data);
        } else {
            console.error(error);
        }
        res.status(500).json({ error: "Failed to create cashier token" });
    }
});

app.listen(8080, () => console.log("Running on port 8080"));