# 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.