# Hosted payout form API integration (Experimental)

This topic describes how to integrate payout requests into your website or checkout flow using the Rebilly API.

Use this integration to create payout requests on behalf of customers using the API, then redirect customers to a Rebilly-hosted payout form where customers select or add a payment instrument for the payout, rather than embedding the form on your website.

To integrate an embedded withdrawal form using the Cashier JavaScript library, where customers enter a withdrawal amount, choose a payment instrument, and submit the withdrawal, see [Integrate a withdrawal form](/docs/dev-docs/integrate-a-withdrawal-form).

## Prerequisites

- Prerequisites

  Complete this section to configure your payment gateway and obtain the resources needed for this guide: an active payment gateway with the ready to payout instruction, a website ID, an organization ID, a secret API key, and a customer ID.
  If you already have these resources, skip this section and go to [Create a payout request using the API](#create-a-payout-request-using-the-api).

  ### Configure ready to payout instruction

  To process payout requests, the ready to payout instruction must be active on at least one payment gateway.

  If you are testing in the sandbox environment and using the `TestProcessor` gateway, you must manually configure this setting on the `TestProcessor` gateway.

  For more information, see [Configure a gateway to manage payout requests](/docs/settings/set-up-a-gateway#optionally,-configure-how-the-gateway-manages-payout-requests).

  ### Obtain 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 **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](/docs/settings/organizations-and-websites).
  3. 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 page, press **Create API key**.
      2. In the **Description** field, enter a recognizable name for the key.
      3. In the **Type** section, select **Secret**.
      4. Optionally, in the **Organizations** dropdown, select the organizations that can use the API key.
      5. Optionally, in the **Allowed IPs** field, enter the IP addresses that are permitted to use the API key.
      6. Press **Save API key**.
      7. Go to the API keys page.
    4. Select a secret key and copy the **Key** value.

  ### Create 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).

    - Interactive example

      - How to use the interactive example

        1. Enter your organization ID:
          1. Locate and press `server /`, then in the **Server variables** section, press **Edit s**.
          2. 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, enter your secret Rebilly sandbox API key.
        For more information, see [Prerequisites](/docs/dev-docs/hosted-payout-integration#prerequisites).
        3. Enter a customer ID:
          1. Press **Path**.
          2. In the input field, enter a customer ID.
        Example: `cus_01HDP7FFX2PGDVH1995EA4QY95`.
        4. Enter your website ID:
          1. Press **Body**.
          2. In the `websiteId` field, enter your website ID.
          3. Optionally, change the customer details.
        5. Press **Send**.
        The `id` value from this response is used as the `customerId` value when creating the payout request in [Step 1: Create a payout request](#step-1-create-a-payout-request).

## Create a payout request using the API

This process describes how to create a payout request using the Rebilly API.

### Step 1: 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 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/).

- Interactive example

  - How to use the interactive example

    1. Enter your organization ID:
      1. Locate and press `server /`, then in the **Server variables** section, press **Edit s**.
      2. 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, enter your secret Rebilly sandbox API key.
    For more information, see [Prerequisites](/docs/dev-docs/hosted-payout-integration#prerequisites).
    3. Enter the payout request details:
      1. Press **Body**.
      2. In the `websiteId` field, enter a website ID.
      3. In the `customerId` field, enter a customer ID.
      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.
    4. Press **Send**.
    In the response, the `selectPaymentInstrumentUrl` field contains the URL of the hosted payout form.
    In the next step, redirect the customer to the hosted payout form.

### Step 2: Redirect the customer to the hosted payout form

Redirect the customer to the hosted payout form using the `selectPaymentInstrumentUrl` URL from [Step 1](#step-1-create-a-payout-request).
In the hosted payout form, the customer selects or adds a preferred payment instrument on which to receive the payout.
For test payment card details, see [Test cards, IBANs, and ACH details](/docs/tutorials/test-payment-cards).

## Allocate a payout

This process 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 [Step 1: Create a payout request](#step-1-create-a-payout-request), after the customer added or selected a payment instrument in the [hosted payout form](#step-2-redirect-the-customer-to-the-hosted-payout-form).

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

- Interactive example

  - How to use the interactive example

    1. Enter your organization ID:
      1. Locate and press `server /`, then in the **Server variables** section, press **Edit s**.
      2. 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, enter your secret Rebilly sandbox API key.
    For more information, see [Prerequisites](/docs/dev-docs/hosted-payout-integration#prerequisites).
    3. Enter a payout request ID:
      1. Press **Path**.
      2. In the input field, enter a payout request ID.
      3. In the **Value** field, enter the `id` value from the response in [Create a payout request](#step-1-create-a-payout-request).
    This is the payout request ID.
    4. 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/).

- Interactive example

  - How to use the interactive example

    1. Enter your organization ID:
      1. Locate and press `server /`, then in the **Server variables** section, press **Edit s**.
      2. 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, enter your secret Rebilly sandbox API key.
    For more information, see [Prerequisites](/docs/dev-docs/hosted-payout-integration#prerequisites).
    3. 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).
    Use the customer ID you obtained in [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.
    Use the payment instrument ID you obtained in [Retrieve a payout request](#step-1-retrieve-a-payout-request).
      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.
    4. 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 process describes how to cancel a payout request with a specified ID using the Rebilly API.

Note
A payout request can be canceled when it is in the `pending`, `ready`, `approved`, or `in-progress` status.

For more information, see [Cancel a payout request](/docs/data-tables/manage-payout-requests#cancel-a-payout-request).

- Interactive example

  - How to use the interactive example

    1. Enter your organization ID:
      1. Locate and press `server /`, then in the **Server variables** section, press **Edit s**.
      2. 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, enter your secret Rebilly sandbox API key.
    For more information, see [Prerequisites](/docs/dev-docs/hosted-payout-integration#prerequisites).
    3. Enter a payout request ID:
      1. Press **Path**.
      2. In the input field, enter a payout request ID.
    Use the payout request ID you obtained in [Step 1: Create a payout request](#step-1-create-a-payout-request).
    4. 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/)