# Payout requests

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

Customers create payout requests when they complete a [withdrawal form](/docs/dev-docs/integrate-a-withdrawal-form), when the [Create a payout request](/docs/dev-docs/api/transactions/postpayoutrequest/) API operation is called, or when a member of your organization creates a payout request on the customer's behalf.
To integrate payout requests using the Rebilly API, see [Hosted payout form API integration](/docs/dev-docs/hosted-payout-integration).
To integrate a cashier form with both deposit and withdrawal tabs, see [Integrate a cashier form](/docs/dev-docs/integrate-a-cashier-form).

To process payout requests, you must configure at least one gateway for payouts.
For more information, see [Configure a gateway to manage payout requests](/docs/settings/set-up-a-gateway#optionally,-configure-how-the-gateway-manages-payout-requests) and [Configure methods to display in withdrawal forms](/docs/settings/payout-method-configuration#configure-methods-to-display-in-withdrawal-forms).

## Payout request components

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.


## Payout request lifecycle

This section describes the lifecycle of a payout request.

### Payout request status

The following are all payout request status types.

| Status  | Description |
|  --- | --- |
| `pending`
 | A payout request is created and begins the pending period configured for the website. 
During the pending period, the customer can select a [payment instrument](/docs/dev-docs/payment-instruments).
New payout requests can be configured to begin in the `ready` status.
If the initial payout request state is not configured, the default status is `ready`.
For more information, see [Edit payout request settings](/docs/settings/organizations-and-websites#edit-payout-request-settings).
A member of your organization can skip the pending period and move the request to the `ready` status.
To skip the pending period and move the request to the `ready` status, select from the following:
- API: Use the [Update a payout request](/docs/dev-docs/api/transactions/patchpayoutrequest/) operation and set the `status` of the payout request to `ready`.
- UI: [Mark a payout request as ready](/docs/data-tables/manage-payout-requests#mark-a-payout-request-as-ready) in the Rebilly UI.

 |
| `ready` | The pending period ends, or a member of your organization skips the pending period, and the request is ready for approval.
When payout request status is `ready`, the customer can select a [payment instrument](/docs/dev-docs/payment-instruments) if one is not already assigned. |
| `approved` | A member of your organization approves the payout request. |
| `in-progress` | Funds are distributed across payment instruments and gateways, and processed as [allocations](#allocations). |
| `fulfilled` | Allocations have been processed, and the full payout amount has been paid out. |
| `canceled` | The request is canceled by a merchant, customer, or system.
Cancellation requires a `canceledBy` value of `customer`, `merchant`, or `system`. |
| `split` | A member of your organization splits the request 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, but `$3,000` can, split the request into two.
Process the `$3,000` request first and the `$1,000` request later instead of blocking the entire `$4,000` request. |
| `merged` | A member of your organization merges the request into another payout request. |


### Payout request created and fulfilled

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

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
graph LR;
    A(1 Pending) --> B(2 Ready)
    B --> C(3 Approved)
    C --> D(4 In-progress)
    D --> E(5 Fulfilled)
```

1. A payout request is created when a customer completes a [withdrawal form](/docs/dev-docs/integrate-a-withdrawal-form), when the [Create a payout request](/docs/dev-docs/api/transactions/postpayoutrequest/) API operation is called, or a member of your organization creates one on the customer's behalf.
Depending on which initial payout request state is configured, the payout request begins in one of the following states:
  - `pending`: The payout request enters the `pending` state for a configured period before it can be reviewed or approved by a member of your organization.
When the pending period ends, the payout request automatically transitions to the `ready` state.
  - `ready`: The payout request enters the `ready` state and can be reviewed and approved immediately by a member of your organization.
If the initial payout request state is not configured, the default status is `ready`.
To configure the initial state, see [Edit payout request settings](/docs/settings/organizations-and-websites#edit-payout-request-settings).
2. A member of your organization reviews the payout request and approves it.
The request transitions to `approved`.
3. A member of your organization allocates funds to payment instruments and processes them through the gateway.
The payout request transitions to `in-progress`.
4. Allocations are processed and the payout request transitions to `fulfilled`.


### Payout request canceled

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 [Update a payout request](/docs/dev-docs/api/transactions/patchpayoutrequest/) operation and set the `status` of the payout request to `canceled`.

**Example**: Payout request canceled by a member of your organization

**Example**: Payout request canceled by customer

### Payout request split

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.

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
graph LR;
    A(1 Pending 4000) --> B(2 Split)
    B --> C(3 Child 3000)
    B --> D(3 Child 1000)
```

The following example describes a payout request that is split from the `pending` status.
You can also split payout requests that are in the `ready` or `approved` status.

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 in the `pending` status for each amount.
Each child request has its own lifecycle.


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

```json
{
  "payoutRequestId": "pout_req_0YVDMDE2BMC6KBB5MX76RF6T80",
  "amounts": [3000.00, 1000.00],
  "splitReason": "processor-limit"
}
```

## Block a payout request

Blocking a payout request temporarily prevents transitions to `ready`, `approved`, `in-progress`, `merged`, `split`, and `canceled`.
It also prevents allocation creation, allocation processing, and cancellation of pending allocations.
For example, for suspected fraudulent activity, you can block a payout request to prevent it from being processed until the activity is investigated.

A blocked payout request can still transition to the `fulfilled` status if allocation processing starts before the payout request is blocked.

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](/docs/dev-docs/api/transactions/patchpayoutrequest/) 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

**Example**: Unblock a payout request

## Allocations

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.

During automatic allocation, payout limits on the gateway account apply to the allocated amount.
Manual allocations are not limited.
To configure payout limits in the Rebilly UI, see [Set payout limits](/docs/settings/manage-payment-gateways#set-payout-limits).
To configure payout limits using the API, use the [Update a gateway account](/catalog/all/gateway-accounts/patchgatewayaccount/) operation and the `payoutLimits` field.

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

| Status  | Description |
|  --- | --- |
| `pending` | Allocation is created and awaiting processing. |
| `queued` | Allocation is queued and waiting to be processed. |
| `processing` | Allocation is being processed, and a transaction is being created. |
| `completed` | Allocation is processed, and the gateway approves the transaction. |
| `failed` | An error prevents the allocation from being processed, and the allocation status is set to `failed`. |
| `canceled` | A member of your organization cancels the allocation before processing, and the allocation status is set to `canceled`. |
| `declined` | A gateway declines the allocation, and the allocation status is set to `declined`. |


Available operations:

- To manually allocate funds, use the [Create a payout request allocation](/docs/dev-docs/api/transactions/postpayoutrequestallocation/) operation.
- To automatically allocate funds, use the [Create automatic payout request allocations](/docs/dev-docs/api/transactions/postpayoutrequestautoallocations/) operation.
- To process a selected set of allocations, use the Create a payout request allocation operation and set `type` to `process`.
- To process the allocations in a batch, use the Create a payout request batch operation and set `type` to `process`.


## Batches

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

| Status | Description |
|  --- | --- |
| `pending` | Batch is pending processing. |
| `processing` | Batch is currently being processed. |
| `completed` | Batch processing is complete. |
| `failed` | Batch processing failed. |


Available operations:

- Create a payout request batch
- Update a payout request batch
- Create a payout request batch operation


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.

## Webhooks

Use webhooks to notify your systems when payout request events occur.
For more information, see [Webhooks](/docs/dev-docs/webhooks-configuration) and [Event types](/docs/automations/event-types).

## Related topics

- [Edit payout request settings](/docs/settings/organizations-and-websites#edit-payout-request-settings)
- [Cashier form integration](/docs/dev-docs/integrate-a-cashier-form)
- [Hosted payout form API integration](/docs/dev-docs/hosted-payout-integration)
- [Manage payout requests in the UI](/docs/data-tables/manage-payout-requests)
- [Payout method configuration](/docs/settings/payout-method-configuration)
- [Configure a gateway to manage payout requests](/docs/settings/set-up-a-gateway#optionally,-configure-how-the-gateway-manages-payout-requests)
- [Set payout limits](/docs/settings/manage-payment-gateways#set-payout-limits)
- [Payout requests API](/docs/dev-docs/api/transactions/)