System Design Interview: Design a Payout System

Finance Team / Automated Trigger
          |
          | POST /payouts/request
          v
Payout Request Service
   - Creates payout record: { id, recipient_code, amount, status: 'pending', created_by, created_at }
   - Inserts into payout_requests table
          |
          | (amount > threshold → approval required)
          v
Approval Service
   - Sends notification to approver(s)
   - Approver 1 approves → status: 'pending_second_approval'
   - Approver 2 approves → status: 'approved'
   - Either rejects → status: 'rejected', notify requester
          |
          | (status = 'approved')
          v
Transfer Dispatcher
   - Checks Paystack balance (GET /balance)
   - Calls POST /transfer with idempotency key = payout_id
   - Updates status: 'transfer_initiated', stores transfer_code
   - Returns transfer_code to audit log
          |
          | (async)
          v
Status Resolver (webhook OR polling fallback)
   - transfer.success → status: 'completed'
   - transfer.failed → status: 'failed', trigger retry or escalate
   - No webhook in 24h → poll GET /transfer/:code

Never call POST /transfer twice for the same payout request. Use your payout_id as the idempotency key:

async function dispatchTransfer(payoutRequest) {
  // Check if we already initiated a transfer for this payout
  if (payoutRequest.transfer_code) {
    // Already dispatched — check status, do not re-dispatch
    return await getTransferStatus(payoutRequest.transfer_code);
  }

  var res = await fetch('https://api.paystack.co/transfer', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: 'balance',
      amount: payoutRequest.amount,
      recipient: payoutRequest.recipient_code,
      reason: payoutRequest.reason,
      reference: 'payout_' + payoutRequest.id, // unique per payout
    }),
  });

  var data = await res.json();
  // Store transfer_code before returning — if we crash here, the payout_request still has the code
  await db.payoutRequests.update(payoutRequest.id, { transfer_code: data.data.transfer_code, status: 'transfer_initiated' });
  return data.data;
}

• Insufficient balance — check GET /balance before dispatching. Queue the transfer for when balance is sufficient, or alert finance team. Never retry blindly on insufficient balance errors.
• Bank account invalid — transfer.failed with gateway_response "Invalid Account Number". Do not retry. Alert the requester to verify recipient details.
• Network timeout during POST /transfer — you don't know if Paystack received the request. Check the payout_requests table: if transfer_code is null, you can safely retry (Paystack deduplicates on reference). If transfer_code is set, poll GET /transfer/:code for status.
• transfer.success webhook never arrives — poll GET /transfer/:code after 24 hours. If status is "success", update DB. If still "pending", escalate to Paystack support.

See system design: payment service for the payment collection version.

Sign up for the McTaba newsletter