GET /api/v1/payouts/:id

Authorization: Bearer <access_token>

{
  "id": "pyt_xyz789abc",
  "reference_id": "PAY_2024_001",
  "status": "completed",
  "amount": 100.00,
  "currency": "USD",
  "fees": 1.50,
  "total_amount": 101.50,
  "beneficiary": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "phone": "+1234567890"
  },
  "description": "Q1 2024 Bonus Payment",
  "created_at": "2024-01-15T10:30:00Z",
  "queued_at": "2024-01-15T10:30:01Z",
  "submitted_at": "2024-01-15T10:31:00Z",
  "completed_at": "2024-01-15T10:35:00Z",
  "failed_at": null,
  "cancelled_at": null
}

{
  "id": "pyt_failed123",
  "reference_id": "PAY_2024_FAIL",
  "status": "failed",
  "amount": 100.00,
  "currency": "USD",
  "fees": 1.50,
  "total_amount": 101.50,
  "failure_code": "INVALID_ACCOUNT",
  "failure_reason": "The beneficiary account number is invalid or closed",
  "beneficiary": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "failed_at": "2024-01-15T10:32:00Z"
}

{
  "error": "BadRequest",
  "message": "Payout ID is required"
}

{
  "error": "NotFound",
  "message": "Payout not found"
}

{
  "error": "UnauthorizedAccess",
  "message": "Authentication required"
}

async function waitForPayoutCompletion(payoutId, maxWaitMs = 300000) {
    const startTime = Date.now();
    const pollInterval = 5000; // 5 seconds

    while (Date.now() - startTime < maxWaitMs) {
        const response = await fetch(`/api/v1/payouts/${payoutId}`, {
            headers: {
                'Authorization': `Bearer ${getAccessToken()}`
            }
        });

        const payout = await response.json();

        // Check for terminal states
        if (['completed', 'failed', 'cancelled', 'expired'].includes(payout.status)) {
            return payout;
        }

        // Log current status
        console.log(`Payout ${payoutId} status: ${payout.status}`);

        // Wait before next poll
        await new Promise(resolve => setTimeout(resolve, pollInterval));
    }

    throw new Error(`Timeout waiting for payout ${payoutId}`);
}

// Usage
try {
    const payout = await waitForPayoutCompletion('pyt_xyz789abc');

    if (payout.status === 'completed') {
        console.log('Payout completed successfully!');
    } else if (payout.status === 'failed') {
        console.log(`Payout failed: ${payout.failure_reason}`);
    }
} catch (error) {
    console.error('Error:', error.message);
}

function displayPayoutTimeline(payout) {
    console.log(`Payout ${payout.id} Timeline:`);
    console.log('─'.repeat(50));

    const milestones = [
        { label: 'Created', time: payout.created_at },
        { label: 'Queued', time: payout.queued_at },
        { label: 'Submitted', time: payout.submitted_at },
        { label: 'Completed', time: payout.completed_at },
        { label: 'Failed', time: payout.failed_at },
        { label: 'Cancelled', time: payout.cancelled_at }
    ];

    milestones.forEach(({ label, time }) => {
        if (time) {
            const date = new Date(time);
            console.log(`  ${label}: ${date.toLocaleString()}`);
        }
    });

    console.log('─'.repeat(50));
    console.log(`Current Status: ${payout.status}`);
}

// Usage
const payout = await getPayout('pyt_xyz789abc');
displayPayoutTimeline(payout);

<?php
function handlePayoutStatus($payout) {
    switch ($payout['status']) {
        case 'created':
        case 'queued':
            return [
                'action' => 'wait',
                'message' => 'Payout is being processed'
            ];

        case 'processing':
            return [
                'action' => 'wait',
                'message' => 'Payout submitted to payment provider'
            ];

        case 'settling':
            return [
                'action' => 'wait',
                'message' => 'Funds are being settled to beneficiary'
            ];

        case 'action_required':
            return [
                'action' => 'review',
                'message' => 'Additional action required - check event details'
            ];

        case 'completed':
            return [
                'action' => 'done',
                'message' => 'Payout delivered successfully',
                'completed_at' => $payout['completed_at']
            ];

        case 'failed':
            return [
                'action' => 'retry_or_refund',
                'message' => $payout['failure_reason'],
                'code' => $payout['failure_code']
            ];

        case 'cancelled':
            return [
                'action' => 'none',
                'message' => 'Payout was cancelled',
                'cancelled_at' => $payout['cancelled_at']
            ];

        case 'expired':
            return [
                'action' => 'recreate',
                'message' => 'Payout expired - create a new one'
            ];

        default:
            return [
                'action' => 'unknown',
                'message' => 'Unknown status: ' . $payout['status']
            ];
    }
}
?>

function getStatusDisplay(payout) {
    const statusConfig = {
        created: { icon: '⏳', text: 'Processing', color: 'blue' },
        queued: { icon: '⏳', text: 'Processing', color: 'blue' },
        processing: { icon: '🔄', text: 'In Progress', color: 'blue' },
        settling: { icon: '🔄', text: 'Settling', color: 'blue' },
        action_required: { icon: '⚠️', text: 'Action Required', color: 'yellow' },
        completed: { icon: '✅', text: 'Completed', color: 'green' },
        failed: { icon: '❌', text: 'Failed', color: 'red' },
        cancelled: { icon: '🚫', text: 'Cancelled', color: 'gray' },
        expired: { icon: '⏰', text: 'Expired', color: 'gray' }
    };

    return statusConfig[payout.status] || { icon: '❓', text: 'Unknown', color: 'gray' };
}

function generateAuditReport(payout) {
    return {
        payout_id: payout.id,
        reference_id: payout.reference_id,
        amount: `${payout.amount} ${payout.currency}`,
        fees: payout.fees,
        total_deducted: payout.total_amount,
        beneficiary: {
            name: `${payout.beneficiary.first_name} ${payout.beneficiary.last_name}`,
            email: payout.beneficiary.email,
            country: payout.beneficiary.country
        },
        timestamps: {
            created: payout.created_at,
            queued: payout.queued_at,
            submitted: payout.submitted_at,
            completed: payout.completed_at,
            failed: payout.failed_at,
            cancelled: payout.cancelled_at
        },
        final_status: payout.status,
        failure_info: payout.failure_code ? {
            code: payout.failure_code,
            reason: payout.failure_reason
        } : null,
        total_processing_time: calculateProcessingTime(payout)
    };
}

function calculateProcessingTime(payout) {
    const start = new Date(payout.created_at);
    const end = new Date(
        payout.completed_at ||
        payout.failed_at ||
        payout.cancelled_at ||
        new Date()
    );
    return `${Math.round((end - start) / 1000)} seconds`;
}