Deposit form integration
This guide describes how to:
- Integrate a deposit form into your website using the Rebilly Instruments JavaScript library.
- Configure the deposit form to retrieve a customer JWT from a backend endpoint.
- Use the JWT to authenticate the customer in the frontend.
Use deposit forms to allow customers to deposit funds into their accounts. To interact with an example deposit form, see the Preview tab in the Set up a deposit form section.
To complete this tutorial, an active gateway is required. If you are testing in the sandbox environment, a test payment gateway called TestProcessor
is already configured. For more information, see Set up a payment gateway.
Payment methods that are displayed in the deposit 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, and also to install dependencies locally. These details and dependencies are required to complete this guide using your Rebilly sandbox environment.
Expand to complete
1. Obtain IDs and publishable API 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:
- In the left navigation bar, press Settings .
- In the Management section, press My organization & websites.
- In the Organization details section, note the ID value.
- In the Website section, note the ID value.
- Obtain your publishable API key:
- In the left navigation bar, press Automations .
- In the Development section, press API keys.
- Optionally, if you have not created a publishable key:
- In top right of the screen, press Create API key.
- In the API key type section, select Publishable.
- Optionally, in the Organizations dropdown, select the organizations that can use the API key.
- Optionally, in the Allowed IPs field, enter the IP addresses that are permitted to use the API key.
- Press Save API key.
- Go to the API keys page.
- Select a publishable key and copy the Key value.
2. Upsert a customer
For the purposes of this tutorial, you must create a customer in your system. A deposit request must be associated with a customer.
This API operation prevents duplicate customers. If the customer already has an identifier within your system, that customer is updated. If the customer does not have an identifier, a new customer is created.
For detailed information about this API operation, see Upsert a customer.
Execute the 'Upsert a customer' operation
This example creates a customer with a specified ID.
How to use this component
- Enter your organization ID:
- Beneath the Environment field, press
{{server}}
. - Beneath the URL, press Show nested variables, then press Edit.
- In the Value field, enter your organization ID and press Save.
- Beneath the Environment field, press
- Enter your secret API key:
- Press Security.
- In the API key field, press
{{SecretApiKey}}
, then press Set value. - In the Value field, enter your secret Rebilly sandbox API key and press Save. For more information, see Prerequisites.
- Enter a customer ID:
- In the URL field beneath the Environment field, press
{{id}}
. - Press Set value.
- In the Value field, enter a customer ID.
Example:cus_01HDP7FFX2PGDVH1995EA4QY95
.
- In the URL field beneath the Environment field, press
- Enter your website ID:
- Press Body.
- In the
websiteId
, enter your website ID. - Optionally, change the customer details.
- Press Send.
Take note of theid
value from this response. This value is used as thecustomerId
later in this tutorial.
3. Set up your environment
This tutorial uses Express JS, Rebilly JS SDK, and body-parser.
- Ensure that Node.js and npm are installed. For more information, see Node.js and npm.
- Install the required dependencies in your project directory:
npm install express rebilly-js-sdk body-parser --save
Set up a deposit form
This section describes how to configure the server and client side implementation for a deposit form.
To complete this section, you must have your website ID, organization ID, secret API key, customer ID, and have the required dependencies installed. For more information, see Prerequisites.
Set up the server
Set up an Express node app to authenticate the client.
Install and initialize dependencies
Dependencies may change from implementation to implementation. This example is for an app that uses Node.js and Express.
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.
Configure the endpoint
This step describes the basic endpoint used for customer authentication.
Define route for POST requests
Define route for handling HTTP POST requests to the /deposit-request
endpoint. You can use any endpoint. 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 8080, listen for host and port information from the server, and log a messages to the console.
Set up the client
This step describes how to set up the client using a using 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
- 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.
Configure the library
This step describes the basic set up for mounting.
Gather values
Gather the customerId
from URLSearchParams
of the page hosting. Provide this value to the server endpoint to exchange for 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 prequisites.
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.
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').
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
Basic set up complete
You now have a basic deposit form integration. To learn more, see:
- server.js
- deposit.html
- deposit.js
1const express = require("express");2const bodyParser = require("body-parser");3const RebillyAPI = require("rebilly-js-sdk").default;4const app = express();5const port = 3000;67app.use(express.static("client"));8app.use(express.json());9app.use(bodyParser.json());10app.use(bodyParser.urlencoded({ extended: true }));1112const REBILLY_API_SECRET_KEY = "REBILLY_API_SECRET_KEY";13const REBILLY_WEBSITE_ID = "REBILLY_WEBSITE_ID";14const REBILLY_ORGANIZATION_ID = "REBILLY_ORGANIZATION_ID";1516const rebilly = RebillyAPI({17 sandbox: true,18 apiKey: REBILLY_API_SECRET_KEY,19});2021app.get("/deposit", async (req, res) => {22 res.redirect(301, "/deposit.html");23});2425app.post("/deposit-request", async function (req, res) {26 const { customerId } = req.body;27 const response = {};28 const data = {29 mode: "passwordless",30 customerId,31 };32 const { fields: login } = await rebilly.customerAuthentication.login({33 data,34 });35 const { fields: exchangeToken } =36 await rebilly.customerAuthentication.exchangeToken({37 token: login.token,38 data: {39 acl: [40 {41 scope: {42 organizationId: [REBILLY_ORGANIZATION_ID],43 },44 permissions: [45 "PostToken",46 "PostDigitalWalletValidation",47 "StorefrontGetAccount",48 "StorefrontPatchAccount",49 "StorefrontPostPayment",50 "StorefrontGetTransactionCollection",51 "StorefrontGetTransaction",52 "StorefrontGetPaymentInstrumentCollection",53 "StorefrontPostPaymentInstrument",54 "StorefrontGetPaymentInstrument",55 "StorefrontPatchPaymentInstrument",56 "StorefrontPostPaymentInstrumentDeactivation",57 "StorefrontGetWebsite",58 "StorefrontGetInvoiceCollection",59 "StorefrontGetInvoice",60 "StorefrontGetProductCollection",61 "StorefrontGetProduct",62 "StorefrontPostReadyToPay",63 "StorefrontGetPaymentInstrumentSetup",64 "StorefrontPostPaymentInstrumentSetup",65 "StorefrontGetDepositRequest",66 "StorefrontGetDepositStrategy",67 "StorefrontPostDeposit",68 ],69 },70 ],71 customClaims: {72 websiteId: REBILLY_WEBSITE_ID,73 },74 },75 });7677 const requestDepositData = {78 websiteId: REBILLY_WEBSITE_ID,79 customerId,80 currency: "USD",81 amounts: [50, 100],82 };8384 const { fields: depositFields } = await rebilly.depositRequests.create({85 data: requestDepositData,86 });8788 response.token = exchangeToken.token;89 response.depositRequestId = depositFields.id;9091 res.send(response);92});9394app.listen(port, () => {95 console.log(`Sandbox listening on port ${port}`);96});
1<!doctype html>2<html lang="en">3 <head>4 <title>Deposit form</title>5 <script src="https://cdn.rebilly.com/instruments/@latest/core.js" type="text/javascript"></script>6 <script src="./deposit.js" defer></script>7 </head>8 <body>9 <div id="app">10 <div class="rebilly-instruments-summary"></div>11 <div class="rebilly-instruments"></div>12 </div>13 </body>14</html>
1const customerId = "cus_01HMW4HF2QMJZ3EJKEQ7T04TFQ";23(async () => {4 const response = await fetch("/deposit-request", {5 method: "POST",6 headers: {7 "Content-Type": "application/json",8 Accept: "application/json",9 },10 body: JSON.stringify({ customerId }),11 });12 const { token, depositRequestId } = await response.json();1314 // Mount Rebilly Instruments15 RebillyInstruments.mount({16 apiMode: "sandbox",17 deposit: {18 depositRequestId,19 },20 jwt: token,21 });22 // Optional23 RebillyInstruments.on("instrument-ready", (instrument) => {24 console.info("instrument-ready", instrument);25 });2627 RebillyInstruments.on("purchase-completed", (purchase) => {28 console.info("purchase-completed", purchase);29 });30})();