Create a payout request
Experimental

Request

Creates a payout request. In the response, the selectPaymentInstrumentUrl field is used to redirect the customer to select a preferred payment instrument. After a payment instrument is selected, the customer is redirected to the selectedPaymentInstrumentRedirectUrl value.

Important: The selected payment gateway must be configured to support payout requests. For more information, see the readyToPayoutInstruction field.

Security
SecretApiKey or JWT
Bodyapplication/jsonrequired
Payout request resource.
websiteIdstring, <= 50 characters(WebsiteId)required
Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"
customerIdstring, <= 50 characters(CustomerId)required
ID of the customer who is requesting a payout.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
paymentInstrumentIdstring or null, <= 50 characters
ID of the requested payment instrument to offer for the payout.
Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
currencystring, = 3 characters(CurrencyCode)required
Currency of the payout.
Example:"USD"
amountnumber, (double)required
Amount of the payout.
descriptionstring or null
Description of payout request.
blockedboolean

Specifies if the payout request is blocked or unblocked.

When blocked, the payout request cannot transition to ready, approved, in-progress, merged, or split. Allocation creation and allocation processing are also blocked. Cancellation of the payout request and pending allocations remains available. When a blocked payout request is canceled, blocked is set to false, blockReason is set to null, and the block reason is added to the cancellation description. If allocation processing starts before the payout request is blocked, the request still transitions to the fulfilled status.

Example:false
blockReasonPayoutRequestBlockReason (string) or null
One of:
Reason for blocking the payout request.
string(PayoutRequestBlockReason)
Enum:"fraud-suspected""kyc-verification-required""aml-review""account-verification""duplicate-request""insufficient-documentation""risk-review""other"
splitReasonPayoutRequestSplitReason (string) or null
One of:
Reason for splitting the payout request.
string(PayoutRequestSplitReason)
Enum:"payment-instrument-limit""processor-limit""risk-review""compliance-review""partial-processing""operational-reconciliation""other"
selectedPaymentInstrumentRedirectUrlstring, (uri), <= 2083 characters

URL where the customer is redirected when a payment instrument is selected. The default value is the website URL. Use {{id}} as a placeholder for the payout request ID.

Example:"https://example.com/payout-request-success"
curl -i -X POST \
  https://www.rebilly.com/_mock/catalog/all/payout-requests \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
    "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
    "paymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
    "currency": "USD",
    "amount": 0.1,
    "description": "string",
    "blocked": false,
    "blockReason": "fraud-suspected",
    "splitReason": "payment-instrument-limit",
    "selectedPaymentInstrumentRedirectUrl": "https://example.com/payout-request-success"
  }'

Responses

Payout request created.
Headers
Locationstring, (uri)
Location of the related resource.
Example:"https://api.rebilly.com/example"
Rate-Limit-Limitinteger

Maximum number of requests available at one time for this rate limit. For more information, see Rate limits.

Example:500
Rate-Limit-Remaininginteger

Number of requests still available for this rate limit. For more information, see Rate limits.

Example:499
Bodyapplication/json
idstring, <= 50 charactersread-only
Unique resource ID.
Example:"pout_req_0YVDMDE2BMC6KBB5MX76RF6T80"
websiteIdstring, <= 50 characters(WebsiteId)required
Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"
customerIdstring, <= 50 characters(CustomerId)required
ID of the customer who is requesting a payout.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
paymentInstrumentIdstring or null, <= 50 characters
ID of the requested payment instrument to offer for the payout.
Example:"inst_0YVB8KPKNXCBR9EDX7JHSED75N"
splitFromPayoutRequestIdstring or null, <= 50 charactersread-only

ID of the payout request from which this request is split, or null if this request is not created by a split operation.

Example:"pout_req_0YVDMDE2BMC6KBB5MX76RF6T80"
mergedIntoPayoutRequestIdstring or null, <= 50 charactersread-only

ID of the payout request that this request is merged into, or null if it is not merged into another request.

Example:"pout_req_0YVDMDE2BMC6KBB5MX76RF6T80"
currencystring, = 3 characters(CurrencyCode)required
Currency of the payout.
Example:"USD"
amountnumber, (double)required
Amount of the payout.
availableAmountnumber, (double)read-only
Available payout request amount that has not been allocated.
descriptionstring or null
Description of payout request.
statusstringread-only
Status of the request.
Enum ValueDescription
pending

