Create and confirm a withdrawal

Before submitting

Confirm that the source account and address book entry are active, compatible, and belong to the authenticated organization. Confirm sufficient balance for sourceAmount, in the source account currency. The fee is deducted from sourceAmount; the recipient receives destinationAmount, equal to sourceAmount less fee.

Create the instruction

Call POST /withdrawals with sourceAccountId, sourceAmount, destinationId, and, where needed, reference and externalReference. Follow the API Reference for the exact contract.

Include supportingDocuments when required by the destination corridor. Each document contains documentType, name, and raw file bytes encoded as base64 in data, without a data-URL prefix. The response returns document metadata, not file content.

Use one idempotency key for one withdrawal intent. Persist the key before the request and reuse it only when retrying the identical operation.

Creation returns the withdrawal in PENDING_CONFIRMATION status; it does not begin execution. Persist the returned withdrawalId, initial status, external reference, request ID, and idempotency key before continuing.

Confirm the instruction

Review the returned sourceAccount, destination, sourceAmount, destinationAmount, and fee against the intended payment. Confirm only after accepting those details.

Call POST /withdrawals/{withdrawalId}/confirm with the identifier returned by creation. The confirmation has no request body and requires its own idempotency key. Generate it once for this confirmation and preserve it when retrying the same request.

The response moves the withdrawal to PENDING, which means it is awaiting or undergoing execution. A successful confirmation is not a completed payment; continue with tracking.