Sending money

Three groups move value out of the wallet, one per kind of destination:

Everything else on this API reads, or mints something to receive into. These three share the rules below.

Two independent grants

The key must carry the money capability, granted per key; and the business must be enabled for money over the API, granted per business by us. Neither is sufficient alone - a key that leaks pays nobody unless the business was also opened, and opening a business arms no key that was not separately granted.

You will see capability_required for the first and api_money_not_enabled for the second, so you always know which to go and ask for. See Access.

Idempotency-Key is required

Required on every endpoint that moves money, and only there. Send a value unique to the payment you intend to make - a uuid, or your own payment id. Retry a request that timed out with the SAME key and you get the SAME order back (200, where a fresh call answers 202) instead of paying twice.

It is mandatory rather than encouraged because a retry is not a mistake here, it is what every HTTP client does by default when a request times out - and a payout that times out has already been created. Optional would mean the protection is on only for the integrator who already thought about it.

• The key is remembered for 24 hours, scoped to your business.
• Reusing one with a different body is refused (idempotency_key_reused) rather than answered, because either answer would be a lie.
• A key whose first request is still running is refused too (idempotency_in_flight) - retry once it settles and it replays.
• A request that fails without creating an order releases its key, so a corrected retry is free to reuse it.

Accepted is not settled

A successful call answers 202 with the order. Nothing has landed yet: the wallet is debited and the payment is on its way. Follow it on Transactions or the webhooks, and report money delivered only when the order says so.