Round six: “connect to the outside world”

interface PaymentConnector {
  readonly id: string;                 // 'nibss' | 'paystack' | 'sepa' ...
  readonly capabilities: Capability[];  // push | pull | mandate | instant

  // validate BEFORE any money moves. cheap, no side effects.
  validate(d: Destination): Promise<ValidationResult>;

  // resolve a destination to a human name, for confirmation screens.
  resolve(d: Destination): Promise<{ accountName: string } | null>;

  // the only method that moves money. MUST be idempotent on our reference.
  dispatch(p: OutboundPayment): Promise<DispatchResult>;

  // the answer to "did that actually happen?". the unknown-state resolver.
  query(ourReference: string): Promise<PaymentStatus>;

  // parse and VERIFY an inbound callback. returns null if unauthentic.
  parseWebhook(raw: Buffer, headers: Headers): InboundEvent | null;
}

// the result type that makes the hard case explicit in the type system
type DispatchResult =
  | { state: 'accepted';  providerRef: string }
  | { state: 'rejected';  reason: string; retryable: boolean }
  | { state: 'unknown';   detail: string };   // ← the one that matters

// 1. name enquiry. cheap, read-only, no money at risk.
const ne = await nibss.resolve({ nuban: '0123456789', bankCode: '058' });
//    → { accountName: 'ADENIJI OLUWAFERANMI' }

// 2. the customer SEES the name and confirms. this is a product
//    requirement, not a nicety: it is the last chance to catch an error
//    on a rail with no reversal.

// 3. transfer, carrying the name-enquiry session so NIBSS can correlate
const r = await nibss.dispatch({
  ourReference: journalId,       // our idempotency key, end to end
  sessionId: ne.sessionId,
  amount: 50000n, currency: 'NGN',
  beneficiary: { nuban: '0123456789', bankCode: '058', name: ne.accountName }
});

// IBAN check: move the first 4 chars to the end, map letters to numbers,
// then the whole thing mod 97 must equal 1. no network call needed.
function validIban(iban: string): boolean {
  const s = iban.replace(/\s/g, '').toUpperCase();
  if (!/^[A-Z]{2}[0-9]{2}[A-Z0-9]{,30}$/.test(s)) return false;
  const re = s.slice(4) + s.slice(0, 4);
  const num = [...re].map(c =>
    /[A-Z]/.test(c) ? (c.charCodeAt(0) - 55).toString() : c).join('');
  // the number is far bigger than a float, so reduce in chunks
  let r = 0;
  for (const d of num) r = (r * 10 + +d) % 97;
  return r === 1;
}

BEGIN;
  INSERT INTO journal (id, kind, idempotency_key)
       VALUES ($jid, 'payout.initiated', $clientKey);

  -- debit the customer, checked against their available balance
  INSERT INTO entries ... ($wallet,             -50000);
  -- credit a per-rail settlement suspense account
  INSERT INTO entries ... ('settle_suspense:nibss', +50000);

  -- the dispatch intent, committed with the money. no dual write.
  INSERT INTO outbox (event_type, payload)
       VALUES ('payout.dispatch.requested', $payload);
COMMIT;
-- ledger sums to zero. money is in a named account. nothing external yet.

async function dispatch(p: OutboundPayment) {
  // our journal id IS the idempotency key, end to end. a retry of this
  // call, or a duplicate outbox delivery, cannot double-send.
  const r = await connector.dispatch({ ...p, ourReference: p.journalId });

  switch (r.state) {
    case 'accepted':
      // NOT settled. just accepted. record the provider ref and wait.
      return markAwaitingConfirmation(p, r.providerRef);

    case 'rejected':
      // authoritative no. safe to compensate immediately.
      return compensate(p, r.reason);

    case 'unknown':
      // DO NOT compensate. DO NOT retry the dispatch.
      // the money stays in suspense and the resolver takes over.
      return scheduleStatusQuery(p);
  }
}

function verify(raw: Buffer, sig: string, ts: string, secret: string): boolean {
  // bound replay: reject anything older than 5 minutes
  if (Math.abs(Date.now() / 1000 - +ts) > 300) return false;

  // sign the timestamp WITH the body, so a captured signature cannot be
  // replayed later against a different timestamp header.
  const expected = hmacSha512(`${ts}.` + raw, secret);

  // constant time: a fast-failing comparison leaks the correct prefix
  // and lets an attacker forge a signature byte by byte.
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

-- the poller's work queue: anything non-terminal, oldest first,
-- with backoff so a stuck payment is not queried every second forever.
SELECT * FROM outbound_payments
 WHERE state IN ('awaiting_confirmation', 'unknown')
   AND next_query_at <= now()
 ORDER BY next_query_at
 LIMIT 200
 FOR UPDATE SKIP LOCKED;   -- many pollers, disjoint work

// bulkheads: a bounded, SEPARATE pool per provider, so one provider's
// slowness cannot consume the capacity the others need.
const pools = {
  nibss:      semaphore(120),
  paystack:   semaphore(60),
  flutterwave:semaphore(60),
  sepa:       semaphore(40),
  swift:      semaphore(20)
};
// this is the difference between a degraded rail and a degraded bank.

function route(p: OutboundPayment, providers: Provider[]): Provider | null {
  const viable = providers
    .filter(x => x.canReach(p.destination))          // capability
    .filter(x => x.breaker.state !== 'open')         // health
    .filter(x => x.remainingFloat >= p.amount)       // funding
    .filter(x => p.speed !== 'instant' || x.isInstant);

  if (!viable.length) return null;   // queue it, alert, do NOT guess

  // score: cost matters, but a cheap provider that fails 5% of the time
  // is more expensive than it looks once you price the support load.
  return viable.sort((a, b) =>
    (a.feeFor(p) / a.successRate) - (b.feeFor(p) / b.successRate)
  )[0];
}