Add to the address book

Register each external bank account or wallet in your address book for whitelisting before using it to fund deposits or receive withdrawals. Axiym performs due diligence and compliance checks before it becomes ACTIVE.

Each entry returns a destinationId. Despite the identifier name, an entry is required for both deposits and withdrawals.

Testing in sandbox

Use only bank details, wallet addresses, blockchain networks, and test assets provided or approved for your sandbox environment. Never add production payment details for a sandbox test.

Confirm with Axiym which due diligence and compliance checks, review outcomes, and lifecycle transitions are available in sandbox. See Sandbox testing.

1. Add a bank account or wallet

Add a bank account using the details agreed for your sandbox. Replace the illustrative bank values below before sending the request.

Supply exactly one of iban or accountNumber, together with currency and the bank details. Use iban for an account identified by an IBAN, or accountNumber for a domestic account number. The bank object requires bankName and address.country.

Bank fields depend on the destination corridor: supply swiftBic when required, and clearingCode for a required local routing code. Supply clearingSystemCode where the country has more than one clearing system. Omit unused optional fields instead of sending empty strings.

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/address-book/bank-accounts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data '{
    "currency": "USD",
    "accountNumber": "0123456789",
    "bank": {
      "bankName": "Bank of America",
      "address": { "country": "US" },
      "swiftBic": "BOFAUS3NXXX"
    }
  }'

Or add a wallet address:

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/address-book/wallets" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data "{\
    \"currency\": \"$EXTERNAL_ACCOUNT_CURRENCY\",\
    \"walletAddress\": \"$TESTNET_WALLET_ADDRESS\",\
    \"network\": \"$BLOCKCHAIN_NETWORK\"\
  }"

Use a different idempotency key for each new entry. Reuse the original key only when retrying the same request after an ambiguous result.

2. Store the entry

Store the returned destinationId with:

• whether it is a bank account or wallet;
• its currency and blockchain network where applicable; and
• its current status.

Do not store destinationId as an Axiym accountId. The identifiers represent different resources and are not interchangeable.

3. Wait for activation

A new external account starts in PENDING_REVIEW while Axiym performs due diligence and compliance checks. Once approved, it becomes ACTIVE and is whitelisted for deposits and withdrawals. Retrieve the entry to check its status:

curl \
  "https://partner-api.sandbox.axiym.io/api/v1/address-book/$DESTINATION_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"

Use destination.* events to react to lifecycle changes, and fetch the entry when your workflow needs its current status. Only ACTIVE entries may be used. destination.closed signals that the entry is permanently retired and can no longer fund deposits or receive withdrawals.

4. Use the entry in the correct direction

• Deposit: initiate the bank or blockchain payment from the exact account or wallet in the entry. Deposit instructions separately identify where the payment must be sent.
• Withdrawal: pass the entry's destinationId when creating the withdrawal.

The returned destinationId identifies the external account’s entry in your organization’s address book.