This guide describes how to integrate an embedded payout form into your website using the Rebilly Instruments JavaScript library, Rebilly JS SDK, and Express JS.
This guide describes how to configure the payout form to retrieve a customer JWT from a backend endpoint and use that 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.
Prerequisites
To complete this guide, you must have a website ID, an organization ID, a secret API key, and the ready-to-payout instruction activated on your payment gateway account.
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 and the ready to payout instruction is activated on your payment gateway account, continue to Step 1: Set up the server. If you do not, activate the ready to payout instruction and get your IDs and API key in Set up your environment.
Set up an Express node app to authenticate the client.
Declare dependencies
Install the required dependencies in your project directory:
npm install express rebilly-js-sdk body-parser --saveDeclare 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 /payout endpoint. For more information, see Express example.
This step describes the basic endpoint used for customer authentication.
Define route for POST requests
Define a route for handling HTTP POST requests to the /payout-request endpoint. For more information, see Express example.
Rebilly passwordless login
In the request body, provide a customerId. Then, 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 the Rebilly Instruments JavaScript library 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.
Send endpoint response
Respond with the JWT token that is provided by the token exchange.
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.
Parse values from request body
This endpoint expects the customerId, amount, and currency to be specified in the request body.
Create payout request
Create the Rebilly payout request using 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.
Listen for requests
Start an Express server on port 8080, listen for host and port information from the server, and log messages to the console.
This step describes how to set up the client using a Content Delivery Network (CDN).
Install the library
Include the Rebilly Instruments library using a CDN:
https://cdn.rebilly.com/instruments/@latest/core.jsInclude 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 the Rebilly Instruments library is mounted.
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 an HTML element to the RebillyInstrument.mount() function as a parameter.
This step describes the basic setup 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.
Authenticate the client
Define a route for handling HTTP POST requests to the /authenticate endpoint and provide the customerId value to the server endpoint.
Connect form buttons
Add button listeners for the payout request form.
This step describes how to create a payout request.
Create a payout request
Send a POST request to the /payout-request endpoint with the customerId, amount, and currency values.
Parse the response body
Parse the response body as JSON and extract the payoutRequest object.
Switch UI
Change from the payout request UI to the Rebilly Instruments UI.
This step describes the basic setup for mounting.
Mount the Rebilly Instruments JavaScript library
Mount the Rebilly Instruments JavaScript library and provide apiMode and the JWT. This configures the library to communicate with Rebilly.
Provide payout data
Provide details of the payout data. For more information, see RebillyInstruments.mount(payout: {}).
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 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("/payout", async (req, res) => {
res.redirect(301, "/payout.html");
});
app.post("/authenticate", async function (req, res) {
const { customerId } = req.body;
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",
"StorefrontGetPaymentInstrumentCollection",
"StorefrontPostPaymentInstrument",
"StorefrontGetPaymentInstrument",
"StorefrontPatchPaymentInstrument",
"StorefrontGetAccount",
"StorefrontGetWebsite",
"StorefrontPostReadyToPay",
"StorefrontGetPayoutRequestCollection",
"StorefrontGetPayoutRequest",
"StorefrontPatchPayoutRequest",
"StorefrontPostReadyToPayout",
],
},
],
customClaims: {
websiteId: REBILLY_WEBSITE_ID,
},
},
});
res.send({ token: exchangeToken.token });
});
app.post("/payout-request", async function (req, res) {
const { customerId, amount, currency } = req.body;
const { fields: payoutRequest } = await rebilly.payoutRequests.create({
data: {
websiteId: REBILLY_WEBSITE_ID,
customerId,
currency,
amount,
},
});
res.send({ payoutRequest });
});
app.listen(port, () => {
console.log(`Sandbox listening on port ${port}`);
});