Money Flows

Money-flow endpoints must be designed for retries, timeouts, and provider uncertainty.

Idempotency

Send Idempotency-Key on every retryable mutation:

• POST /wallets/transfer
• POST /wallets/cash-in
• POST /wallets/airtime
• POST /wallets/bill-pay
• POST /wallets/topup-dev
• POST /savings-pots/{blnkBalanceId}/deposit
• POST /savings-pots/{blnkBalanceId}/withdraw
• POST /virtual-cards

Use a stable operation identifier. Do not generate a new idempotency key on retry.

Quotes before execution

Use POST /wallets/transfer/quote before showing the final transfer confirmation. The quote response should drive fees, limits, blockers, and total.

Sandbox versus staging

Sandbox may simulate success, pending, and failure. Staging validates live provider behavior. Never use staging for exploratory destructive testing.