/
Create a payout request

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

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

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 whether the payout request is blocked or unblocked.

When blocked, the payout request cannot transition to ready, approved, in-progress, merged, split, or canceled. Allocation creation, allocation processing, and cancellation of pending allocations are also prevented. A blocked payout request can still transition to the fulfilled status if allocation processing starts before the payout request is blocked.

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"
X-RateLimit-Limitinteger

Total number of rate limit tokens for this request within a rate limit period. For more information, see Rate limits.

Example:3600
X-RateLimit-Remaininginteger

Remaining number of rate limit tokens for this request within the rate limit period. For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.

Example:3600
Bodyapplication/json
idstring, <= 50 charactersread-only

Unique resource ID.

Example:"pout_req_0YVDMDE2BMC6KBB5MX76RF6T80"
websiteIdstring, <= 50 characters(WebsiteId)required

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

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 whether the payout request is blocked or unblocked.

When blocked, the payout request cannot transition to ready, approved, in-progress, merged, split, or canceled. Allocation creation, allocation processing, and cancellation of pending allocations are also prevented. A blocked payout request can still transition to the fulfilled status if allocation processing starts before the payout request is blocked.

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:"preq_batch_0YVDMDE2BMC6KBB5MX76RF6T80"
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.

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": "preq_batch_0YVDMDE2BMC6KBB5MX76RF6T80",
  "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": [
    { … }
  ]
}