Payout requests

A payout request is a customer request to withdraw funds. This topic describes the payout request resource and its lifecycle.

Customers request payouts using a payout form. To integrate a Rebilly payout form into your website, see Payout form integration.

A payout request contains the following:

• Customer: Customer who is requesting a payout.
• Amount and currency: Requested payout amount and currency.
• Payment instrument: Payment instrument that the customer selects or adds as the suggested instrument for payout. Payout allocations are not limited to this instrument and can be applied to any instrument the customer has available for payouts.
• Allocations: How the payout amount is split across payment instruments and gateways.

This section describes the lifecycle of a payout request.

The following are all payout request status types.

This section describes the lifecycle for a payout request that is approved and fully paid out.

1. A payout request is created and assigned the pending status. The customer adds a payment instrument to the payout request in a payout form.

2. The pending period ends, or a member of your organization skips the pending period by marking the payout request as ready. The payout request is assigned the ready status. To set the pending period length, see Edit payout request settings.

   If the pending period length is not set for the website, payout requests remain in the pending state until they are manually marked as ready. For more information, see Mark payout requests in a batch as ready and Mark a payout request as ready.

3. A member of your organization reviews the payout request and approves it. The request transitions to approved.

4. A member of your organization allocates funds to payment instruments and processes them through the gateway. The payout request transitions to in-progress.

5. Allocations are processed and the payout request transitions to fulfilled.

This section describes the lifecycle for a payout request that is canceled. A payout request can be canceled from the pending, ready, or approved status.

Cancellation requires a canceledBy value that identifies who initiated the cancellation:

• merchant: A member of your organization cancels the request.
• customer: The customer cancels the request.
• system: The system cancels the request automatically.

To cancel a payout request, use the Cancel a payout request operation.

Example: Payout request canceled by a member of your organization

{
  "canceledBy": "merchant",
  "description": "string"
}

Example: Payout request canceled by customer

{
  "canceledBy": "merchant",
  "description": "string"
}

This section describes the lifecycle for a payout request that is split. A split payout request is a payout that is split into two or more child payout requests.

Payout requests are split when the full amount cannot be processed because of amount restrictions, but a smaller amount can be processed.

For example, if a payout request for $4,000 cannot be processed in full but $3,000 can, split the request into two child requests for $3,000 and $1,000. Process the $3,000 request first and the $1,000 request later instead of blocking the entire $4,000 request.

The parent request transitions to the split status, and each child request follows its own lifecycle. The combined amount of the child requests must equal the parent payout amount.

1. A payout request is in the pending status for $4,000.
2. Using the Split a payout request operation, a member of your organization splits the payout request into two child requests with amounts of $3,000 and $1,000.
3. The payout request transitions to split, and a child payout request is created for each amount. Each child request has its own lifecycle.

Example: Split a $4,000 payout request into two child requests

{
  "amounts": [
    50,
    30,
    20
  ]
}

Blocking a payout request temporarily stops status transitions and allocation operations. For example, for suspected fraudulent activity, you can block a payout request to prevent it from being processed until the activity is investigated.

This action is available for payout requests in the pending, ready, approved, or in-progress status.

To block or unblock a payout request, use the Update a payout request operation and set blocked to true or false. When blocking, provide a blockReason and optionally a blockDescription.

Example: Block a payout request due to suspected fraudulent activity

{
  "status": "pending",
  "canceledBy": "customer",
  "cancellationDescription": "string",
  "description": "string",
  "blocked": false,
  "blockReason": "fraud-suspected",
  "blockDescription": "string"
}

Example: Unblock a payout request

{
  "status": "pending",
  "canceledBy": "customer",
  "cancellationDescription": "string",
  "description": "string",
  "blocked": false,
  "blockReason": "fraud-suspected",
  "blockDescription": "string"
}

Allocations define how the payout amount is distributed across payment instruments and gateways. After a member of your organization approves a payout request, you can create allocations manually or automatically.

Each allocation has a status that tracks the progress of the allocation operation:

Available operations:

• To manually allocate funds, use the Create a payout request allocation operation.
• To automatically allocate funds, use the Create an automatic payout request allocation operation.
• To process allocations, use the Initiate processing of allocations operation.

Use batches to group payout requests and perform bulk actions. Each batch has a status that tracks the progress of the batch operation:

Available operations:

• Create a payout request batch
• Update a payout request batch
• Approve a payout request batch
• Auto allocate a payout request batch
• Block a payout request batch

To set the saved payout method priority for a batch through the API, use the Update a payout request batch operation and the allocationOrder field.

Use webhooks to notify your systems when payout request events occur. For more information, see Webhooks and Event types.

• Edit payout request settings
• Payout form integration
• Hosted payout form API integration
• Manage payout requests in the UI
• Payout method configuration
• Configure a gateway to manage payout requests
• Payout requests API