/
Request a payout request...

Request a payout request split
Experimental

Request

Splits a payout request that is in pending, ready, or approved status into two or more separate requests.

Use this operation when the full amount cannot be processed due to amount restrictions, but a smaller amount can be processed. For example, if a payout request for $4,000 cannot be processed, but $3,000 can be processed, split the request into two. This allows you to approve and process $3,000 instead of blocking the entire request.

Provide an array of at least two amounts; one new payout request is created per amount. The sum of the amounts must equal the original payout request amount. Each new payout request is created in pending status. The original request transitions to the split status. This operation returns the newly created payout requests.

Security
SecretApiKey or JWT
Path
idstring, <= 50 characters^[@~\-\.\w]+$required

ID of the resource.

Bodyapplication/jsonrequired

Payout request split parameters.

amountsArray of numbers, [ 2 .. 100 ] itemsrequired

Amounts for each new payout request. One request is created per amount. Provide at least two amounts. Each amount must be greater than zero. The sum must equal the original payout request amount.

Example:
[
  50,
  30,
  20
]
splitReasonstring(PayoutRequestSplitReason)required

Reason for splitting the payout request.

Enum:"payment-instrument-limit""processor-limit""risk-review""compliance-review""partial-processing""operational-reconciliation""other"
splitDescriptionstring or null, <= 255 characters

Additional description for splitting the payout request.

curl -i -X POST \
  'https://www.rebilly.com/_mock/catalog/all/payout-requests/{id}/split' \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "amounts": [
      50,
      30,
      20
    ],
    "splitReason": "payment-instrument-limit",
    "splitDescription": "string"
  }'

Responses

Payout requests created by the split operation.

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
Array [
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": { … },
    "createdTime": "2019-08-24T14:15:22Z",
    "updatedTime": "2019-08-24T14:15:22Z",
    "_links": [ … ]
  }
]