# Hosted payout form API integration 

This topic describes how to integrate a Rebilly hosted payout form into your website, or checkout flow, using the Rebilly API. Use payout forms to allow customers to request payouts. In the payout form, customers must select or add a preferred payment instrument on which to receive the payout.

## Prerequisites

Complete this section to interact with your Rebilly sandbox in the interactive examples in this tutorial, and to use your own data.

Important
To complete a payout using a Rebilly hosted payout:

- 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 payout form are based on the gateway configuration. For more information, see [Set up a payment gateway](/docs/settings/set-up-a-gateway).

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 hosted payout form

This section describes how to create a hosted payout form using the Rebilly API.

### Step 1: Upsert a customer

This step creates or updates (upserts) a customer with a specified ID.

This operation prevents duplicate customers. 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 more information, see [Upsert a customer](/catalog/all/customers/putcustomer).

details
summary
Interactive example
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 order in [Step 2](#step-2-create-a-payout-request). The `websiteId` value is also used in [Step 2](#step-2-create-a-payout-request).


### Step 2: Create a payout request

This step creates a payout request using the customer that you created in the previous step.

In the response, the `selectPaymentInstrumentUrl` field contains the URL of the hosted payout request form. Redirect the customer to this URL to select or add a preferred payment instrument on which to receive the payout.

For more information, see [Create a payout request](/docs/dev-docs/api/transactions/postpayoutrequest/).

details
summary
Interactive example
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 /payout-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 `websiteId` field, enter the `websiteId` value you used in [Step 1](#step-1-upsert-a-customer).
  3. In the `customerId` field, enter the `id` value from the response in [Step 1](#step-1-upsert-a-customer).
  4. In the `currency` field, enter a currency code.
  5. In the `amount` field, enter an amount that is less than `50`.
The amount must be less than `50` to complete the process in the sandbox environment.
5. Press **Send**. 
In the response, the `selectPaymentInstrumentUrl` contains a hosted payment instrument selection form. In the next step, you will redirect the customer to this URL.


### Step 3: Redirect the customer to select or add a payment instrument

Redirect the customer to the `selectPaymentInstrumentUrl` URL that you created in [Step 2](#step-2-create-a-payout-request). This URL contains a hosted payment instrument selection form. When the customer opens this URL, they are prompted to select or add a preferred payment instrument on which to receive the payout. For test payment card details, see [Test payment cards, IBANs, and ACH details](/docs/tutorials/test-transactions#test-payment-cards-ibans-and-ach-details)

## Allocate a payout

This section describes how to allocate a payout to a customer's payment instrument using the Rebilly API.

Note
Payouts can also be allocated using the Rebilly UI. For more information, see [Allocate funds](/docs/data-tables/manage-payout-requests#allocate-funds).

### Step 1: Retrieve a payout request

This step retrieves the payout request you created in [Create a hosted payout form](#step-2-create-a-payout-request), the customer added or selected a payment instrument in [Create a hosted payout form](#step-3-redirect-the-customer-to-select-or-add-a-payment-instrument).

For more information, see [Retrieve a payout request](/docs/dev-docs/api/transactions/getpayoutrequest/).

details
summary
Interactive example
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 /payout-requests/{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 payout request ID:
  1. In the URL field beneath the **Environment** field, press `{{id}}`.
  2. Press **Set value**.
  3. In the **Value** field, enter the `id` value from the response in [Create a payout request](#step-2-create-a-payout-request). This is the ID of the payout request ID.
5. Press **Send**. 
In the response, the `paymentInstrumentId` field contains the ID of the payment instrument on which the customer would prefer to receive the payout.


### Step 2: Allocate a payout

This step processes the payout request by allocating an amount to a credit transaction. This amount is transferred to the customer's payment instrument. The customer has indicated their preference, but the funds may be sent to any applicable payment instrument held by the customer.

For more information, see [Create a credit transaction](/docs/dev-docs/api/transactions/postpayout/).

details
summary
Interactive example
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 /payouts` 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 details of the payout request:
  1. Press **Body**.
  2. In the `websiteId` field, enter the `websiteId` value from [Retrieve a payout request](#step-1-retrieve-a-payout-request).
  3. In the `customerId` field, enter the `id` value from [Retrieve a payout request](#step-1-retrieve-a-payout-request).
  4. In the `currency` field, enter the currency code value from [Retrieve a payout request](#step-1-retrieve-a-payout-request).
  5. In the `amount` field, enter the amount value from [Retrieve a payout request](#step-1-retrieve-a-payout-request).
  6. In the `paymentInstrumentId` field, to use the customer's preferred payment instrument, use the value you obtained in the response in [Retrieve a payout request](#step-1-retrieve-a-payout-request). Or select another payment instrument held by the customer.
  7. Optionally, if you would like to use a specific payment gateway: in the `gatewayAccountId` field, enter the ID of the gateway.
The amount must be less than `50` to complete the process in the sandbox environment.
5. Press **Send**. 
In the response, the `status` field value is `completed`, and the `result`value is `approved`. This payout was successful.


## Cancel a payout request

This section describes how to cancel a payout request with a specified ID using the Rebilly API.

Note
A payout request can only be canceled if it has the `pending` or `instrument-selected` status.

For more information, see [Cancel a payout request](/docs/dev-docs/api/transactions/postpayoutrequestcancellation).

details
summary
Interactive example
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 /payout-requests/{id}/cancel` 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 payout request ID:
  1. In the URL field beneath the **Environment** field, press `{{id}}`.
  2. Press **Set value**.
  3. In the **Value** field, enter the `id` value from the response in [Create a payout request](#step-2-create-a-payout-request). This is the ID of the payout request ID.
5. Press **Send**. 
In the response, the `status` field value is `canceled`. This indicates that the payout request is canceled.


## Related webhooks

- [Payment instruments](/catalog/all/payment-instruments)
- [Transactions](/catalog/all/transactions)
- [Transaction processed](/docs/dev-docs/api/transactions/transaction-processed/)
- [Payout request created](/docs/dev-docs/api/transactions/payout-request-created/)
- [Payout request canceled](/docs/dev-docs/api/transactions/payout-request-canceled/)
- [Payout request modified](/docs/dev-docs/api/transactions/payout-request-modified/)