Withdraw funds

A withdrawal sends funds from an Axiym account to an active address book entry. The accounts must both belong to your company and use the same currency.

Complete Add to the address book before creating the withdrawal. Third-party withdrawals are not supported.

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 registered-account status, withdrawal states, notifications, Axiym account debits, and reconciliation. See Sandbox testing.

1. Select the source Axiym account

Confirm that the source account 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. Confirm the registered recipient

Retrieve the address book entry by destinationId. Confirm that it:

belongs to your company;
is 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.

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. The example below omits documents; add them when required.

curl --request POST "https://partner-api.sandbox.axiym.io/api/v1/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 address book entry 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.

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.

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

The confirmation request has no body. It requires its own idempotency key and returns the withdrawal with status PENDING, which means execution has begun.

5. Track and reconcile

curl \
  "https://partner-api.sandbox.axiym.io/api/v1/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.