# Depositing funds

Retrieve deposit instructions, send funds from an active address book entry, and track the resulting deposit.

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/depositing-funds

A deposit moves funds from an
[address book entry](/account-api/concepts/accounts-and-destinations)
into an Axiym account. The external bank account or wallet and the receiving
Axiym account must both belong to your organization.

You do not create a deposit with an API request. You retrieve **deposit
instructions** for the intended Axiym account, send the payment outside the
Account API, and then use the API to track the incoming payment detected by
Axiym.

## The three parts of a deposit

| Part                 | Role                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------- |
| Address book entry   | The owned bank account or wallet from which the payment is permitted to originate.          |
| Deposit instructions | The receiving details to which the payment must be sent to credit a specific Axiym account. |
| Deposit              | The incoming payment record created after Axiym detects the payment.                        |

The address book entry answers **where may the payment come from**.
The deposit instructions answer **where must it be sent**.



```mermaid
sequenceDiagram
  participant Integration as Your integration
  participant Sender as Address book entry
  participant Account as Account API
  participant Network as Bank or network

  Integration->>Account: Request deposit instructions
  Account-->>Integration: Return receiving details
  Sender->>Network: Send funds using the instructions
  Network->>Account: Deliver the incoming payment
  Account-->>Integration: Send deposit webhook event
  Integration->>Account: Fetch current deposit when needed
  Account-->>Integration: Return the deposit
```



## Before sending funds

1. Confirm that the sending account or wallet is an active entry in your
   address book.
2. Select the Axiym account whose currency and payment rail match the payment
   you intend to send.
3. Retrieve the current deposit instructions for that Axiym account.

Send funds only from a registered, active address book entry. Use the deposit
instructions returned for the intended Axiym account in the current
environment.

## Deposit instructions

Deposit instructions depend on the Axiym account's payment rail.

Bank deposit

Bank instructions contain the receiving beneficiary name, account number,
bank name, SWIFT/BIC, and, when present, a reference assigned to the Axiym account.

Initiate the transfer from the registered bank account and
include the supplied `reference` when one is returned. Axiym uses
the reference, or the receiving account number when there is no reference,
to match the incoming payment to the intended account. Formatting spaces in
the reference do not affect matching.

Wallet deposit

Wallet instructions contain a `walletAddress` and
`network`. Send from the registered wallet using only
the Axiym account's currency and the specified network.

The receiving wallet address is used to associate the incoming payment
with the Axiym account.

## Deposit lifecycle

After Axiym detects the incoming payment, it appears as a deposit. The Axiym
account is credited only when processing completes.

Use webhook events or retrieve the deposit again to observe status changes.

| Status      | Meaning                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------- |
| `PENDING`   | The payment was detected and is awaiting crediting.                                           |
| `HELD`      | Processing is temporarily on hold. Continue monitoring the deposit for a later status change. |
| `COMPLETED` | The payment completed and the Axiym account was credited.                                     |
| `CANCELED`  | The deposit did not complete.                                                                 |
| `REJECTED`  | The deposit was rejected.                                                                     |

A canceled or rejected deposit can include a `reasonCode`. A completed wallet
deposit can include the network transaction hash.

## Deposit record and account balance

The deposit represents the incoming payment and its processing status. The
Axiym account represents the resulting balance held with Axiym.

A completed deposit tells you the credited account, amount, and currency,
along with any fee and available sender or network information. Depending on
the rail, it can also include:

* `remitterName`, as reported by the sending bank or network;
* an Axiym payment `code`; or
* a blockchain `transactionHash`.

Use the deposit for the business status of the incoming payment. Use the
account statement for the corresponding posted credit and running balance.