ExchangeWithdrawals

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.

Allowed values:

Errors

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