Developer docs
/
Payouts
/
Hosted payout API integration
Last updated

These docs are intended for a developer audience.

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.

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, click Settings .
    2. In the Management section, click 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, click Automations .
    2. In the Development section, click API keys.
    3. Optionally, if you have not created a secret key:
      1. In top right of the screen, click Add API.
      2. In the API key type section, select Secret, then complete the form and click Save API key.
      3. Go back 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.

Interactive example
How to use the interactive example
  1. Enter your organization ID:
    1. Beneath the Environment field, click {{server}}.
    2. Beneath the URL, click Show nested variables, then click Edit.
    3. In the Value field, enter your organization ID and click Save.
  2. Enter your secret API key:
    1. Click Security.
    2. In the API key field, click {{SecretApiKey}}, then click Set value.
    3. In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
  3. Enter a customer ID:
    1. In the URL field beneath the Environment field, click {{id}}.
    2. Click Set value.
    3. In the Value field, enter a customer ID.
      Example: cus_01HDP7FFX2PGDVH1995EA4QY95.
  4. Enter your website ID:
    1. Click Body.
    2. In the websiteId, enter your website ID.
    3. Optionally, change the customer details.
  5. Click Send.
    The id value from this response is used as the customerId value when creating the order in Step 2. The websiteId value is also used in Step 2.
Loading...

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.

Interactive example
How to use the interactive example
  1. Enter your organization ID:
    1. Beneath the Environment field, click {{server}}.
    2. Beneath the URL, click Show nested variables, then click Edit.
    3. In the Value field, enter your organization ID and click Save.
  2. Enter your secret API key:
    1. Click Security.
    2. In the API key field, click {{SecretApiKey}}, then click Set value.
    3. In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
  3. Enter the deposit details:
    1. Click Body.
    2. In the websiteId field, enter the websiteId value you used in Step 1.
    3. In the customerId field, enter the id value from the response in Step 1.
    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. Click 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.
Loading...

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

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.

Step 1: Retrieve a payout request

This step retrieves the payout request you created in Create a hosted payout form, the customer added or selected a payment instrument in Create a 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. Beneath the Environment field, click {{server}}.
    2. Beneath the URL, click Show nested variables, then click Edit.
    3. In the Value field, enter your organization ID and click Save.
  2. Enter your secret API key:
    1. Click Security.
    2. In the API key field, click {{SecretApiKey}}, then click Set value.
    3. In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
  3. Enter a payout request ID:
    1. In the URL field beneath the Environment field, click {{id}}.
    2. Click Set value.
    3. In the Value field, enter the id value from the response in Create a payout request. This is the ID of the payout request ID.
  4. Click Send.
    In the response, the paymentInstrumentId field contains the ID of the payment instrument on which the customer would prefer to receive the payout.
Loading...

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. Beneath the Environment field, click {{server}}.
    2. Beneath the URL, click Show nested variables, then click Edit.
    3. In the Value field, enter your organization ID and click Save.
  2. Enter your secret API key:
    1. Click Security.
    2. In the API key field, click {{SecretApiKey}}, then click Set value.
    3. In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
  3. Enter the details of the payout request:
    1. Click 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.
    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.
    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. Click Send.
    In the response, the status field value is completed, and the resultvalue is approved. This payout was successful.
Loading...

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.

Interactive example
How to use the interactive example
  1. Enter your organization ID:
    1. Beneath the Environment field, click {{server}}.
    2. Beneath the URL, click Show nested variables, then click Edit.
    3. In the Value field, enter your organization ID and click Save.
  2. Enter your secret API key:
    1. Click Security.
    2. In the API key field, click {{SecretApiKey}}, then click Set value.
    3. In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
  3. Enter a payout request ID:
    1. In the URL field beneath the Environment field, click {{id}}.
    2. Click Set value.
    3. In the Value field, enter the id value from the response in Create a payout request. This is the ID of the payout request ID.
  4. Click Send.
    In the response, the status field value is canceled. This indicates that the payout request is canceled.
Loading...
Previous page
Next page