Initiate Transfer (Atlas)

Overview

The POST /banking/ibans/v2/transfer endpoint initiates a direct funds movement from one wallet to another wallet or business entity.

This endpoint supports externalUniqueRef—an external tracking reference provided by your system to prevent duplicate ledger transactions and ensure idempotency.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/transfer
• Authentication: Bearer token required
• Permissions: Client:Make Payment To Account:write, Client:Make Payment To Another Business:write, Admin:Exchange Now:write, Client:At Desired Rate:write

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Content-Type	application/json	Yes	Request payload format
Accept	application/json	Yes	Response payload format

Request Body

Request Fields

Field	Type	Required	Description
amount	number	Yes	Transfer amount (e.g. 1000).
currency	string	Yes	3-letter currency code (e.g. USD).
sourceWalletId	number	Yes	Originating wallet identifier.
targetWalletId	number	Yes	Destination wallet identifier.
description	string	No	Optional human-readable memo or description.
externalUniqueRef	string	No	Unique external reference (up to 40 characters) used for record-keeping and duplicate prevention.

Request Example

{
  "amount": 1000,
  "currency": "USD",
  "sourceWalletId": 1,
  "targetWalletId": 2,
  "description": "Internal funds movement",
  "externalUniqueRef": "PAY1234567890XYZ1234567890ABC"
}

---

Response

Success Response (200 OK)

{
  "reference": "TO-11012024-005",
  "state": "completed",
  "amount": 1000,
  "currency": "USD",
  "sourceWalletId": 1,
  "targetWalletId": 2,
  "description": "Internal funds movement",
  "externalUniqueRef": "26c8b828-9ee3-4f2a-b98f-fc317f934897"
}

Response Fields

Field	Type	Description
reference	string	Unique order tracking reference (e.g. TO-11012024-005).
state	string	Execution state (e.g. completed).
amount	number	Amount moved.
currency	string	ISO currency code.
sourceWalletId	number	Originating wallet ID.
targetWalletId	number	Destination wallet ID.
description	string	Transfer memo or reason.
externalUniqueRef	string	External idempotency reference.

---

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "sourceWalletId": 1,
    "targetWalletId": 2,
    "description": "Internal funds movement",
    "externalUniqueRef": "TX-9988776655"
  }'

JavaScript (Fetch)

const response = await fetch('https://api.ahrvo.network/banking/ibans/v2/transfer', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1000,
    currency: 'USD',
    sourceWalletId: 1,
    targetWalletId: 2,
    description: 'Internal funds movement',
    externalUniqueRef: 'TX-9988776655'
  })
});

const data = await response.json();
console.log('Transfer reference:', data.reference, 'Status:', data.state);

Python (requests)

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/transfer"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "amount": 1000,
    "currency": "USD",
    "sourceWalletId": 1,
    "targetWalletId": 2,
    "description": "Internal funds movement",
    "externalUniqueRef": "TX-9988776655"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

---

Interactive API Console

Test the endpoint directly in your browser: