# 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](/docs/dev-docs/hosted-payout-integration).
To integrate a Rebilly payout form into your website, see [Payout form integration](/docs/dev-docs/integrate-a-payout-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 payout methods displayed in payout forms](/docs/settings/payout-method-configuration#configure-methods-to-display-in-a-payout-form).

## 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). 
When the pending period is set to `0` hours, payout requests transition to `ready`. 
It can take up to five minutes to transition to `ready`. 
To set the pending period, see [Edit payout request settings](/docs/settings/organizations-and-websites#edit-payout-request-settings).
If the pending period length is not set, payout requests for that website must be manually marked as ready.
For more information, see [Mark payout requests in a batch as ready](/docs/data-tables/manage-payout-requests#mark-payout-requests-in-a-batch-as-ready) and [Mark a payout request as ready](/docs/data-tables/manage-payout-requests#mark-a-payout-request-as-ready).
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. |
| `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 and assigned the `pending` status.
The customer adds a payment instrument to the payout request in a [payout form](/docs/dev-docs/hosted-payout-integration).
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](/docs/settings/organizations-and-websites#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](/docs/data-tables/manage-payout-requests#mark-payout-requests-in-a-batch-as-ready) and [Mark a payout request as ready](/docs/data-tables/manage-payout-requests#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`.


### 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 [Cancel a payout request](/docs/dev-docs/api/transactions/postpayoutrequestcancellation/) operation.

**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)
```

1. A payout request is in the `pending` status for `$4,000`.
2. Using the [Split a payout request](/docs/dev-docs/api/transactions/postpayoutrequestsplit/) 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

## Block a payout request

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](/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.

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 an automatic payout request allocation](/docs/dev-docs/api/transactions/postpayoutrequestautoallocation/) operation.
- To process allocations, use the [Initiate processing of allocations](/docs/dev-docs/api/transactions/postpayoutrequestallocationsprocess/) operation.


## 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](/docs/dev-docs/api/transactions/postpayoutrequestbatch/)
- [Update a payout request batch](/docs/dev-docs/api/transactions/patchpayoutrequestbatch/)
- [Approve a payout request batch](/docs/dev-docs/api/transactions/postpayoutrequestbatchapprove/)
- [Auto allocate a payout request batch](/docs/dev-docs/api/transactions/postpayoutrequestbatchautoallocate/)
- [Block a payout request batch](/docs/dev-docs/api/transactions/postpayoutrequestbatchblock/)


To set the saved payout method priority for a batch through the API, use the [Update a payout request batch](/docs/dev-docs/api/transactions/patchpayoutrequestbatch/) 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)
- [Payout form integration](/docs/dev-docs/integrate-a-payout-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)
- [Payout requests API](/docs/dev-docs/api/transactions/)