Developer documentation
Payments that keep working when the network does not
PayVault is payment infrastructure for unreliable networks. Your app can accept and make payments with no signal, with the risk set in advance, and everything is reconciled and settled when connectivity returns.
What PayVault is
PayVault is a B2B technology layer for banks, mobile money operators, fintechs, payment service providers and aid agencies in Africa. You keep your customers, your brand and your ledger. PayVault provides the offline protocol, the client library, the server-side reconciliation and the events that tell your systems what to settle.
In production the licensed partner is the custodian of funds and the lender of record for any overdraft. The reference app in this repository also includes a hosted sandbox ledger, so you can try the full flow without a ledger of your own.
Two layers
Layer 1 is reliability. Every payment is a signed, hash-chained message that is stored durably on the device, moved by QR code, uploaded whenever someone has signal, and de-duplicated by the server. A payment can be retried, relayed by a courier or uploaded twice without being counted twice.
Layer 2 is guaranteed offline acceptance. A merchant can decide to accept a payment with no network because the value behind it was locked in advance (the offline vault) and, optionally, because the partner extended a limited overdraft. The merchant verifies the payment fully on the device. If it passes, the merchant is paid, whatever happens later.
Who it is for
- Mobile money operators and agent networks that lose sales to network downtime.
- Banks, fintechs and payment service providers that want offline acceptance in their existing apps and POS flows.
- Humanitarian and government cash programmes that pay in low-connectivity areas.
- Transit, ticketing and market use cases with many small, frequent payments.
The flow in five steps
- Issue: your backend asks PayVault to sign an allowance for a customer's device key, after you have locked the funds in your ledger.
- Request: the merchant's device shows a payment request as a QR code.
- Pay: the customer's device signs a payment, chained to its previous one, and shows it back as a QR code.
- Verify: the merchant's device checks signatures, limits, revocations and the chain, offline, and accepts or rejects.
- Reconcile: when either side has signal, payments are uploaded. PayVault de-duplicates them, allocates each one to funded value, overdraft or the risk pool, detects forks, and emits events for your ledger.
The sandbox
PayVault is currently a prototype. The API and the console you can reach run in sandbox mode: no real money moves, no funds are held, and the same API key format is used throughout. Every country pack is marked concept, and the limits in it are illustrative placeholders, not regulator-approved values.
To try it, create a partner account in the console, create an API key, and follow the quickstart. Requests in these docs use $PAYVAULT_URL for the origin that serves the API.