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.

The interactive steps in this tutorial are pre-configured with sample data using a mock server. The mock server has limitations in that is cannot produce a working URL in Create a payout request and is unable to execute the payout in Allocate a payout.

To interact with your Rebilly sandbox in the interactive steps, use the sandbox server and replace the sample data with data from your Rebilly sandbox.

Optional: Get data from your Rebilly sandbox

Complete this section to interact with your Rebilly sandbox in the interactive examples in this tutorial, and to use your own data. Skip this step to use the pre-configured sample data with the mock server.

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

Select from the following server options:

Use a mock server

This process describes how to use a mock server in the interactive example.

Note

The mock server does not create a working URL in Step 2.

  1. In the Target server dropdown, select Mock server.
  2. Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
  3. Click Parameters, then in the id field, enter any value.
  4. Click Send.
Use your Rebilly sandbox server

This process describes how to interact with your Rebilly sandbox in the interactive example.

  1. In the Target server dropdown, select Sandbox server.
  2. In the Organization ID field, enter the organization ID you obtained in Get data from your Rebilly sandbox.
  3. Click Security, then in the REB-APIKEY field, enter your sandbox API key you obtained in Get data from your Rebilly sandbox.
  4. Click Body, enter the websiteId value you obtained in Get data from your Rebilly sandbox.
  5. Click Parameters, then in the id field, enter the ID of the customer that you want to create or update.
  6. Click Send.
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

Select from the following server options:

Use a mock server

This process describes how to use a mock server in the interactive example.

Note

The mock server does not create a working URL in this step.

  1. In the Target server dropdown, select Mock server.
  2. Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
  3. Click Send.
  4. In the response, the selectPaymentInstrumentUrl contains a hosted payment instrument selection form. In the next step, you will redirect the customer to this URL.
    Note: The mock server does not create a working URL.
Use your Rebilly sandbox server

This process describes how to interact with your Rebilly sandbox in the interactive example.

  1. In the Target server dropdown, select Sandbox server.
  2. In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
  3. Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
  4. Click Body, and enter the following:
    • In the websiteId field, enter the websiteId value from the Get data from your Rebilly sandbox.
    • In the customerId field, enter the id value from the response in Upsert a customer.
    • In the currency field, enter a currency code.
    • In the amount field, enter an amount that is less than 50.
      Note

      The amount must be less than 50 to complete the process in the sandbox environment.

  5. Click Send.
  6. 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

Select from the following server options:

Use a mock server This process describes how to use a mock server in the interactive example.
  1. In the Target server dropdown, select Mock server.
  2. Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
  3. In the Parameters field, enter the id value from the response in Create a payout request. This is the ID of the payout request.
  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.
Use your Rebilly sandbox server

This process describes how to interact with your Rebilly sandbox in the interactive example.

  1. In the Target server dropdown, select Sandbox server.
  2. In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
  3. Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
  4. Click Parameters, and enter the id value from the response in Create a payout request. This is the ID of the payout request.
  5. Click Send.
  6. 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

Select from the following server options:

Use a mock server

This process describes how to use a mock server in the interactive example.

Note

The mock server returns a 500 message for this operation.

  1. In the Target server dropdown, select Mock server.
  2. Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
  3. Click Body, and enter the following:.
  4. Click Send.
    In the response, the status field value is completed, and the resultvalue is approved. This indicates that the payout was successful.
    Note: The mock server returns a 500 message for this operation.
Use your Rebilly sandbox server

This process describes how to interact with your Rebilly sandbox in the interactive example.

  1. In the Target server dropdown, select Sandbox server.
  2. In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
  3. Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
  4. Click Body, and enter the following:
    • In the websiteId field, enter the websiteId value from Retrieve a payout request.
    • In the customerId field, enter the id value from Retrieve a payout request.
    • In the currency field, enter the currency code value from Retrieve a payout request.
    • In the amount field, enter the amount value from Retrieve a payout request.
    • 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.
    • Optionially, if you would like to use a specific payment gateway: in the gatewayAccountId field, enter the ID of the gateway.
  5. Click Send.
  6. In the payoutRequestId field, enter the id value from the response in Retrieve a payout request.
    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 Select from the following server options:
Use a mock server This process describes how to use a mock server in the interactive example.
  1. In the Target server dropdown, select Mock server.
  2. Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
  3. In the Parameters field, enter the id for the payout request. If you are experimenting, use the id value from the response in Create a payout request.
  4. Click Send.
    In the response, the status field value is canceled. This indicates that the payout request was canceled.
Use your Rebilly sandbox server This process describes how to interact with your Rebilly sandbox in the interactive example.
  1. In the Target server dropdown, select Sandbox server.
  2. In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
  3. Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
  4. Click Parameters, and enter the id value from the response in Create a payout request. This is the ID of the payout request.
  5. Click Send.
    In the response, the status field value is canceled. This indicates that the payout request was canceled.
Loading...
Previous page
Next page