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

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

In this guide, you configure the 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 reverse withdrawal form to display a compact reverse withdrawal option when a customer has pending payout requests. When a customer completes a reverse withdrawal, pending payout requests are canceled and funds are returned to the customer's account balance. A payout request is a customer request to withdraw funds.

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 your website uses a Content Security Policy (CSP), configure it before you embed the reverse 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, view this guide to Create a customer and get your IDs and API key in Set up your environment.

The reverse withdrawal option is available only when the customer has a pending payout total that is greater than zero. Provide pendingPayoutTotal when you Create a cashier, or pass balances.pendingPayoutTotal to RebillyCashier.renderReverseWithdraw().

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.

Provide pending payout total

Provide the total value of all payout requests that are currently in a pending state. This value is the maximum possible reverse withdrawal amount.

Step 2: Set up the form

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

For this guide, index.html and reverse-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 reverse withdrawal form.

For more information, see Customize.

Add a container element

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

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

Render the reverse 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 reverse withdrawal form on the page.

Handle reverse withdrawal completion (optional)

To handle reverse withdrawal completion, use RebillyCashier.on() to listen for the reverse-withdrawal-completed event. The reverse withdrawal form does not support completeAction.

Customize the empty state

When the customer has no pending payout requests, the reverse withdrawal form displays a default empty state message. To customize this message, add a child element with the no-pending-withdrawal slot to the mount element before you call RebillyCashier.renderReverseWithdraw():

<div id="reverse-withdraw">
  <section slot="no-pending-withdrawal">
    <h3>No pending withdrawals</h3>
    <p>You do not have any pending payout requests.</p>
  </section>
</div>

Step 3: View the reverse withdrawal form

This section describes how to view the reverse 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 reverse 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 }}",
                pendingPayoutTotal: 100.0,
            },
        });

        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"));