Skip to main content

The Lifecycle of a Payout

A payout is the process of sending funds from a NextAPI account to an external bank account or e-wallet. This page explains every state a payout passes through.

Payout States​

INITIATED → PENDING → PROCESSING → COMPLETED
    ↓           ↓           ↓
  FAILED    CANCELLED    REVERSED

State Descriptions​

Initiated​

The payout request has been created and validated:

  • API request authenticated and parameters validated
  • Amount, recipient, and account confirmed
  • Idempotency key recorded
  • Reference ID generated
{
  "id": "pr_abc123",
  "status": "initiated",
  "amount": 10000,
  "currency": "PHP",
  "created_at": "2024-01-15T10:00:00Z"
}

Pending​

The payout is queued for processing:

  • Funds reserved from the source account (available decreases, reserved increases)
  • Recipient validation initiated
  • Queued for the appropriate payment rail

Processing​

Active payment processing via the selected rail:

  • Sent to payment provider (one of NextAPI's 3 partner financial institutions)
  • Bank or e-wallet transfer initiated
  • For amounts under PHP 50,000: routed via InstaPay (real-time)
  • For larger amounts: routed via PESONet (batch, same-day)

Completed​

Payout successfully delivered:

  • Funds received by the recipient
  • Account reserved balance decreases permanently
  • Confirmation from the payment provider received
  • Receipt available via GET /v2/payouts/{id}/receipt

Exception States​

Failed​

The payout could not be completed. Common reasons:

  • Insufficient available balance
  • Invalid recipient bank details
  • Payment rail network issues
  • Recipient account closed or frozen

On failure, reserved funds return to available balance.

Cancelled​

The payout was cancelled before processing began:

  • Cancelled via API or by the system
  • Funds return from reserved to available

Reversed​

A completed payout was reversed after delivery:

  • Recipient account issues
  • Compliance requirements
  • Bank-initiated return

Timeline and SLAs​

TransitionTypical DurationMaximum
Initiated → Pending< 1 second5 seconds
Pending → Processing1-5 minutes30 minutes
Processing → Completed (InstaPay)5-30 seconds5 minutes
Processing → Completed (PESONet)1-4 hours24 hours

Webhook Events​

Each state transition emits a webhook event. Configure webhooks to receive real-time updates:

  • payout_request.initiated
  • payout_request.pending
  • payout_request.processing
  • payout_request.completed
  • payout_request.failed
  • payout_request.cancelled
  • payout_request.reversed

See Understanding Webhooks for payload structure and delivery details.