# Withdraw funds

Product: Account API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.sandbox.axiym.io/account-api/integration-guide/withdraw-funds

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

Complete [Add to the address book](/account-api/integration-guide/add-to-address-book)
before creating the withdrawal, and wait for the external account to become
`ACTIVE` after Axiym's due diligence and compliance checks.

## 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](/account-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. Select the external account

Retrieve the external account from your 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.

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

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

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

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 endpoint, resource identifier, and body unchanged when retrying an
operation. Use new keys for new operations. See
[Idempotency](/account-api/integration-guide/fundamentals/idempotency) for the
full key and retry rules.

## 5. Track and reconcile

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