Update a payout request
Experimental

Request

Updates a payout request with a specified ID. Use this operation to update the status, description, and blocked state.
Security
SecretApiKey or JWT
Path
idstring, <= 50 characters^[@~\-\.\w]+$required
ID of the resource.
Bodyapplication/json
Fields for updating the payout request status, description, and blocked state.
statusstring
Status of the request.
Enum ValueDescription
pending
Request was created by the customer.
ready
Request was assessed, deemed eligible for processing and is ready for approval.
approved
Request was approved and is ready for processing.
canceled

Request is canceled. This status requires the canceledBy field.

canceledBystring

Initiator of the cancellation. Required when status is canceled.

Enum:"customer""merchant""system"
cancellationDescriptionstring or null, [ 1 .. 255 ] characters

Description of the cancellation reason. When a blocked payout request is canceled, the block reason is added to this description. For example, Fraud confirmed becomes Fraud confirmed (blocked: fraud-suspected). If this field is omitted, the description is the block reason only, such as blocked: fraud-suspected. If the combined text is longer than 255 characters, the text before the block reason is shortened to fit.

descriptionstring or null
Description of the payout request.
blockedboolean

Specifies if the payout request is blocked or unblocked. This field can only be applied to payout requests in the following statuses: pending, ready, approved, or in-progress.

When a payout request is blocked, it cannot:

  • Transition to ready, approved, in-progress, merged, or split.
  • Have allocations created.
  • Start allocation processing.

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 cancellationDescription. 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"
blockDescriptionstring or null, <= 255 characters
Additional description for blocking the payout request.
curl -i -X PATCH \
  'https://www.rebilly.com/_mock/catalog/all/payout-requests/{id}' \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "status": "pending",
    "canceledBy": "customer",
    "cancellationDescription": "string",
    "description": "string",
    "blocked": false,
    "blockReason": "fraud-suspected",
    "blockDescription": "string"
  }'

Responses

Payout request updated.
Headers
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": [
    { … }
  ]
}