# Hosted deposit API integration 

This topic describes how to integrate a Rebilly hosted deposit form into your website, or checkout flow, using the Rebilly API.

Rebilly hosted deposits provide a secure and compliant way to deposit funds. Deposit forms use fully responsive design, built-in error messaging, and validation. The creation of hosted deposit forms is limited to one per [organization](/docs/settings/organizations-and-websites). Use Rebilly hosted deposits to control deposit amounts that are presented to the customer and to process the deposit.

Optionally, use deposit strategies to determine the amounts presented to the customer. Deposit strategies filter deposit requests by currency, customer segmentation (tags), or prior deposit behavior. If a deposit request matches several strategies, a strategy is randomly selected.

## Prerequisites

To complete this tutorial, you need a Rebilly account, a website ID, an organization ID, a secret API key, and a customer ID. You must also have at least one payment gateway configured in your Rebilly account. If you are testing in the sandbox environment, a test payment gateway called `TestProcessor` is already configured.

Payment methods that are displayed in the hosted deposit form are based on the gateway configuration. For more information, see [Set up a payment gateway](/docs/settings/set-up-a-gateway).

details
summary
Obtain your organization ID, website ID, and secret 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](/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.


details
summary
Configure a payment gateway
To set up or configure a payment gateway, see [Set up a payment gateway](/docs/settings/set-up-a-gateway).

details
summary
Create a customer
This example creates or updates (upserts) a customer with a specified ID. 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](/catalog/all/customers/putcustomer).

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 /customers/{id}` 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 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`.
5. Enter your website ID:
  1. Press **Body**.
  2. In the `websiteId`, enter your website ID.
  3. Optionally, change the customer details.
6. Press **Send**. 
The `id` value from this response is used as the `customerId` value when creating the deposit request in [Step 2](#step-2-create-a-deposit-request). The `websiteId` value is also used in [Step 2](#step-2-create-a-deposit-request).


## Step 1: Optionally, create a deposit strategy

This step creates a deposit strategy. Use deposit strategies to determine the amounts presented to the customer. Deposit strategies filter deposit requests by currency, customer segmentation (tags), or prior deposit behavior. If a deposit request matches several strategies, a strategy is randomly selected.

Deposit strategies are optional. You do not need to create a deposit strategy to create a deposit request.

For detailed information about this API operation, see [Create a deposit strategy](/catalog/all/deposits/postdepositstrategy).

details
summary
Interactive example
This example creates a deposit strategy that displays buttons for deposit amounts of $10, $20, $30, and $40. The strategy supports custom deposits between $10 and $1000, with a minimum of $10 and a multiple of $10. The strategy does not adjust the base amount to the last deposit.

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**.
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 [Prerequisites](#prerequisites).
3. Enter strategy details:
  1. Press **Body**.
  2. In the `name` field, enter a strategy name. 
Example: `Test strategy`.
  3. In the `amounts` field, specify the amounts to display as buttons in the deposit form. 
Example: `{"calculator": "absolute", "baseAmount": 10.00, "increments": [10.00, 20.00, 30.00], "adjustBaseToLastDeposit": false}`.
  4. Optionally, in the `customAmount` field, specify the custom amount limits. 
Example: `{"minimum": 10.00, "multipleOf": 10.00, "maximum": 1000.00}`.
4. Press **Send**. 
Use the `id` value from this response as the `strategyId` value when creating the deposit request in [Step 2](#step-2-create-a-deposit-request).


## Step 2: Create a deposit request

This step creates a deposit request using the customer that you created and the website ID that you obtained in the previous step. When the customer opens the URL included in the response, a Rebilly hosted deposit form is displayed to complete the deposit.

In the response, in the `_links` field, under `"rel": "deposit"`, the `href` field contains the deposit URL.

For detailed information about this API operation, see [Create a deposit request](/catalog/all/deposits/postdepositrequest).

details
summary
Interactive example
This example creates a deposit request using the `customerId` value you created in the previous step.

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 /deposit-requests` 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 deposit details:
  1. Press **Body**.
  2. In the `customerId` field, enter the `id` of a customer. To create a customer, see [Prerequisites](#prerequisites).
  3. In the `websiteId` field, enter your website ID.
  4. Optionally, to apply a specific strategy for the request, use the `strategyId` field. To create a strategy, see [Step 1](#step-1-optionally-create-a-deposit-strategy).
  5. Optionally, to apply a deposit amount limit, in the `amountLimits` field, specify `minimum` and `maximum` amount values. Limits override `amounts` and `customAmount` values.
5. Press **Send**. 
In the response, in the `_links` field, under `"rel": "deposit"`, the `href` field contains the deposit URL. The value is used to redirect the customer to the deposit form in [Step 3](#step-3-redirect-the-customer-to-the-deposit-url-to-complete-the-deposit).


## Step 3: Redirect the customer to the deposit URL to complete the deposit

Redirect the customer to the deposit URL that you created in [Step 2](#step-2-create-a-deposit-request). After completing the deposit form, the hosted payment form is displayed to complete the deposit.

## Related webhooks

- [Payment instruments](/catalog/all/payment-instruments)
- [Transactions](/catalog/all/transactions)