Payout requests

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

A payout request is created 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.

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 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 Update a payout request operation and set the status of the payout request to canceled.

Example: Payout request canceled by a member of your organization

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

Example: Payout request canceled by customer

{
  "status": "pending",
  "canceledBy": "customer",
  "cancellationDescription": "string",
  "description": "string",
  "blocked": false,
  "blockReason": "fraud-suspected",
  "blockDescription": "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.

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. To configure payout limits using the API, use the Update a gateway account operation and the payoutLimits field.

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 automatic payout request allocations operation.

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

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