ExchangeExchangeWithdrawals

Create withdrawal

Initiates a payout. The amount is reserved synchronously on success — the available balance drops immediately.

Idempotency: Idempotency-Key header recommended. Omitting it is permitted — the caller accepts all retry and duplicate risk.

Authentication

AuthorizationBearer
Token obtained via the login flow.

Headers

Idempotency-KeystringOptionalformat: "uuid"

Optional client-generated UUIDv4. Persist before issuing the request and reuse on retries. Omitting it is permitted — the caller accepts all retry and duplicate risk.

Request

This endpoint expects an object.
beneficiaryIdstringRequired

Must be status: active and match currency.

currencystringRequired
ISO 4217. Must match the beneficiary's currency.
amountstringRequired
Positive decimal string.
referencestringRequired<=140 characters

≤ 140 chars. Appears on the beneficiary’s bank statement (rail-dependent truncation).

clientReferencestringOptional<=140 characters

≤ 140 chars. Client’s internal tracker, echoed on reads, never sent to the bank.

Response

Withdrawal created with status: pending.

withdrawalIdstring
statusenum
  • pending — reserved, awaiting dispatch. Cancellable.
  • processing — dispatched to the rail. Not cancellable.
  • completed — rail confirms sent; reservation → final debit.
  • cancelled — client-initiated cancel while pending.
  • failed — rejected pre-dispatch; reservation released.
  • returned — sent but returned by receiving bank; balance restored.
beneficiaryIdstring
currencystring
amountstring
referencestring
paymentTypeenum
Inherited from the beneficiary's routing.
createdAtdatetime
updatedAtdatetime
clientReferencestring or null
statusReasonenum or null

Machine-readable context for the current status. Present when additional detail is available.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error