OPay: complete surface reference

// Pseudocode — production code is split across services
async function handleChargeSuccessful(webhook: OPayWebhookBody) {
  // 1. Signature verification has already passed (middleware)
  // 2. Idempotency check has already passed (unique on event_id)

  // 3. Re-verify against OPay's authoritative endpoint
  const verification = await opayClient.verifyTransaction(webhook.reference);

  // 4. Status must match success
  if (!/success/i.test(verification.status)) {
    audit.write({ kind: 'webhook_rejected_status_mismatch', ...webhook });
    return; // We acknowledge the webhook but do not credit
  }

  // 5. Amount must match to the kobo
  if (BigInt(verification.amount_kobo) !== BigInt(webhook.amount_kobo)) {
    audit.write({ kind: 'webhook_rejected_amount_mismatch', ...webhook });
    return;
  }

  // 6. All checks passed. Credit the wallet atomically with the audit row.
  await db.transaction(async (tx) => {
    await tx.walletLedger.credit({
      userId: resolveOwner(webhook),
      amountKobo: webhook.amount_kobo,
      sourceRef: webhook.reference
    });
    await tx.audit.append({
      kind: 'wallet_credit',
      reference: webhook.reference,
      amount: webhook.amount_kobo,
      verifiedAt: new Date()
    });
  });
}

const STATUS_LOOKUP: Record<string, DirectChargeNextStep> = {
  validate_otp: 'OTP_REQUIRED',
  ValidateOtp:  'OTP_REQUIRED',
  VALIDATEOTP:  'OTP_REQUIRED',
  validate_pin: 'PIN_REQUIRED',
  ValidatePin:  'PIN_REQUIRED',
  // ... etc
};

try {
  await opayClient.requestPayout({ ... });
} catch (e) {
  if (e instanceof OPayError && e.kind === 'TRANSIENT') {
    await scheduler.scheduleRetry(idempotencyKey);
  } else {
    // PERMANENT — surface to user, do not retry
    await notifyUser({ kind: 'payout_failed', reason: e.message });
  }
}