# Hosted payment form API integration

This guide describes how use the Rebilly API to create an order and process a payment using a hosted payment form in the sandbox environment.

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

## Prerequisites

Complete this section to create the resources needed for this guide in your Rebilly sandbox, such as a product, pricing plan, and customer. This section also explains how to obtain required Rebilly sandbox IDs and a secret API key. If you have already created these resources, skip this step and continue to [Step 1: Create an order](#step-1-create-an-order).

Important
To complete a payment using a Rebilly payment form:

- An active gateway is required. If you are testing in the sandbox environment, a test payment gateway called `TestProcessor` is already configured.
- The ready to payout instruction must be active and configured on the gateway. This setting must be manually configured on the `TestProcessor` gateway. For more information, see [set up a payment gateway](/docs/settings/set-up-a-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](/docs/settings/set-up-a-gateway).

details
summary
Expand to complete prerequisites
### Obtain Rebilly sandbox IDs and secret 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](/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.


### 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 [Prerequisites](#prerequisites).

details
summary
How to use the interactive example
1. 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**. For more information, see [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
2. 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 [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
3. Optionally, to change the product details, press **Body**.
4. Press **Send**. 
In the response, note the `id` value. This is the product ID.


### 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](#create-a-product).

details
summary
How to use the interactive example
1. 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**. For more information, see [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
2. 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 [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
3. Enter a product ID:
  1. Press **Body**.
  2. In the `productId` field, a product ID. For more information, see [Create a product](#create-a-product).
  3. Optionally, change the plan details.
4. Press **Send**. 
In the response, note the `id` value. This is the plan ID.


### Upsert a customer

This step creates or updates (upserts) a customer with a specified ID. For more information, see [Upsert a customer with predefined ID](/docs/dev-docs/api/customers/putcustomer/).

details
summary
How to use the interactive example
1. 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**. For more information, see [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
2. 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 [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
3. Enter a customer ID:
  1. In the URL field beneath the **Environment** field, press `{{id}}`.
  2. Press **Set value**.
  3. In the **Value** field, enter a customer ID. 
Example: `cus_01HDP7FFX2PGDVH1995EA4QY95`.
4. Enter your website ID:
  1. Press **Body**.
  2. In the `websiteId`, enter your website ID. For more information, see [Obtain Rebilly sandbox IDs and secret key](#obtain-rebilly-sandbox-ids-and-secret-key).
  3. Optionally, change the customer details.
5. Press **Send**. 
In the response, note the `id` value. This is the customer ID.


## Step 1: Create an order

This step creates a subscription order for the customer you created in the previous step. For more information, see [Create an order](/docs/dev-docs/api/orders/postsubscription).

details
summary
How to use the interactive example
To obtain the required values mentioned in this interactive example, complete the [Prerequisites](#prerequisites) section.

1. 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**.
2. 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**.
3. Enter the order details:
  1. Press **Body**.
  2. In the `customerId` field, enter a customer ID.
  3. In the `websiteId` field, enter your website ID.
  4. In the `id` field, enter a pricing plan ID.
4. Press **Send**.
5. In the response, note the `recentInvoiceId` value. This is used in the next step.


## Step 2: Create hosted payment form URL

This step creates a hosted payment form URL where the customer can complete payment for the invoice you created in the previous step. For more information, see [Create a transaction](/docs/dev-docs/api/transactions/posttransaction).

details
summary
How to use the interactive example
To obtain the required values mentioned in this interactive example, complete the [Prerequisites](#prerequisites) section.

1. 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**.
2. 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**.
3. Enter the transaction details:
  1. In the `customerId` field, enter the customer ID used in [Step 1](#step-1-create-an-order).
  2. In the `websiteId` field, enter the website ID used in [Step 1](#step-1-create-an-order).
  3. In the `invoiceIds` field, enter the `recentInvoiceId` value from the response in [Step 1: Create an order](#step-1-create-an-order).
4. Press **Send**.
5. In the response, in the `_links` field, locate the `approvalUrl` value. This is the hosted payment form URL. The customer uses this link to pay for the order using a hosted payment form in [Step 3: Complete the payment](#step-3-complete-the-payment).


## Step 3: Complete the payment

This step completes the payment using the hosted payment form URL obtained in [Step 2](#step-2-create-hosted-payment-form-url).

1. Open the hosted payment form URL in a web browser.
2. Enter this test card number `4111 1111 1111 1111`, with any future expiration date, and 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).


## Related topics

- [Test transactions](/docs/tutorials/test-transactions#test-transactions).