Withdraw funds

A withdrawal sends funds from the selected client's Axiym account to an ACTIVE, whitelisted external bank account or wallet in the same currency.

Complete Add to the address book before creating the withdrawal, and wait for the external account to become ACTIVE after Axiym's due diligence and compliance checks.

Use the same /clients/{clientId} context for the source Axiym account, external account’s address book entry, withdrawal, and statement.

Testing withdrawals in sandbox

Bank withdrawals use the sandbox simulation process and registered test bank account confirmed by Axiym. They are not submitted to a real banking network.
Wallet withdrawals use the configured blockchain test network, registered test wallet, and test assets—never a production-network wallet.

Verify external-account status, withdrawal states, notifications, Axiym account debits, and reconciliation. See Sandbox testing.

1. Select the source Axiym account

Confirm that the source account belongs to the selected client, is ACTIVE, uses the withdrawal currency, and has sufficient balance for sourceAmount. The fee is deducted from this amount; the recipient receives destinationAmount, equal to sourceAmount less fee.

2. Select the external account

Retrieve the external account from the selected client’s address book by destinationId. Confirm that it:

is whitelisted and ACTIVE;
uses the same currency; and
for a wallet, uses the intended blockchain network.

3. Create the withdrawal

Set WITHDRAWAL_CURRENCY to the source account's currency and WITHDRAWAL_AMOUNT to the decimal amount to debit. The amount must fit within the source account balance.

Generate two distinct idempotency keys once for each new withdrawal: one for creation and one for confirmation. Save them with the withdrawal workflow before sending requests, so retries can reuse the original keys.

WITHDRAWAL_IDEMPOTENCY_KEY="$(uuidgen)"
CONFIRM_IDEMPOTENCY_KEY="$(uuidgen)"

Run this setup only for a new withdrawal, not before each retry. The Idempotency-Key header lets Axiym return the original result when the same operation is retried, instead of processing it again.

Include supportingDocuments when required by the destination corridor. Each document includes documentType, name, and the file content encoded as base64 in data, without a data-URL prefix. Supply up to 10 documents, each up to 10 MB in PDF, JPEG, or PNG format. The example below omits documents; add them when required.

Set YOUR_REFERENCE to your own payment, invoice, or treasury record identifier if you use externalReference, or omit that optional field. It helps correlate the withdrawal with your records; it does not replace an idempotency key.

curl --request POST "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/withdrawals" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $WITHDRAWAL_IDEMPOTENCY_KEY" \
  --data "{\
    \"sourceAccountId\": \"$ACCOUNT_ID\",\
    \"sourceAmount\": {\"amount\": \"$WITHDRAWAL_AMOUNT\", \"currency\": \"$WITHDRAWAL_CURRENCY\"},\
    \"destinationId\": \"$DESTINATION_ID\",\
    \"reference\": \"Treasury sweep\",\
    \"externalReference\": \"$YOUR_REFERENCE\"\
  }"

destinationId is the external account's address book identifier. It is not an Axiym accountId, bank account number, or wallet address.

Creation returns a withdrawal in PENDING_CONFIRMATION; it does not begin execution. Store the returned withdrawalId and set WITHDRAWAL_ID to it for the confirmation and tracking requests below. The response includes a snapshot of the external account details used for this withdrawal, plus an Axiym-generated payment code.

If the create request times out or its response is unclear, retry the same request body with the same WITHDRAWAL_IDEMPOTENCY_KEY. Generating a new key could create a second withdrawal.

4. Confirm the withdrawal

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

Use CONFIRM_IDEMPOTENCY_KEY for this operation. It must differ from the key used to create the withdrawal. The confirmation request has no body.

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/withdrawals/$WITHDRAWAL_ID/confirm" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Idempotency-Key: $CONFIRM_IDEMPOTENCY_KEY"

Confirmation returns the withdrawal with status PENDING, meaning it has been accepted and queued for execution.

If confirmation times out or its response is unclear, retry the confirmation for the same withdrawalId with the same CONFIRM_IDEMPOTENCY_KEY. Do not restart the create step to recover a confirmation response.

Keep the clientId, endpoint, resource identifier, and body unchanged when retrying an operation. Use new keys for new operations. See Idempotency for the full key and retry rules.

5. Track and reconcile

curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/withdrawals/$WITHDRAWAL_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"

PENDING_CONFIRMATION, PENDING, and HELD are non-terminal. COMPLETED, CANCELED, and REJECTED are terminal. Inspect reasonCode when the withdrawal does not complete.

For a completed wallet withdrawal, transactionHash identifies the network transaction. Use the source Axiym account statement and withdrawalId to reconcile the posted debit.