Register an external account

Register each owned external bank account or wallet before using it to send funds into Axiym or receive funds from Axiym. The account must belong to the client selected by clientId and must be registered for that client.

The API contract calls this resource a whitelisted own account and returns a destinationId. Despite the identifier name, registration is required for both deposits and withdrawals.

Every request uses /clients/{clientId}/whitelisted-own-accounts. Here, {type} is bank or wallet. Register only accounts owned by that client.

Testing registration in sandbox

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

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

1. Register a bank account or wallet

Register an external bank account:

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/whitelisted-own-accounts/bank" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data "{\
    \"currency\": \"$EXTERNAL_ACCOUNT_CURRENCY\",\
    \"accountNumber\": \"$SANDBOX_ACCOUNT_NUMBER\",\
    \"swiftBic\": \"$SANDBOX_SWIFT_BIC\",\
    \"bankName\": \"$SANDBOX_BANK_NAME\"\
  }"

Or register an external wallet:

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/whitelisted-own-accounts/wallet" \
  --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 registration. Reuse the original key only when retrying the same request after an ambiguous result.

2. Store the registered account

Store the returned destinationId with:

• the clientId that owns it;
• 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 registered external account starts in PENDING_REVIEW. Retrieve it until it becomes ACTIVE:

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

Use destination.* events to react to lifecycle changes, and fetch the record when your workflow needs its current status. Do not use an account that is pending review, suspended, or closed.

4. Use the account in the correct direction

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

Keep the registered account, Axiym account, deposit, or withdrawal in the same client context throughout the workflow.