Create a Wallet (New)

Overview

Create a currency-specific digital wallet for a company. When provisioned, the returned wallet ID serves as the central account reference for receiving inbound transfers, holding foreign currencies, executing FX conversions, and initiating outbound payouts.

If a wallet is created for a given currency for the first time, it automatically becomes the default wallet for that currency unless configured otherwise.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/{companyId}/wallets
• 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

Path Parameters

Parameter	Type	Required	Description
companyId	string	Yes	Unique identifier assigned to the company within the system (e.g. 4011).

Request Body

Request Fields (NewWalletRq)

Field	Type	Required	Description
currency	string	Yes	3-letter ISO 4217 currency code (e.g. USD, GBP, EUR, NGN, CAD).
type	string	Yes	Wallet type: standard (everyday transactions) or fx_balance (FX conversion operations).
customReferenceLabel	string	No	User-friendly custom label for the wallet (max 75 characters, e.g. US_SEGREGATED or Default GBP Wallet).

Request Example

{
  "currency": "USD",
  "type": "standard",
  "customReferenceLabel": "Operating USD Wallet"
}

Response

Success Response (200 OK)

{
  "id": 25427,
  "totalBalance": 0,
  "availableBalance": 0,
  "currency": "USD",
  "type": "standard",
  "companyId": 4011,
  "customReferenceLabel": "Operating USD Wallet",
  "isDefault": true,
  "isDisabled": false,
  "fundingType": "account"
}

Response Fields (Wallet)

Field	Type	Description
id	number	Unique identifier assigned to the newly created wallet. Store this ID for subsequent API flows.
totalBalance	number	Total cumulative balance (sum of available balance and locked balance).
availableBalance	number	Liquid funds available for immediate utilization, FX trades, or payouts.
currency	string	3-letter ISO currency code.
type	string	Wallet type (standard or fx_balance).
companyId	number	Company ID that owns the wallet.
customReferenceLabel	string	User-friendly name or custom reference label.
isDefault	boolean	Indicates whether this wallet is the default wallet for this currency.
isDisabled	boolean	Indicates whether the wallet is disabled for transactions.
fundingType	string	Method by which the wallet is funded (account, smartWallet, pooled, or null).

Error Responses

• 400 Bad Request: Invalid currency code, unsupported wallet type, or invalid company ID.
• 401 Unauthorized: Missing or expired Bearer token.
• 403 Forbidden: Insufficient permissions to create wallets for this company.
• 404 Not Found: Specified companyId does not exist.
• 500 Internal Server Error: Internal platform error.

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/4011/wallets' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "USD",
    "type": "standard",
    "customReferenceLabel": "Operating USD Wallet"
  }'

Python

import requests

company_id = "4011"
url = f"https://gateway.ahrvo.network/banking/ibans/v2/{company_id}/wallets"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "currency": "USD",
    "type": "standard",
    "customReferenceLabel": "Operating USD Wallet"
}

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

JavaScript (Node.js)

const axios = require('axios');

const companyId = '4011';
const url = `https://gateway.ahrvo.network/${companyId}/wallets`;
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};

const payload = {
  currency: 'USD',
  type: 'standard',
  customReferenceLabel: 'Operating USD Wallet'
};

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