The Lifecycle of a Payout

Understanding the complete journey of a payout from initiation to completion, including all intermediate states and possible outcomes.

Payout States

A payout progresses through several distinct states:

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

Detailed Lifecycle

1. Initiation

State: initiated

The payout request is created and validated:

• API request received and authenticated
• Parameters validated (amount, recipient, etc.)
• Initial record created in system
• Reference ID generated

{
  "id": "payout_123",
  "status": "initiated",
  "amount": 10000,
  "currency": "PHP",
  "created_at": "2024-01-15T10:00:00Z"
}

2. Pending

State: pending

The payout is queued for processing:

• Funds reserved from wallet
• Recipient validation initiated
• Risk assessment performed
• Queued for payment processor

3. Processing

State: processing

Active payment processing:

• Sent to payment gateway
• Bank/wallet transfer initiated
• Real-time status updates
• Estimated completion time provided

4. Completed

State: completed

Payout successfully delivered:

• Funds transferred to recipient
• Wallet debited permanently
• Confirmation received
• Receipt generated

Exception States

Failed

State: failed

Payout could not be completed:

• Insufficient funds
• Invalid recipient details
• Network/gateway errors
• Regulatory blocks

Cancelled

State: cancelled

Payout cancelled before processing:

• User requested cancellation
• System detected issues
• Timeout during pending state

Reversed

State: reversed

Completed payout reversed:

• Recipient account issues
• Fraud detection
• Compliance requirements
• Bank chargebacks

Timeline and SLAs

State	Typical Duration	Maximum Duration
Initiated → Pending	< 1 second	5 seconds
Pending → Processing	1-5 minutes	30 minutes
Processing → Completed	5-30 minutes	24 hours
Failed notifications	< 1 second	5 seconds

Webhook Events

Receive real-time updates for state changes:

// Payout initiated
{
  "event": "payout.initiated",
  "data": { "payout_id": "payout_123", "status": "initiated" }
}

// Payout completed
{
  "event": "payout.completed",
  "data": { "payout_id": "payout_123", "status": "completed" }
}

// Payout failed
{
  "event": "payout.failed",
  "data": { 
    "payout_id": "payout_123", 
    "status": "failed",
    "error_code": "INSUFFICIENT_FUNDS"
  }
}

Monitoring and Tracking

Status Polling

GET /v1/payouts/{payout_id}

Batch Status Check

GET /v1/payouts?status=processing&limit=50

Real-time Updates

• Configure webhooks for instant notifications
• Use WebSocket connections for live updates
• Implement status dashboards

Error Handling

Common failure scenarios and resolutions:

1. Insufficient Funds: Top up wallet or reduce amount
2. Invalid Recipient: Verify recipient details
3. Network Issues: Implement retry logic
4. Compliance Blocks: Contact support team

Best Practices

1. Track Reference IDs: Maintain your own reference mapping
2. Implement Timeouts: Handle processing delays gracefully
3. Monitor Failures: Set up alerts for failed payouts
4. Handle Reversals: Account for potential reversals
5. Keep Records: Store payout lifecycle data for auditing

Related Concepts

• [Understanding Webhooks](./understanding-webhooks
• [IDs, Reference IDs, and Idempotency](./ids-reference-ids-idempotency
• [Handle Payout Failures & Retries](../guides/how-to/handle-payout-failures-retries