11. API & Protocols/Financial Engine
Billing & Treasury API
The Treasury API orchestrates ledger management, secure checkout tokenization, and resource credit deductions (SMS/WhatsApp gas).
FINANCIAL INTEGRITY
ACID
Database Transaction Compliance
“All credit deductions and payments utilize strictly typed PostgreSQL $transactions to prevent double-spending or race conditions.”
Idempotent Financial Routing
Transaction Orchestration
Combine multiple pending invoices into a single payment envelope.
POST/v1/billing/initialize
json
| 1 | { |
| 2 | "invoiceIds": ["inv_123abc", "inv_456def"] |
| 3 | } |
Gateway Execution (Card/Mobile Money)
Pass the initialized Transaction ID to a gateway (e.g. MPESA, STRIPE_CARD) to retrieve the secure checkout URL.
POST/v1/billing/execute
json
| 1 | { |
| 2 | "transactionId": "txn_889900", |
| 3 | "gateway": "MPESA" |
| 4 | } |
Project Faucet Allocations
Set a hard limit on how many credits a specific project node can drain from the master organizational vault.
POST/v1/organizations/:orgId/treasury/allocate
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| projectId | string | Required | The target project ID. |
| maxSms | number | Required | Monthly SMS allowance (-1 for unlimited). |
| maxWhatsapp | number | Required | Monthly WhatsApp conversation allowance. |
Asynchronous Webhook Reconciliation
Gateway Webhooks
External gateways (Stripe, Selcom, Flutterwave) post asynchronous callbacks to
/billing/webhooks/[gateway]. The control plane validates the cryptographic signature (e.g. verif-hash), marks the transaction as COMPLETED, unlocks infrastructure assets, and dispatches PDF receipts automatically.