# 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](/docs/glossary#payment-card-industry-pci-compliance).
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](#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](/docs/settings/set-up-a-gateway).
Payment methods that are displayed in hosted payment forms, such as payment cards and digital wallets, are configured when setting up a gateway account. If you are testing in the sandbox environment, configure payment methods to display in the `TestProcessor` gateway. For more information, see [Set up a payment gateway](/docs/settings/set-up-a-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](#set-up-a-hosted-payment-form).
details
summary
Expand to complete
### 1. Configure payment methods
Payment methods that are displayed in payment forms, such as payment cards and digital wallets, are configured when setting up a gateway account. If you are testing in the sandbox environment, configure payment methods to display in the `TestProcessor` gateway.
- To configure payment methods, see [Set up a payment gateway](/docs/settings/set-up-a-gateway).
- To learn about payment method automation, such as payment method display order and display payment methods by location, see [Payment method automations](/docs/settings/payment-methods#payment-method-automations).
### 2. 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](/docs/settings/organizations-and-websites).
1. [Log in or sign up to Rebilly](https://app-sandbox.rebilly.com/).
2. Obtain your organization ID and website ID:
1. In the left navigation bar, press .
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](/docs/settings/organizations-and-websites).
3. Obtain your secret API key:
1. In the left navigation bar, press .
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.
### 3. Create a product
This API interaction creates a product in your Rebilly sandbox account. For more information, see [Create a product](/docs/dev-docs/api/products/postproduct/).
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](#2.-obtain-ids-and-a-secret-api-key).
details
summary
How to use the interactive example
1. Select the sandbox server environment:
1. In the top right of the interactive example, press the **Environment** dropdown.
2. Select **Sandbox server**.
2. Enter your organization ID:
1. Locate `server /products` press .
2. In the **Server variables** section, press **Edit**.
3. In the **Value** field, enter your organization ID and press **Save**.
3. 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](#prerequisites).
4. Optionally, to change the product details, press **Body**.
5. Press **Send**.
The `id` value from this response is used as the `productId` value in [Step 4](#4.-create-a-pricing-plan).
### 4. 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](/docs/dev-docs/api/plans/postplan/).
To create a pricing plan, you must have a product ID.
For more information, see [Create a product](#3.-create-a-product).
details
summary
How to use the interactive example
1. Select the sandbox server environment:
1. In the top right of the interactive example, press the **Environment** dropdown.
2. Select **Sandbox server**.
2. Enter your organization ID:
1. Locate `server /plans` press .
2. In the **Server variables** section, press **Edit**.
3. In the **Value** field, enter your organization ID and press **Save**.
3. 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](#prerequisites).
4. Enter the product ID from the [Step 3](#3.-create-a-product) response.
1. Press **Body**.
2. In the `productId` field, enter the `id` value from [Step 3](#3.-create-a-product).
3. Optionally, change the plan details.
5. Press **Send**.
## Set up a hosted payment form
Use HTML and CDN
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 API key, Organization ID, and website ID. For more information, see [Prerequisites](#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 `/example` endpoint.
For more information, see [Express example](https://expressjs.com/en/starter/hello-world.html).
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.
Create a transaction
Create an asynchronous transaction that sends data to the Rebilly API and waits for a response.
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.
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 HTML page
Optional: Display transaction parameters
Display the transaction parameters in a code snippet.
Add a button
Add a button to trigger payment processing.
Set up the client
Locate the process payment button
Locate the button element with the ID `process` in the HTML form.
Add an event listener
Add an event listener to the button element to listen for press events.
Disable the button
Disable the button to prevent multiple clicks.
Send a POST request
Send a POST request to the `/payment` endpoint.
Provide required data
Provide payment data.
Parse the response
Parse the JSON response from the server.
Redirect the user
Redirect the user to the provided URL.
Log errors
Log any errors that occur during the process.
Re-enable the button
Re-enable the button after the request is complete.
Basic set up complete
You now have a basic hosted payment form integration.
To learn more, see:
- [Customization](/docs/dev-docs/customize-rebilly-instruments/)
- [Examples](/docs/dev-docs/examples-rebilly-instruments/)
- [Reference](/docs/dev-docs/reference-rebilly-instruments/)
```JavaScript
const express = require("express");
const RebillyAPI = require("rebilly-js-sdk").default;
const app = express();
const port = 3000;
app.use(express.static("client"));
app.use(express.json());
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("/example", async (req, res) => {
res.redirect(301, "/example.html");
});
app.post("/payment", async function (req, res) {
const { customerId, currency, amount, redirectUrl, type } = req.body;
const transaction = await rebilly.transactions.create({
data: {
websiteId: REBILLY_WEBSITE_ID,
customerId,
currency,
amount,
redirectUrl,
type,
paymentInstruction: { methods: [] },
},
});
const approvalUrl = transaction.fields._links.find(
(link) => link.rel === "approvalUrl",
);
if (approvalUrl) {
res.send(approvalUrl);
} else {
res.send(transaction.fields);
}
});
app.listen(port, () => {
console.log(`Sandbox listening on port ${port}`);
});
```
```JavaScript
const button = document.querySelector("#process-payment");
button.addEventListener("click", async (e) => {
e.preventDefault();
try {
button.disabled = true;
const response = await fetch("/payment", {
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
},
body: JSON.stringify({
customerId: "CUSTOMER_ID",
currency: "USD",
amount: 20,
redirectUrl: "https://google.com",
type: "sale",
}),
});
const { href } = await response.json();
window.location.href = href;
} catch (error) {
console.error(error);
} finally {
button.disabled = false;
}
});
```
```HTML
Payment form
```
Preview
This is an interactive example of a Rebilly hosted payment form. Press **Process payment** to see the hosted form.
To complete the payment flow, enter any 3-digits for the CVC number. For more test cards, see [Test payment cards, IBANs, and ACH details](/docs/tutorials/test-transactions#test-payment-cards-ibans-and-ach-details).
div
iframe