Payout form integration

This guide describes how to:

Integrate a payout form into your website using the Rebilly Instruments JavaScript library.
Configure the payout form to retrieve a customer JWT from a backend endpoint.
Use the JWT to authenticate the customer in the frontend.

Use payout forms to allow customers to request payouts. In the payout form, customers must select or add a preferred payment instrument on which to receive the payout. Payout requests must be approved and allocated before the approved amount is transferred to the customer's payment instrument.

To interact with an example payout form, see the Preview tab in the Set up a payout form section.

To complete this tutorial, an active payment gateway with payout settings is required.

If you are testing in the sandbox environment, a test payment gateway called TestProcessor is already active but not configured for payouts. To configure it, see Activate the ready to payout instruction.

For information on payment gateway settings, see Set up a payment gateway.

Payment methods that are displayed in the payout form are based on the gateway configuration. For more information, see Set up a payment gateway.

Prerequisites

Complete this section to gather your website ID, organization ID, and secret API key. These details are required to complete this guide using your Rebilly sandbox environment. If you have already created these resources, skip this step and continue to Set up a payout form.

Expand to complete

Activate the ready to payout instruction

To complete this guide, you must have an active payment gateway with payout settings configured. This process describes how to activate the ready to payout instruction on the TestProcessor payment gateway in the sandbox environment.

The TestProcessor payment gateway is automatically configured in the sandbox environment when you sign up to Rebilly. For more information on payment gateway settings, see Set up a payment gateway.

Log in or sign up to Rebilly.
In the left navigation bar, press Settings .
In the Configuration section, press Gateway accounts.
In the ID column, press TestProcessor.
In the right of the page, press Edit gateway account.
Scroll down to the Ready to payout instruction section, and turn on the Activate this gateway for payouts toggle.
Select one of the following options:
- Covered payout: Use this gateway if it previously processed a payment for the same, or a greater, amount.
- Approved payments: Use this gateway if it previously processed a payment for the same amount. The customer must have a previously approved transaction, in the same currency, on this gateway.
- All payments: Use this gateway for any amount.
Scroll to the bottom of the page and press Save gateway account.

Obtain IDs and secret key

When you first log in to Rebilly, you create an organization as part of the setup process. A default website is created when a new organization is created. For more information, see Organizations and websites.

Log in or sign up to Rebilly.
Obtain your organization ID and website ID:
1. In the left navigation bar, press Settings .
2. In the Management section, press My organization & websites.
3. In the Organization details section, note the ID value.
4. In the Website section, note the ID value. For more information, see Organizations and websites.
Obtain your secret API key:
1. In the left navigation bar, press Automations .
2. In the Development section, press API keys.
3. Optionally, if you have not created a secret key:
  1. In top right of the screen, press Create API key.
  2. In the API key type section, select Secret.
  3. Optionally, in the Organizations dropdown, select the organizations that can use the API key.
  4. Optionally, in the Allowed IPs field, enter the IP addresses that are permitted to use the API key.
  5. Press Save API key.
  6. Go to the API keys page.
4. Select a secret key and copy the Key value.

Set up a payout form

This section describes how to set up the server and client side implementation for a payout form.

Set up the server

Set up an Express node app for authenticating the client.

Install and initialize dependencies

Import dependencies, this may change from implementation to implementation. This example is for an app that uses Node.js and Express.

server.js

Provide credentials

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

server.js

Initialize Rebilly JS SDK

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

server.js

Define route for GET requests

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

server.js

Configure the authentication

This step describes the basic endpoint used for customer authentication.

Define route for POST requests

Define route for handling HTTP POST requests to the /authenticate endpoint. This request is used to authenticate the customer. You can use any endpoint. In this example it is called authenticate.

server.js

Rebilly passwordless login

In the request body, provide a customerId. Then, provide that value along with mode: "passwordless" to rebilly.customerAuthentication.login.

server.js

Rebilly exchange token

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

server.js

ACL scope data

In the scope object, provide your organization ID.

For more information, see Prerequisites.

