Skip to content

Phase 6 — Payments

Goal: money in. This phase covers:

  • apps/niobi-proxy: a relay with Niobi signing, caller verification and webhook verification
  • top-ups with the vendor fee
  • the callback path into the ledger, with the status-check backup
  • staff-run credit moves between workspaces
  • the transaction views

Milestone M2: in staging (niobi-proxy in mock mode), sign up → create a key → call the API → top up → the call is charged against the topped-up balance. The callback path and the status-check path each credit the top-up exactly once.

Note: staging never talks to the real Niobi. The production webhook hostname, firewall allowlist and certificate are set up in P9.02, and the first real top-up is in P9.13.

ID Task Who Needs Status
P6.01 niobi-proxy service, chart and deploy Agent P0.08, P0.09, P1.09 todo
P6.02 Niobi signing and outbound calls You + agent P6.01, P0.05 todo
P6.03 Webhook receiver Agent P6.02 todo
P6.04 Billing details and top-ups Agent P5.04, P6.02 todo
P6.05 Callback consumer and top-up status check Agent P6.03, P6.04, P4.02 todo
P6.06 Credit moves (staff action) Agent P5.11, P2.06 todo
P6.07 Transactions and Niobi reconciliation data Agent P6.05, P6.06 todo
P6.08 M2: the full loop in staging Agent P6.05, P5.07 todo

P6.01 — niobi-proxy service, chart and deploy

Section titled “P6.01 — niobi-proxy service, chart and deploy”

Who: Agent · Needs: P0.08, P0.09, P1.09

The service:

  • a TypeScript service using the shared niobi-proxy types
  • HMAC verification of every caller request: method, path, timestamp and body hash, within a 5-minute window
  • mock mode behind an environment flag
  • a health route

Deployment:

  • Dockerfile and image pushed to GHCR

  • the Helm chart in infra/niobi-proxy/

  • deployed by the pipeline through the self-hosted runner

  • reached by dashboard-api through its VPC binding

  • Spec: decisions log, Niobi payments static IP handling, Private service access, Container registry; ../architecture/tech-stack.md Niobi Payments Static IP Handling

  • Done when: a merge deploys it to the staging namespace, dashboard-api reaches its health route through the binding, and an unsigned or stale request is refused.

P6.02 — Niobi signing and outbound calls

Section titled “P6.02 — Niobi signing and outbound calls”

Who: You + agent · Needs: P6.01, P0.05

  • You: the sandbox credentials (Bitwarden, then the niobi-proxy secret for staging). The droplet’s IP is whitelisted (2026-11-02). The signing reference implementation, test vector and API docs are public; the scope is in ../architecture/niobi-integration.md.

  • Agent:

    • port the signing into niobi-proxy; it lives there and nowhere else
    • implement start collection (direct API, our top-up id as third_party_reference_1), the Côte d’Ivoire Orange OTP step and query transaction status, per ../architecture/niobi-integration.md sections 3–5 (confirm-before-credit, no blind retry of a start, non-final timeout)
    • make mock mode return realistic success, failure and pending results
  • Spec: ../product/design-doc.md (Niobi integration); decisions log, Niobi payments static IP handling (containment requirement)

  • Done when: the signing passes the docs’ test vector; the mock is exercised by tests; and in staging, against Niobi’s sandbox, each flow type (phone prompt, bank transfer, OTP, provider page) gives a success, a failure and a no-callback case (niobi-integration.md section 7).

Who: Agent · Needs: P6.02

A webhook route in niobi-proxy:

  • verify Niobi’s signature
  • treat the reference as idempotent
  • push the verified event to the niobi-callbacks queue through the Cloudflare Queues HTTP API, with the send-only token
  • return quickly

In staging, the mock produces signed callbacks against this same route.

  • Spec: decisions log, Niobi webhooks; ../architecture/network-security-map.md (A6)
  • Done when:
    • a mock-signed callback reaches the queue
    • a bad signature is refused and counted (for the observability alert)
    • a replayed callback is harmless

Who: Agent · Needs: P5.04, P6.02

Billing details: org-level, required before the first top-up.

Top-up:

  • Owner or Admin only
  • the customer enters credits; the server adds the vendor fee (flat or percentage, per currency)
  • create the pending top-up and call niobi-proxy
  • store credits, fee and total collected

First top-up: locks the workspace currency.

  • Spec: decisions log, Top-up transaction fee (Niobi markup), Credit balance & non-refundability; ../architecture/db-schema.md 4.4 (top-ups, payment_vendor_fees); ../product/build-inventory.md screens 17 and 21
  • Done when: total_collected = credits + fee on every row (enforced by a CHECK), and a Member is refused.

P6.05 — Callback consumer and top-up status check

Section titled “P6.05 — Callback consumer and top-up status check”

Who: Agent · Needs: P6.03, P6.04, P4.02

Consumer (in dashboard-api) for niobi-callbacks. One guarded transaction (WHERE status = 'pending'):

  • credit the credits only, never the fee
  • write the ledger entry
  • record the fee as revenue
  • set currency_locked_at

Status-check job: checks top-ups still pending after a couple of minutes, through the same guarded path. Pending past the threshold is flagged, never auto-failed. The receipt email goes through Resend.

Who: Agent · Needs: P5.11, P2.06

Customers don’t move credits themselves (decisions log, Credit moves are support-only). An admin API route lets staff move credits between two workspaces:

  • Same currency: 1 for 1.
  • Different currencies: the P2.06 rate (FX markup on each non-USD leg), shown to staff before confirming and locked at confirm.
  • Recording: one transaction with transfer_out and transfer_in ledger entries and a transfers row, the rate stored on both entries; reason required; audit-logged.
  • Spec: ../product/build-inventory.md screen 40, Credit moves, Cross-currency moves; decisions log, FX markup
  • Done when: both ledgers balance after concurrent moves (test), a move larger than the available balance (balance minus held) is refused, and Support (read-only staff) is refused.

P6.07 — Transactions and Niobi reconciliation data

Section titled “P6.07 — Transactions and Niobi reconciliation data”

Who: Agent · Needs: P6.05, P6.06

Transactions API: top-ups (credits, fee, total), transfers, settlements and released holds, for this workspace or all workspaces.

Reconciliation queries for admin screen 46:

  • the Niobi pooled wallet against the ledger balances, minus consumed funds and fees

  • pending and failed top-ups

  • Spec: ../product/build-inventory.md screens 19 and 46; ../product/design-doc.md (periodic reconciliation)

  • Done when: the numbers reconcile on seeded data, including fees kept out of balances.

Who: Agent · Needs: P6.05, P5.07

A Playwright-free end-to-end test script (the UI comes in phase 7): create a user through the API → create a key → top up (mock) → call → assert the charge, the balance and the ledger. Run it after every staging deploy.

  • Done when: it passes in the staging pipeline.