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, when the Create a payout request 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. To integrate a cashier form with both deposit and withdrawal tabs, see Integrate a cashier form.

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 when a customer completes a withdrawal form, when the Create a payout request 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.

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.

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.

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

{
  "amounts": [
    50,
    30,
    20
  ],
  "splitReason": "payment-instrument-limit",
  "splitDescription": "string"
}

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.

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
• Cashier 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