server.js

ACL permissions data

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

server.js

ACL customClaims data

In the customClaims object, provide your website ID.

For more information, see Prerequisites.

server.js

Send endpoint response

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

server.js

Configure the payout request

This step describes the basic endpoint that is used for payout requests.

Obtain data

Set up a route handler for POST requests to the /payout-request endpoint. You can use any endpoint. In this example it is called payout-request.

server.js

Parse values from request body

This endpoint expects the customerId, amount, and currency to be specified in the request body.

server.js

Create the Rebilly payout request and send endpoint response

Use the values from the request body and make an API call to Rebilly.payoutRequests.create, and provide your website ID.

For more information, see Prerequisites.

server.js

Listen for requests

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

server.js

Set up the client

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

Install the library

Include the Rebilly Instruments library using a CDN:

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

example.html

Include payout request HTML

This example uses hard-coded values for the payout request. In a real-life scenario, the amount and currency would be determined dynamically.

Note: This section is displayed by default, and hidden when a selection is made and Rebilly Instruments is mounted.

example.html

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 a HTML element to the RebillyInstrument.mount() function, as a parameter.

example.html

Configure the library

This step describes the basic set up for mounting.

Gather values and authenticate

Gather the customerId from the URLSearchParams of the hosting page and authenticate the user.

For demonstration purposes, this example uses a hardcoded customerId value. In a production environment, you must obtain the customerId value from the URLSearchParams of the hosting page.

client.js

Authenticate the client

Define route for handling HTTP POST requests to the /authenticate endpoint. This request is used to authenticate the customer. Provide the customerId value to the server endpoint. You can use any endpoint. In this example it is called authenticate.

client.js

Connect form buttons

Add button listeners for the payout request form.

client.js

Payout request

Create a payout request

Use the created API endpoint to create the payout request, and pass the customerId, amount, and currency values.

client.js

Parse the response body

Parse the response body as JSON and extract the payoutRequest object.

client.js

Switch UI

Change from the payout request UI to the Rebilly Instruments UI.

client.js

Configure the library

Rebilly data

Mount the Rebilly Instruments JavaScript library and provide apiMode and the JWT. This configures the library to communicate with Rebilly.

client.js

Payout data

Provide details of the payout data.

For more information, see RebillyInstruments.mount(payout: {}).

client.js

Basic set up complete

You now have a basic payout form integration.

To learn more, see:

Copy to clipboard

server.js
example.html
client.js

1const express = require("express");
2const bodyParser = require("body-parser");
3const RebillyAPI = require("rebilly-js-sdk").default;
4const app = express();
5const port = 3000;
6
7app.use(express.static("client"));
8app.use(express.json());
9app.use(bodyParser.json());
10app.use(bodyParser.urlencoded({ extended: true }));
11
12const REBILLY_API_SECRET_KEY = "REBILLY_API_SECRET_KEY";
13const REBILLY_WEBSITE_ID = "REBILLY_WEBSITE_ID";
14const REBILLY_ORGANIZATION_ID = "REBILLY_ORGANIZATION_ID";
15
16const rebilly = RebillyAPI({
17    sandbox: true,
18    apiKey: REBILLY_API_SECRET_KEY,
19});
20
21app.get("/payout", async (req, res) => {
22    res.redirect(301, "/payout.html");
23});
24
25app.post("/authenticate", async function (req, res) {
26    const { customerId } = req.body;
27    const data = {
28        mode: "passwordless",
29        customerId,
30    };
31    const { fields: login } = await rebilly.customerAuthentication.login({
32        data,
33    });
34    const { fields: exchangeToken } =
35        await rebilly.customerAuthentication.exchangeToken({
36            token: login.token,
37            data: {
38                acl: [
39                    {
40                        scope: {
41                            organizationId: [REBILLY_ORGANIZATION_ID],
42                        },
43                        permissions: [
44                            "PostToken",
45                            "StorefrontGetPaymentInstrumentCollection",
46                            "StorefrontPostPaymentInstrument",
47                            "StorefrontGetPaymentInstrument",
48                            "StorefrontPatchPaymentInstrument",
49                            "StorefrontGetAccount",
50                            "StorefrontGetWebsite",
51                            "StorefrontPostReadyToPay",
52                            "StorefrontGetPayoutRequestCollection",
53                            "StorefrontGetPayoutRequest",
54                            "StorefrontPatchPayoutRequest",
55                            "StorefrontPostReadyToPayout",
56                        ],
57                    },
58                ],
59                customClaims: {
60                    websiteId: REBILLY_WEBSITE_ID,
61                },
62            },
63        });
64    res.send({ token: exchangeToken.token });
65});
66
67app.post("/payout-request", async function (req, res) {
68    const { customerId, amount, currency } = req.body;
69    const { fields: payoutRequest } = await rebilly.payoutRequests.create({
70        data: {
71        websiteId: REBILLY_WEBSITE_ID,
72        customerId,
73        currency,
74        amount,
75        },
76    });
77    res.send({ payoutRequest });
78});
79
80app.listen(port, () => {
81    console.log(`Sandbox listening on port ${port}`);
82});

