Debit an account

POST 
/v1/accounts/:account_id/debit

Removes money from an account. If the available_balance is too low, the request fails with insufficient_funds and a 402. Money held by pending authorizations can't be debited.

There are two ways to prevent duplicate debits, and you should use both:

• Idempotency-Key protects against retries. Using the same key within 24 hours returns the stored response instead of creating another debit.
• client_transaction_id identifies the actual debit. It must be unique for the account and doesn't expire. Reusing the same ID with the same amount returns 200 with Idempotent-Replay: true and doesn't move any money. Reusing it with a different amount returns 409 adjustment_already_applied.

Send both on every debit request.

Request

Responses

200

The updated account. Carries Idempotent-Replay: true when the client_transaction_id had already been applied.

Response Headers

Idempotent-Replay

true when this response reproduces an earlier one — the same Idempotency-Key, or the same client_transaction_id, seen before. Absent otherwise.

402

The account's available balance is too low.

409

adjustment_already_applied: this client_transaction_id was already applied to the account with a different amount or direction. Or idempotency_request_in_progress: the movement carrying it is still in flight.

422

Well-formed but fails a business rule.