Wallet (New) - Overview

Introduction

The Wallet (New) API provides multi-currency treasury infrastructure, virtual account issuance, real-time balance tracking, and asynchronous statement generation for global commercial operations.

Each company can provision currency-specific digital wallets (e.g., USD, GBP, EUR, NGN), link them to local clearing rails or global SWIFT IBANs via automated funding methods, and extract comprehensive ledger statements for audits and accounting.

Key Capabilities

• Currency-Specific Wallets: Provision standard or fx_balance wallets for over 50 supported global currencies.
• Dedicated Virtual Account Numbers (vIBANs): Generate segregated or pooled local and international bank account numbers (CHAPS, BACS, Faster Payments, SEPA, SWIFT) through integrated funding methods.
• Auto-Creation of Funding Methods: Dynamically generate new local/global clearing details on-demand with the autoCreate=true parameter.
• Real-Time Ledger Balances: Inspect totalBalance, availableBalance, locked reserves, and account funding types.
• Asynchronous Statement Reporting: Export transaction histories across multiple wallets for custom date ranges in CSV or PDF format directly to corporate finance teams.

Authentication

All Wallet API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer <your_access_token>

An optional x-api-key header may also be supplied for tenant-based routing.

Base URLs

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

Common Headers

Header	Value	Required	Description
Authorization	Bearer {token}	Yes	JWT Bearer access token
Content-Type	application/json	Yes (for POST)	Request payload format
Accept	application/json	Yes	Response payload format
x-api-key	string	No	Optional API key for merchant routing

Available Endpoints

Method	Endpoint	Description
POST	/{companyId}/wallets	Create a new currency-specific digital wallet for a company
GET	/{companyId}/wallets	List, filter, and paginate all digital wallets belonging to a company
GET	/{companyId}/wallets/{walletId}	Retrieve specific wallet details, live balance, and configuration
GET	/{companyId}/wallets/{walletId}/fundingMethods	Retrieve or auto-create local/international funding account details
POST	/statement/export	Queue an asynchronous ledger statement export job (CSV / PDF)

Wallet Lifecycle & Funding Architecture

graph TD
    A["Create Wallet (POST /{companyId}/wallets)"] --> B["Wallet Initialized (id, currency)"]
    B --> C["Get Funding Methods (GET /{companyId}/wallets/{walletId}/fundingMethods?autoCreate=true)"]
    C --> D{"Account Type"}
    D -->|"Segregated Local"| E["Dedicated Sort Code / Account Number (CHAPS, BACS, Faster Payments)"]
    D -->|"Segregated Global"| F["Dedicated SWIFT IBAN (International Wire)"]
    D -->|"Pooled Account"| G["Shared Account with Smart Wallet Reference"]
    E & F & G --> H["Receive Funds into Wallet"]
    H --> I["Check Balance (GET /{companyId}/wallets/{walletId})"]
    I --> J["Extract Audit Statement (POST /statement/export)"]

Next Steps

• Provision a new wallet with Create Wallet.
• View company holdings with Get all Wallets.
• Inspect and provision bank clearing coordinates with Funding Methods.
• Export transaction statements with Request Wallet Statement.