1<!doctype html>
2<html lang="en">
3    <head>
4        <title>Payout form</title>
5        <script src="https://cdn.rebilly.com/instruments/@latest/core.js" type="text/javascript"></script>
6        <script src="./client.js" defer></script>
7    </head>
8    <body>
9        <div id="app">
10            <section id="payout-request">
11                <button class="button-5">Request $4.99</button>
12                <button class="button-10">Request $9.99</button>
13            </section>
14            <section id="rebilly-instruments" style="display: none">
15                <div class="rebilly-instruments-summary"></div>
16                <div class="rebilly-instruments"></div>
17            </section>
18        </div>
19    </body>
20</html>

1const customerId = "cus_01HMW4HF2QMJZ3EJKEQ7T04TFQ";
2let authorization = null;
3
4(async () => {
5    const response = await fetch("/authenticate", {
6        method: "POST",
7        headers: {
8            "Content-Type": "application/json",
9            Accept: "application/json",
10        },
11        body: JSON.stringify({ customerId }),
12    });
13    authorization = await response.json();
14    document
15        .querySelector(".button-5")
16        .addEventListener("click", () => requestPayout({ amount: 4.99 }));
17    document
18        .querySelector(".button-10")
19        .addEventListener("click", () => requestPayout({ amount: 9.99 }));
20})();
21
22async function requestPayout({ amount }) {
23    const response = await fetch("/payout-request", {
24        method: "POST",
25        headers: {
26            "Content-Type": "application/json",
27            Accept: "application/json",
28        },
29        body: JSON.stringify({
30            customerId,
31            amount,
32            currency: "USD",
33        }),
34    });
35    const { payoutRequest } = await response.json();
36
37    document.getElementById("payout-request").style.display = "none";
38    document.getElementById("rebilly-instruments").style.display = "block";
39
40    RebillyInstruments.mount({
41        apiMode: "sandbox",
42        jwt: authorization.token,
43        payout: {
44            payoutRequestId: payoutRequest.id,
45        },
46    });
47}

Our Solutions

Products

Features

Payout form integration

Prerequisites

Activate the ready to payout instruction

Obtain IDs and secret key

Set up a payout form

Set up the server

Install and initialize dependencies

Provide credentials

Initialize Rebilly JS SDK

Define route for GET requests

Configure the authentication

Define route for POST requests

Rebilly passwordless login

Rebilly exchange token

ACL scope data

ACL permissions data

ACL customClaims data

Send endpoint response

Configure the payout request

Obtain data

Parse values from request body

Create the Rebilly payout request and send endpoint response

Listen for requests

Set up the client

Install the library

Include payout request HTML

Specify mounting controls

Configure the library

Gather values and authenticate

Authenticate the client

Connect form buttons

Payout request

Create a payout request

Parse the response body

Switch UI

Configure the library

Rebilly data

Payout data

Basic set up complete

Related topics

Was this helpful?