Offline deposit and settlement

Offline payments have three moments: load, pay and settle. Only loading and settling touch the API.

1. Load the device

POST /offline/deposit moves value from the owner’s main account into their device wallet. The value is held in a device ledger account at the bank; nothing is ever created offline.

POST /offline/deposit
X-Idempotency-Key: 9a0e15d2-topup-0001

Note the header name: offline payments use X-Idempotency-Key, not Idempotency-Key. See Idempotency.

2. Pay, with no network

The network drops. Payments complete locally against the device wallet, phone to phone or at a POS. Both devices sign each payment, and each one is recorded with its own local reference and timestamp.

3. Settle when the signal returns

POST /offline/settlement posts the batch of taps and reconciles it into the real ledger, with one result per item.

• Posting the same batch again returns the same results. Nothing moves twice, so re-posting is the right recovery from a timeout.
• One failed item doesn’t void the rest of the batch.
• A device’s offline cap is derived from its settled history.

Device conditions

A movement is refused unless all four hold: a validated PIN in the session, the device registered and active, the device belongs to the caller, and it’s the device the wallet is bound to now.

You’ll receive offline_topup.completed and offline_settlement.completed webhooks as each step lands.