/
Hosted payout API integra...
Last updated

Hosted payout form API integration ExperimentalThis feature is experimental and may change.

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.

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.

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.

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.

  1. Log in or sign up to Rebilly.
  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.
  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.

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 .
    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.
  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.

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.

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 .
    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.
  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. 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.

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.

Step 1. Retrieve a payout request

This step retrieves the payout request you created in Step 1. Create a payout request, after the customer added or selected a payment instrument in the hosted payout form.

For more information, see Retrieve 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 .
    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.
  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. 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.

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 .
    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.
  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.
    3. In the customerId field, enter the id value from Retrieve a payout request.
      Use the customer ID you obtained in Retrieve a payout request.
    4. In the currency field, enter the currency code value from Retrieve a payout request.
    5. In the amount field, enter the amount value from 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. Or select another payment instrument held by the customer.
      Use the payment instrument ID you obtained in 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.

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 .
    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.
  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.
  4. Press Send.
    In the response, the status field value is canceled. This indicates that the payout request is canceled.

Hosted payment API integration

Request KYC docs API guide