Developer docs
/
Hosted payout API integration
Last updated
These docs are intended for a developer audience.Dismiss

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.

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.

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

Interactive example
How to use the interactive example
  1. Enter your organization ID:
    1. Beneath the Environment field, press {{server}}.
    2. Beneath the URL, press Show nested variables, then press Edit.
    3. 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, 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.
  3. 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.
  4. Enter your website ID:
    1. Press Body.
    2. In the websiteId, 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 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, press {{server}}.
    2. Beneath the URL, press Show nested variables, then press Edit.
    3. 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, 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.
  3. Enter the deposit details:
    1. Press 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. 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.
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 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.

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, press {{server}}.
    2. Beneath the URL, press Show nested variables, then press Edit.
    3. 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, 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.
  3. 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. This is the ID of 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.
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, press {{server}}.
    2. Beneath the URL, press Show nested variables, then press Edit.
    3. 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, 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.
  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.
    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. Press 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, press {{server}}.
    2. Beneath the URL, press Show nested variables, then press Edit.
    3. 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, 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.
  3. 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. This is the ID of the payout request ID.
  4. Press Send.
    In the response, the status field value is canceled. This indicates that the payout request is canceled.
Loading...
Previous page
Next page