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-proxytypes - 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-apithrough its VPC binding -
Spec: decisions log, Niobi payments static IP handling, Private service access, Container registry;
../architecture/tech-stack.mdNiobi Payments Static IP Handling -
Done when: a merge deploys it to the staging namespace,
dashboard-apireaches 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-proxysecret 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.mdsections 3–5 (confirm-before-credit, no blind retry of a start, non-final timeout) - make mock mode return realistic success, failure and pending results
- port the signing into
-
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.mdsection 7).
P6.03 — Webhook receiver
Section titled “P6.03 — Webhook receiver”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-callbacksqueue 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
P6.04 — Billing details and top-ups
Section titled “P6.04 — Billing details and top-ups”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
pendingtop-up and callniobi-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.md4.4 (top-ups,payment_vendor_fees);../product/build-inventory.mdscreens 17 and 21 - Done when:
total_collected = credits + feeon every row (enforced by aCHECK), 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.
- Spec: decisions log, Top-up status check;
../architecture/db-schema.md8.3 item 2;../architecture/backend-scope.mdsection 4 Top-up - Done when: a top-up resolved by both the callback and the status check is credited once (test), and the receipt shows credits, fee and total.
P6.06 — Credit moves (staff action)
Section titled “P6.06 — Credit moves (staff action)”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_outandtransfer_inledger entries and atransfersrow, the rate stored on both entries; reason required; audit-logged. - Spec:
../product/build-inventory.mdscreen 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.mdscreens 19 and 46;../product/design-doc.md(periodic reconciliation) -
Done when: the numbers reconcile on seeded data, including fees kept out of balances.
P6.08 — M2: the full loop in staging
Section titled “P6.08 — M2: the full loop in staging”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.