# Withdrawal lifecycle

Follow a withdrawal from creation to a terminal outcome.

Product: Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/account-api/concepts/withdrawal-lifecycle

Creating a withdrawal returns an instruction in `PENDING_CONFIRMATION` status.
It does not begin execution. Confirm the returned `withdrawalId` with
`POST /withdrawals/{withdrawalId}/confirm` to move it into `PENDING` and begin
processing.

Processing is asynchronous, and the statuses do not form one fixed linear
sequence. A withdrawal can be held and later return to pending processing
before reaching a terminal outcome.



```mermaid
flowchart TD
  A["Create"] --> B["Awaiting confirmation"]
  B -->|Confirm| C["Processing"]
  C --> D["On hold"]
  D -->|Resume| C
  C --> E["Completed"]
  C --> F["Not completed"]
```



The diagram uses operational labels. The exact API statuses are listed below.

| Status                 | Meaning                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `PENDING_CONFIRMATION` | Created and awaiting the explicit confirmation request. Execution has not started. |
| `PENDING`              | Confirmed and awaiting or undergoing execution.                                    |
| `HELD`                 | Processing is temporarily on hold. Continue monitoring the withdrawal.             |
| `COMPLETED`            | Completed successfully.                                                            |
| `CANCELED`             | Canceled before completion; inspect `reasonCode`.                                  |
| `REJECTED`             | Rejected and not completed; inspect `reasonCode`.                                  |

Treat the current withdrawal resource as authoritative. Events are
notifications and may arrive more than once or out of order.

## Account activity

A withdrawal debits `sourceAmount` from the source account. The fee is deducted
from this amount, so the recipient receives `destinationAmount`, equal to
`sourceAmount` less `fee`.

Use the withdrawal resource for processing status and outcome details. Use the
account's current `balance` and its statement for posted activity. Reconcile
the withdrawal debit using `relatedResourceType: WITHDRAWAL` and the
`withdrawalId` as `relatedResourceId`; do not infer completion from a balance
change alone.