Payment form using a JWT
This guide describes how to:
- Integrate a payment form into your website using the Rebilly Instruments JavaScript library
- Configure the payment form to retrieve a customer JWT from a backend endpoint.
- Use the JWT to process payments for both invoices and transactions.
Use payment forms to process payments from your customers. To interact with an example payment form, see the Preview tab in the Set up a payment 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 payment form are based on the gateway configuration. For more information, see Set up a payment gateway.
Prerequisites
Complete this section to create resources and also to gather your website ID, organization ID, and secret API key. These resources and 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 payment form.
Expand to complete
1) Obtain IDs and API keys
This process describes how to obtain your website ID, organization ID, and publishable API key from your Rebilly sandbox.
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.
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.
Obtain your secret API key
- In the left navigation bar, press Automations .
- In the Development section, press API keys.
- Optionally, if you have not created a secret key:
- In top right of the screen, press Create API key.
- In the API key type section, select Secret.
- 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 secret key and copy the Key value.
2) Create a product
This API interaction creates a product in your Rebilly sandbox account. For more information, see Create a product.
To create a product you must have your Rebilly website ID, organization ID, and secret API key. For more information, see Obtain IDs and API keys.
How to use the interactive example
- 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.
- Optionally, to change the product details, press Body.
- Press Send.
Theid
value from this response is used as theproductId
value in the next step.
3) Create a pricing plan
This API interaction creates a pricing plan for a product in your Rebilly sandbox account. For more information, see Create a plan.
To create a pricing plan, you must have a product ID. To create a product, see Create a product.
How to use the interactive example
- 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 the product ID from the Step 2 response.
- Press Body.
- In the
productId
field, enter theid
value from the Step 2 response. - Optionally, change the plan details.
- Press Send.
4) Create a customer
This API interaction creates a customer in your Rebilly sandbox account. For more information, see Create a customer.
How to use the interactive example
- 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.
Theid
value from this response is used as thecustomerId
value in Step 5.
5) Create an order
This API interaction creates an order in your Rebilly sandbox account.
To create an order, you must have a customer ID and a plan ID. For more information, see Create a customer and Create a pricing plan.
How to use the interactive example
- 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 the customer ID, plan ID, and website ID:
- Press Send.
Set up a payment form
This section describes how to create a payment form, integrate it to your website, and how to process payments from an invoice and how to process a transaction.
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 /checkout
endpoint. For more information, see Express example.
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
.
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 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.
You can also provide the invoiceId
or transactionId
in the customClaims
object and omit them in the client when mounting Rebilly Instruments.
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).
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 setup for mounting.
Gather values
Gather the customerId
from URLSearchParams
of the page hosting, and provide this value to the server endpoint to exchange for it for a customer JWT.
For demonstration purposes, this example uses a hardcoded customerId
value in client.js
. 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 RebillyInstruments.mount().
Provide payment data
Select one of the following:
- Process from an invoice:
Provide theinvoiceId
value of an invoice you want to process. To create an order, see step 5 of Prerequisites.invoiceId: 'an-invoice-id', jwt: 'token',
- Process from a transaction:
Provide thetransactionId
value of a transaction you want to process.transactionId: 'a-transaction-id', jwt: 'token',
Provide the apiMode
value as sandbox
or live
based on your environment. Website and organization IDs are obtained from the JWT token. A JWT is required to process a purchase based on invoiceId
or transactionId
.
The following purchase data properties are available:items
, money
, invoiceId
, transactionId
. For more information, see Purchase data examples.
It is also possible to obtain the invoiceId
value from the jwt
value. For more information, see Purchase data examples.
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. 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').
If you are using a local server, use this listener to view the transaction response in the browser console.
Basic set up complete
You now have a basic payment form integration.
To learn more, see:
- server.js
- client.js
- example.html
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('/checkout', async (req, res) => {22 res.redirect(301, '/checkout.html');23});2425app.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 } = await rebilly.customerAuthentication.exchangeToken({35 token: login.token,36 data: {37 acl: [38 {39 scope: {40 organizationId: [REBILLY_ORGANIZATION_ID],41 },42 permissions: ['PostToken', 'PostDigitalWalletValidation', 'StorefrontGetAccount', 'StorefrontPatchAccount', 'StorefrontPostPayment', 'StorefrontGetTransaction', 'StorefrontGetPaymentInstrumentCollection', 'StorefrontPostPaymentInstrument', 'StorefrontGetPaymentInstrument', 'StorefrontPatchPaymentInstrument', 'StorefrontPostPaymentInstrumentDeactivation', 'StorefrontGetWebsite', 'StorefrontGetInvoiceCollection', 'StorefrontGetInvoice', 'StorefrontGetProductCollection', 'StorefrontGetProduct', 'StorefrontPostReadyToPay', 'StorefrontPostPreviewPurchase'],43 },44 ],45 customClaims: {46 websiteId: REBILLY_WEBSITE_ID,47 },48 },49 });50 res.send({ token: exchangeToken.token });51});5253app.listen(port, () => {54 console.log(`Sandbox listening on port ${port}`);55});
1const customerId = 'cus_01HMW4HF2QMJZ3EJKEQ7T04TFQ';23(async () => {4 const response = await fetch('/authenticate', {5 method: 'POST',6 headers: {7 'Content-Type': 'application/json',8 Accept: 'application/json',9 },10 body: JSON.stringify({ customerId }),11 });12 const { token } = await response.json();1314 RebillyInstruments.mount({15 apiMode: 'sandbox',16 invoiceId: 'in_01HTQB8FKKE4C8B79HK1TY3FP9',17 jwt: token,18 });19 // Optional20 RebillyInstruments.on('instrument-ready', (instrument) => {21 console.info('instrument-ready', instrument);22 });2324 RebillyInstruments.on('purchase-completed', (purchase) => {25 console.info('purchase-completed', purchase);26 });27})();
1<!doctype html>2<html lang="en">3 <head>4 <title>Payment 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 <div class="rebilly-instruments-summary"></div>11 <div class="rebilly-instruments"></div>12 </div>13 </body>14</html>