Withdrawing funds

A withdrawal moves funds from an Axiym account to a address book entry. The Axiym account supplies the balance, and the bank account or wallet from your address book receives the outgoing payment.

Unlike a deposit, a withdrawal is initiated through the Direct Trade API. It uses a two-step create-and-confirm flow: creation returns a PENDING_CONFIRMATION withdrawal, and confirmation begins execution.

Third-party withdrawals are not supported.

The three parts of a withdrawal

Part	Role
Source Axiym account	Holds the balance from which funds are withdrawn. Identified by `sourceAccountId`.
Address book entry	The owned bank account or wallet that receives the payment. Identified by `destinationId`.
Withdrawal	The outgoing payment record created and tracked through the Direct Trade API. Identified by `withdrawalId`.

These resources must all belong to your company. The source Axiym account and address book entry must also use the same currency.

Before creating a withdrawal

Confirm that:

the external bank account or wallet is registered to your company;
the address book entry is ACTIVE;
its currency matches the source Axiym account;
a wallet uses the intended blockchain network; and
the source Axiym account is active and has sufficient balance for sourceAmount.

Registering an external account does not move funds. It creates the reusable record referenced by destinationId.

Creating a withdrawal

Create the withdrawal using sourceAccountId, destinationId, and sourceAmount to debit. Use an idempotency key so the request can be retried safely without creating another withdrawal. Include supportingDocuments when required by the destination corridor.

The fee is deducted from sourceAmount. The recipient receives destinationAmount, which equals sourceAmount less fee.

For example, a USD withdrawal must use a USD Axiym account and an active USD external bank account. A USDT withdrawal must use a USDT Axiym account and an active USDT external wallet on the configured network.

The response contains the new withdrawalId, status PENDING_CONFIRMATION, amount, fee, and the address book entry details used for that payment. The embedded details record where the specific withdrawal was instructed to go; destinationId remains the reusable reference to the registered account.

Confirming a withdrawal

Confirm the returned withdrawalId with POST /withdrawals/{withdrawalId}/confirm. The request has no body and requires a new idempotency key. Confirmation changes the withdrawal to PENDING and begins execution.

Creation and confirmation are distinct operations and use distinct idempotency keys. If either response is lost, retry that exact operation with its original key.

Withdrawal lifecycle

Do not infer the next status from the current one. Use webhook events or retrieve the withdrawal again to observe changes.

Status	Meaning
`PENDING_CONFIRMATION`	The withdrawal was created and awaits explicit confirmation. Execution has not begun.
`PENDING`	The withdrawal was accepted and is awaiting execution.
`HELD`	Processing is temporarily on hold. Continue monitoring the withdrawal for a later status change.
`COMPLETED`	The outgoing payment completed.
`CANCELED`	The withdrawal was canceled before completion.
`REJECTED`	The withdrawal was rejected and did not complete.

A canceled or rejected withdrawal can include a reasonCode. A completed wallet withdrawal can include a blockchain transactionHash.

Withdrawal record and account balance

The withdrawal represents the outgoing payment and its processing status. The source Axiym account represents the balance held with Axiym.

Use externalReference to associate the withdrawal with your own payment, invoice, or treasury record. The withdrawal also receives an Axiym-generated payment code.

Use the withdrawal for the business status, amount, fee, and payment details. Use the source Axiym account statement to reconcile the posted debit and running balance.

Common mistakes

Passing an accountId, bank account number, or raw wallet address as destinationId.
Retrying creation or confirmation without its original idempotency key.

The Idempotency guide explains how to retry funds-moving requests safely.