Integrate a hosted payment form

This guide describes how to integrate a hosted payment form into your website.

Hosted payment forms simplify the process of accepting payments. Rebilly hosts your payment forms and ensures that your payments process is secure and PCI-compliant.

Use payment forms to process payments from your customers. To interact with an example hosted payment form, see the Preview tab in the Set up a hosted 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 hosted 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 hosted payment form.

Expand to complete

1) Obtain IDs and a secret API key

This step describes how to obtain your website ID, organization ID, and secret API key from your Rebilly sandbox account.

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.

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 a secret API key.

How to use the interactive example

Enter your organization ID:
1. Beneath the Environment field, press {{server}}.
2. Beneath the URL, press Show nested variables, then press Edit.
3. In the Value field, enter your organization ID and press Save.
Enter your secret API key:
1. Press Security.
2. In the API key field, press {{SecretApiKey}}, then press Set value.
3. In the Value field, enter your secret Rebilly sandbox API key and press Save. For more information, see Prerequisites.
Optionally, to change the product details, press Body.
Press Send.
The id value from this response is used as the productId value in Step 3.

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. For more information, see Create a product.

How to use the interactive example

Enter your organization ID:
1. Beneath the Environment field, press {{server}}.
2. Beneath the URL, press Show nested variables, then press Edit.
3. In the Value field, enter your organization ID and press Save.
Enter your secret API key:
1. Press Security.
2. In the API key field, press {{SecretApiKey}}, then press Set value.
3. 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.
1. Press Body.
2. In the productId field, enter the id value from Step 2.
3. Optionally, change the plan details.
Press Send.

Set up a hosted payment form

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.

server.js

Provide credentials

Provide your secret API key and website 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 /example endpoint. For more information, see Express example.

server.js

Define route for POST requests

Define route for handling HTTP POST requests to the /payment endpoint, and extract parameters from customerId, currency, amount, and redirectUrl from the request body. These values are used to create a transaction.

Note: redirectUrl is the URL that the customer is redirected to after a payment is completed.

server.js

Create a transaction

Create an asynchronous transaction that sends data to the Rebilly API and waits for a response.

server.js

Configure the redirect

Check if the response includes an approvalUrl. This value is the hosted payment form.

If this value is included in the response, redirect the client to the URL to complete the payment.

If this value is not returned, send the transaction details back to the client.

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 HTML page

Optional: Display transaction parameters

Display the transaction parameters in a code snippet.

example.html

Add a button

Add a button to trigger payment processing.

example.html

Set up the client

Locate the process payment button

Locate the button element with the ID process in the HTML form.

client.js

Add an event listener

Add an event listener to the button element to listen for press events.

client.js

Disable the button

Disable the button to prevent multiple clicks.

client.js

Send a POST request

Send a POST request to the /payment endpoint.

client.js

Provide required data

Provide payment data.

client.js

Parse the response

Parse the JSON response from the server.

client.js

Redirect the user

Redirect the user to the provided URL.

client.js

Log errors

Log any errors that occur during the process.

client.js

Re-enable the button

Re-enable the button after the request is complete.

client.js

Basic set up complete

You now have a basic hosted payment form integration. To learn more, see:

Copy to clipboard

server.js
client.js
example.html

1const express = require("express");
2const RebillyAPI = require("rebilly-js-sdk").default;
3const app = express();
4const port = 3000;
5
6app.use(express.static("client"));
7app.use(express.json());
8
9const REBILLY_API_SECRET_KEY = "REBILLY_API_SECRET_KEY";
10const REBILLY_WEBSITE_ID = "REBILLY_WEBSITE_ID";
11
12
13const rebilly = RebillyAPI({
14    sandbox: true,
15    apiKey: REBILLY_API_SECRET_KEY,
16});
17
18app.get("/example", async (req, res) => {
19    res.redirect(301, "/example.html");
20});
21
22app.post("/payment", async function (req, res) {
23    const { customerId, currency, amount, redirectUrl, type } = req.body;
24
25    const transaction = await rebilly.transactions.create({
26        data: {
27            websiteId: REBILLY_WEBSITE_ID,
28            customerId,
29            currency,
30            amount,
31            redirectUrl,
32            type,
33            paymentInstruction: { methods: [] },
34        },
35    });
36
37    const approvalUrl = transaction.fields._links.find(
38        (link) => link.rel === "approvalUrl",
39    );
40    if (approvalUrl) {
41        res.send(approvalUrl);
42    } else {
43        res.send(transaction.fields);
44    }
45});
46
47app.listen(port, () => {
48    console.log(`Sandbox listening on port ${port}`);
49});

1const button = document.querySelector("#process-payment");
2
3button.addEventListener("click", async (e) => {
4    e.preventDefault();
5    try {
6        button.disabled = true;
7        const response = await fetch("/payment", {
8            method: "POST",
9            headers: {
10                "Content-Type": "application/json",
11                Accept: "application/json",
12            },
13            body: JSON.stringify({
14                customerId: "CUSTOMER_ID",
15                currency: "USD",
16                amount: 20,
17                redirectUrl: "https://google.com",
18                type: "sale",
19            }),
20        });
21        const { href } = await response.json();
22
23        window.location.href = href;
24    } catch (error) {
25        console.error(error);
26    } finally {
27        button.disabled = false;
28    }
29});

1<!doctype html>
2<html lang="en">
3    <head>
4        <title>Payment form</title>
5        <script src="./client.js" defer></script>
6    </head>
7    <body>
8        <div id="app">
9            <code>
10                <pre>
11                {
12                    customerId: CUSTOMER_ID
13                    currency: USD
14                    amount: 20
15                    redirectUrl: https://google.com
16                    type: sale
17                }
18                </pre>
19            </code>
20            <button id="process-payment">Process payment</button>
21        </div>
22    </body>
23</html>

Our Solutions

Products

Features

Solutions

About

Integrate a hosted payment form

Prerequisites

1) Obtain IDs and a secret API key

2) Create a product

3) Create a pricing plan

Set up a hosted payment form

Set up the server

Install and initialize dependencies

Provide credentials

Initialize Rebilly JS SDK

Define route for GET requests

Define route for POST requests

Create a transaction

Configure the redirect

Listen for requests

Set up the HTML page

Optional: Display transaction parameters

Add a button

Set up the client

Locate the process payment button

Add an event listener

Disable the button

Send a POST request

Provide required data

Parse the response

Redirect the user

Log errors

Re-enable the button

Basic set up complete

Was this helpful?