Skip to navigation

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 — not yet dispatched. Cancellable, unless statusReason is compliance_review: the withdrawal is held by a compliance check and stays pending until compliance clears it.
  • processing — dispatched to the rail. Not cancellable.
  • completed — rail confirms sent; reservation → final debit.
  • cancelled — client-initiated cancel while pending.
  • failed — rejected; 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 nullOptional
statusReasonenum or nullOptional

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

  • compliance_review — set with pending; the withdrawal is held by a compliance check and cannot be cancelled.
  • returned_by_bank — set with returned.
Allowed values:

Errors

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