# Withdraw funds

Product: Client Trade API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/trade-api/integration-guide/withdraw-funds

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

Complete [Add to the address book](/trade-api/integration-guide/add-to-address-book)
before creating the withdrawal. Third-party withdrawals are not supported.

Keep every resource and request under the same `/clients/{clientId}` path.

## 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](/trade-api/integration-guide/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 the same client as the source Axiym account;
* 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.

```sh
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 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.

```sh
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"
```

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

```sh
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.