# Deposit funds

Product: Client Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.sandbox.axiym.io/client-account-api/integration-guide/deposit-funds

A deposit is initiated outside the Client Account API. Send funds from an `ACTIVE`,
whitelisted external account using the deposit instructions returned for the
intended Axiym account. Use the API to identify, track, and reconcile the
resulting deposit.

Complete [Add to the address book](/client-account-api/integration-guide/add-to-address-book)
before initiating the deposit payment. Wait for the external account to become `ACTIVE`
after Axiym’s due diligence and compliance checks.

Use the same `/clients/{clientId}` context for the external account’s address
book entry, receiving Axiym account, deposit, and statement.

## 1. Confirm the registered source

Confirm that the bank account or wallet from which the payment will originate:

* is registered in the selected client’s address book;
* is whitelisted and `ACTIVE`;
* uses the intended currency; and
* for a wallet, uses the intended blockchain network.

Do not send funds from an external account that has not been whitelisted or
is no longer `ACTIVE`.

## 2. Select the Axiym account

List Axiym accounts and select the `accountId` whose currency and payment rail
match the funds you will send.

```sh
curl "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/accounts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Do not infer receiving details from `paymentRails`.

## 3. Retrieve deposit instructions

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/accounts/$ACCOUNT_ID/deposit-instructions" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

The response lists one instruction per transfer scheme the account accepts,
in `nodes`. Pick the instruction whose `scheme` matches how you send the funds
(`SWIFT`, `FEDWIRE`, `ACH`, `SEPA`, `FPS`, `BOOK`, or `BLOCKCHAIN` for a
wallet) and use only its details.

A bank instruction returns:

* `beneficiaryName` and `beneficiaryAddress` — the receiving party to put on
  the transfer;
* `iban` or `accountNumber` — the account to send to for that scheme;
* the receiving bank, and an `intermediaryBank` when the transfer passes
  through one;
* `reference` — returned when the account is funded through a shared receiving
  account; include it on the transfer.

A wallet instruction returns a `walletAddress` and `network`.

See [Get deposit instructions](/client-account-api/api-reference/0.3.0/deposits/getDepositInstructions)
for the bank and wallet fields. The beneficiary name in wallet instructions
is for your records; the blockchain transfer itself carries no name.

## Testing deposits in sandbox

The conversion quickstart does not require a deposit because Axiym provides a
funded sell-side Axiym account.

When specifically testing deposits:

* use only the address book entry fixture and bank simulation process
  confirmed by Axiym; never send a real bank payment to sandbox details;
* use only the registered test wallet, test asset, and blockchain test network
  confirmed for the sandbox workflow; and
* verify the deposit, notification, account credit, and statement entry in the
  same way you would in production.

## 4. Send the funds

In production, initiate the bank or blockchain payment from the whitelisted
external account or wallet using the exact details of the instruction for the
scheme you send with.
Include the returned reference, when present, on a bank transfer, and use the
returned network for a wallet transfer.

The external payment does not include the address book entry's
`destinationId`. Bank deposits are matched to the receiving Axiym account by
the supplied reference, or by the receiving account number when no reference
is returned; wallet deposits are matched by the receiving address. Formatting
spaces in the bank reference do not affect matching.

In sandbox, use the test process agreed with Axiym. Never reuse payment details
from another environment or client context.

## 5. Find and track the deposit

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/deposits?accountId=$ACCOUNT_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Store the matching `depositId`, then retrieve that deposit when you need its
current status or complete details.

The [deposit record](/client-account-api/api-reference/0.3.0/deposits/getDeposit)
includes the amount, currency, fee, and available sender or network details,
such as `remitterName`, payment `code`, or `transactionHash`.

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/deposits/$DEPOSIT_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Do not rely on the Axiym account balance until the deposit is `COMPLETED`.
`HELD` is a temporary processing hold. Continue monitoring for a later status
change. `CANCELED` and `REJECTED` mean the deposit did not complete.

## 6. Reconcile the credit

Retrieve the Axiym account statement after completion:

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/accounts/$ACCOUNT_ID/statement" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Use `relatedResourceType: DEPOSIT` and `depositId` to join the posted credit to
the deposit record and resulting running balance.