Request was created by the customer and is in a pending state for the configured pending period, unless it is marked as ready by a member of your organization. When automatic readiness is enabled, the payout request transitions to the ready state after the pending period elapses and the configured transition time is reached. Depending on the configured automaticReadinessEnabled setting, this may be the initial status assigned to new payout requests, or this status may not be used.

ready

Request was created by the customer and is ready for review. Depending on the configured automaticReadinessEnabled setting, this may be the initial status assigned to new payout requests.

approved
Request was reviewed, approved, and is ready for processing.
in-progress
Request has allocations and is being processed.
fulfilled
Request is fully paid out.
canceled
Request is canceled by merchant or customer.
split
Request was split into two or more payout requests.
merged
Request was merged into another payout request.
blockedboolean

Specifies if the payout request is blocked or unblocked.

When blocked, the payout request cannot transition to ready, approved, in-progress, merged, or split. Allocation creation and allocation processing are also blocked. Cancellation of the payout request and pending allocations remains available. When a blocked payout request is canceled, blocked is set to false, blockReason is set to null, and the block reason is added to the cancellation description. If allocation processing starts before the payout request is blocked, the request still transitions to the fulfilled status.

Example:false
blockReasonPayoutRequestBlockReason (string) or null
One of:
Reason for blocking the payout request.
string(PayoutRequestBlockReason)
Enum:"fraud-suspected""kyc-verification-required""aml-review""account-verification""duplicate-request""insufficient-documentation""risk-review""other"
splitReasonPayoutRequestSplitReason (string) or null
One of:
Reason for splitting the payout request.
string(PayoutRequestSplitReason)
Enum:"payment-instrument-limit""processor-limit""risk-review""compliance-review""partial-processing""operational-reconciliation""other"
batchIdstring or null, <= 50 charactersread-only
ID of the payout request batch that contains this request.
Example:"prb_0YVDMDE2BMC6KBB5MX76RF6T80"
batchNamestring or null, <= 255 charactersread-only

Short name of the payout request batch that contains this request. This value is null if the request is not in a batch or the batch has no name.

Example:"Weekly CAD payouts"
batchDescriptionstring or null, <= 255 charactersread-only

Description of the payout request batch that contains this request. This value is null if the request is not in a batch or the batch has no description.

Example:"Batch processed on 2024-01-15"
selectPaymentInstrumentUrlstring, (uri)read-only
URL for the customer to select a preferred payment instrument.
allocationsArray of objects(PayoutRequestAllocation)read-only
List of payout request allocations for the payout request.
selectedPaymentInstrumentRedirectUrlstring, (uri), <= 2083 characters

URL where the customer is redirected when a payment instrument is selected. The default value is the website URL. Use {{id}} as a placeholder for the payout request ID.

Example:"https://example.com/payout-request-success"
cancellationReasonobject or null(PayoutRequestCancellation)read-only
Reason the payout request is canceled.
createdTimestring, (date-time)(CreatedTime)read-only
Date and time when the payout request is created.
updatedTimestring, (date-time)(UpdatedTime)read-only
Date and time when the payout request is updated.
_linksArray of objectsread-only
Related links.
Response
{
  "id": "pout_req_0YVDMDE2BMC6KBB5MX76RF6T80",
  "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  "paymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N",
  "splitFromPayoutRequestId": "pout_req_0YVDMDE2BMC6KBB5MX76RF6T80",
  "mergedIntoPayoutRequestId": "pout_req_0YVDMDE2BMC6KBB5MX76RF6T80",
  "currency": "USD",
  "amount": 0.1,
  "availableAmount": 0.1,
  "description": "string",
  "status": "pending",
  "blocked": false,
  "blockReason": "fraud-suspected",
  "splitReason": "payment-instrument-limit",
  "batchId": "prb_0YVDMDE2BMC6KBB5MX76RF6T80",
  "batchName": "Weekly CAD payouts",
  "batchDescription": "Batch processed on 2024-01-15",
  "selectPaymentInstrumentUrl": "http://example.com",
  "allocations": [
    { … }
  ],
  "selectedPaymentInstrumentRedirectUrl": "https://example.com/payout-request-success",
  "cancellationReason": {
    "canceledBy": "merchant",
    "description": "string"
  },
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "_links": [
    { … }
  ]
}