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

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

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 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

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 includes the amount, currency, fee, and available sender or network details, such as remitterName, payment code, or transactionHash.

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:

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.