Build a Referral Payout System

Tables: users (id, email, referral_code, referred_by, pending_balance, paid_balance), referrals (referrer_id, referred_id, status, commission_amount, paid_at), withdrawals (user_id, amount, status, paystack_transfer_ref, requested_at).

// Generate unique referral code on signup
function generateReferralCode(userId) {
  return 'REF-' + userId.toString(36).toUpperCase() + '-' + Math.random().toString(36).slice(2, 6).toUpperCase();
}

// When a referred user registers
async function handleReferralSignup(newUserId, referralCode) {
  var referrer = await db.users.findByReferralCode(referralCode);
  if (!referrer) return;

  await db.referrals.create({
    referrer_id: referrer.id,
    referred_id: newUserId,
    status: 'signed_up', // only credits commission after first payment
  });
  await db.users.update(newUserId, { referred_by: referrer.id });
}

// Webhook: when referred user makes their first payment, credit commission
if (event.event === 'charge.success') {
  var payingUserId = event.data.metadata.user_id;
  var referral = await db.referrals.findPendingByReferredId(payingUserId);

  if (referral && referral.status === 'signed_up') {
    var commission = Math.floor(event.data.amount * 0.1); // 10% commission

    await db.referrals.update(referral.id, { status: 'converted', commission_amount: commission });
    await db.users.increment(referral.referrer_id, 'pending_balance', commission);
    await notifyReferrer(referral.referrer_id, commission);
  }
}

async function requestWithdrawal(userId, amount, bankDetails) {
  var user = await db.users.findById(userId);
  var minWithdrawal = 500000; // NGN 5,000 in kobo

  if (amount < minWithdrawal) throw new Error('Minimum withdrawal is NGN 5,000');
  if (amount > user.pending_balance) throw new Error('Insufficient balance');

  // Register recipient if not already done
  if (!user.paystack_recipient_code) {
    var recRes = await fetch('https://api.paystack.co/transferrecipient', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ type: 'nuban', name: bankDetails.name, account_number: bankDetails.account, bank_code: bankDetails.bank_code, currency: 'NGN' }),
    });
    var recData = await recRes.json();
    await db.users.update(userId, { paystack_recipient_code: recData.data.recipient_code });
    user.paystack_recipient_code = recData.data.recipient_code;
  }

  // Deduct from balance immediately (prevent double withdrawal)
  await db.users.decrement(userId, 'pending_balance', amount);

  // Initiate transfer
  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, recipient: user.paystack_recipient_code, reason: 'Referral payout' }),
  });
  var transfer = await res.json();

  await db.withdrawals.create({ user_id: userId, amount, status: 'processing', paystack_transfer_ref: transfer.data.reference });
}

// Webhook: handle transfer outcome
if (event.event === 'transfer.success') {
  await db.withdrawals.update({ ref: event.data.reference }, { status: 'completed' });
  await db.users.increment(event.data.metadata.user_id, 'paid_balance', event.data.amount);
}
if (event.event === 'transfer.failed') {
  // Restore balance on failure
  await db.users.increment(event.data.metadata.user_id, 'pending_balance', event.data.amount);
  await db.withdrawals.update({ ref: event.data.reference }, { status: 'failed' });
  await notifyUserOfFailedWithdrawal(event.data.metadata.user_id);
}

See build an affiliate commission engine for a more detailed affiliate tracking system with conversion attribution.

Sign up for the McTaba newsletter