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.
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.
- Obtain your organization ID and website ID:
- In the left navigation bar, click Settings .
- In the Management section, click My organization & websites.
- In the Organization details section, note the ID value.
- In the Website section, note the ID value. For more information, see Organizations and websites.
- Obtain your secret API key:
- In the left navigation bar, click Automations .
- In the Development section, click API keys.
- Optionally, if you have not created a secret key:
- In top right of the screen, click Add API.
- In the API key type section, select Secret, then complete the form and click Save API key.
- Go back to the API Keys page.
- 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.
The mock server does not create a working URL in Step 2.
- In the Target server dropdown, select Mock server.
- Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
- Click Parameters, then in the
id
field, enter any value. - Click Send.
Use your Rebilly sandbox server
This process describes how to interact with your Rebilly sandbox in the interactive example.
- In the Target server dropdown, select Sandbox server.
- In the Organization ID field, enter the organization ID you obtained in Get data from your Rebilly sandbox.
- Click Security, then in the REB-APIKEY field, enter your sandbox API key you obtained in Get data from your Rebilly sandbox.
- Click Body, enter the
websiteId
value you obtained in Get data from your Rebilly sandbox. - Click Parameters, then in the
id
field, enter the ID of the customer that you want to create or update. - Click Send.
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.
The mock server does not create a working URL in this step.
- In the Target server dropdown, select Mock server.
- Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
- 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.
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.
- In the Target server dropdown, select Sandbox server.
- In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
- Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
- Click Body, and enter the following:
- In the
websiteId
field, enter thewebsiteId
value from the Get data from your Rebilly sandbox. - In the
customerId
field, enter theid
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 than50
.NoteThe amount must be less than
50
to complete the process in the sandbox environment.
- In the
- 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.
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.
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.- In the Target server dropdown, select Mock server.
- Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
- In the Parameters field, enter the
id
value from the response in Create a payout request. This is the ID of the payout request. - Click Send.
In the response, thepaymentInstrumentId
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.
- In the Target server dropdown, select Sandbox server.
- In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
- Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
- Click Parameters, and enter the
id
value from the response in Create a payout request. This is the ID of the payout request. - 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.
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.
The mock server returns a 500
message for this operation.
- In the Target server dropdown, select Mock server.
- Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
- Click Body, and enter the following:.
- In the
paymentInstrumentId
field, enter the value you obtained in the response in Retrieve a payout request. - In the
payoutRequestId
field, enter theid
value you obtained in the response in Create a payout request.
- In the
- Click Send.
In the response, thestatus
field value iscompleted
, and theresult
value isapproved
. This indicates that the payout was successful.
Note: The mock server returns a500
message for this operation.
Use your Rebilly sandbox server
This process describes how to interact with your Rebilly sandbox in the interactive example.
- In the Target server dropdown, select Sandbox server.
- In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
- Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
- Click Body, and enter the following:
- In the
websiteId
field, enter thewebsiteId
value from Retrieve a payout request. - In the
customerId
field, enter theid
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.
- In the
- Click Send.
- In the
payoutRequestId
field, enter theid
value from the response in Retrieve a payout request.
In the response, thestatus
field value iscompleted
, and theresult
value isapproved
. This payout was successful.
Cancel a payout request
This section describes how to cancel a payout request with a specified ID using the Rebilly API.
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.- In the Target server dropdown, select Mock server.
- Click Security, then in the REB-APIKEY field, enter any alphanumeric value.
- In the Parameters field, enter the
id
for the payout request. If you are experimenting, use theid
value from the response in Create a payout request. - Click Send.
In the response, thestatus
field value iscanceled
. 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.- In the Target server dropdown, select Sandbox server.
- In the Organization ID field, enter your organization ID from Get data from your Rebilly sandbox.
- Click Security, then in the REB-APIKEY field, enter your sandbox API key from Get data from your Rebilly sandbox.
- Click Parameters, and enter the
id
value from the response in Create a payout request. This is the ID of the payout request. - Click Send.
In the response, thestatus
field value iscanceled
. This indicates that the payout request was canceled.