Create a Wallet-to-Wallet Transfer (New)

Overview

The wallet-to-wallet transfer API enables seamless, instant movement of funds between two wallets holding the same currency within your account. This is ideal for internal balance rebalancing, allocating funds to dedicated operational wallets, or segregating merchant pools without incurring foreign exchange conversion costs.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/transfer
• Authentication: Bearer token required

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
x-api-key	string	No	Optional API key

Request Body

Request Fields

Field	Type	Required	Description
amount	number	Yes	The amount you intend to deduct from the source wallet (e.g. 200).
currency	string	Yes	3-character ISO currency code of both wallets (e.g. USD). Must match both source and target wallets.
sourceWalletId	number	Yes	The wallet ID from which funds are deducted (e.g. 8599).
targetWalletId	number	Yes	The wallet ID to be funded (e.g. 90033).
description	string	No	Optional description or purpose for the transfer (e.g. Internal funds movement).
externalUniqueRef	string	No	Client-supplied idempotency key or unique reference identifier.

Request Example

{
  "amount": 200,
  "currency": "USD",
  "sourceWalletId": 8599,
  "targetWalletId": 90033,
  "description": "Internal rebalancing to operational wallet",
  "externalUniqueRef": "71467f6d-58ed-400f-89b6-20db028fb498"
}

Response

Success Response (200 OK)

{
  "result": {
    "amount": 200,
    "currency": "USD",
    "reference": "T0-28052024-046",
    "description": "Internal rebalancing to operational wallet",
    "sourceWalletId": 8599,
    "targetWalletId": 90033,
    "state": "completed",
    "externalUniqueRef": "71467f6d-58ed-400f-89b6-20db028fb498"
  }
}

Response Fields

Field	Type	Description
result.amount	number	Amount transferred.
result.currency	string	ISO currency code.
result.reference	string	Unique transaction reference identifying the transfer.
result.sourceWalletId	number	Source wallet identifier.
result.targetWalletId	number	Target wallet identifier.
result.description	string	Description associated with the transaction.
result.state	string	Execution state (completed or failed).
result.externalUniqueRef	string	Client-provided external identifier.

Error Responses

• 400 Bad Request: Mismatched currencies between wallets, invalid wallet IDs, or insufficient source funds.
• 401 Unauthorized: Missing or invalid Bearer authentication token.
• 403 Forbidden: Insufficient account permissions to access one or both wallets.
• 404 Not Found: Source or target wallet does not exist.
• 500 Internal Server Error: Internal processing failure.

Code Examples

Base URL

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/ibans/v2/transfer' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 200,
    "currency": "USD",
    "sourceWalletId": 8599,
    "targetWalletId": 90033,
    "description": "Internal rebalancing",
    "externalUniqueRef": "71467f6d-58ed-400f-89b6-20db028fb498"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/transfer"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "amount": 200,
    "currency": "USD",
    "sourceWalletId": 8599,
    "targetWalletId": 90033,
    "description": "Internal rebalancing",
    "externalUniqueRef": "71467f6d-58ed-400f-89b6-20db028fb498"
}

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

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/transfer';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};

const payload = {
  amount: 200,
  currency: 'USD',
  sourceWalletId: 8599,
  targetWalletId: 90033,
  description: 'Internal rebalancing',
  externalUniqueRef: '71467f6d-58ed-400f-89b6-20db028fb498'
};

axios.post(url, payload, { headers })
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response ? err.response.data : err.message));

Interactive API Explorer