Payment (New) - Overview

Introduction

The Payment (New) API provides streamlined capabilities for executing domestic and cross-border transfers, moving funds between same-currency wallets, generating secure document upload links for payout compliance, and tracking detailed payout lifecycle states by unique payment identifiers.

Key Capabilities

• Internal Wallet-to-Wallet Transfers: Instantly move funds between two wallets holding the same currency without incurring FX conversion spreads.
• Payment Lifecycle Reconciliation: Retrieve comprehensive payment details, fee breakdowns, routing targets, and current states by paymentId to resolve RFI inquiries or avoid duplicate execution.
• Compliance Document Uploads: Obtain pre-signed 10-minute S3 upload URLs to attach invoices, payment confirmations, or supporting compliance documents directly to company payment records.
• Proof of Payment Documentation: Seamlessly access verified transaction receipts and legal proof of payment records.

Authentication

All Payment 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	/transfer	Execute an instant wallet-to-wallet transfer between two same-currency wallets
POST	/documents/generate-upload-link	Generate a temporary pre-signed upload URL for payment compliance files
GET	/payments/{paymentId}	Retrieve full transaction details, execution state, target account, and pricing by paymentId
GET	/profile/transaction-history/proof-of-payment/{reference}	Download official proof of payment for a completed transaction

Payout & Transfer Workflow

sequenceDiagram
    autonumber
    actor Client as Business Client
    participant API as Payment API
    participant Wallet as Multi-Currency Wallet
    participant Target as Beneficiary Account

    Client->>API: POST /transfer (sourceWalletId, targetWalletId, amount, currency)
    API->>Wallet: Validate balances & transfer funds
    Wallet-->>API: Funds moved instantly
    API-->>Client: 200 OK (reference, state: completed)

    opt Document Attachment
        Client->>API: POST /documents/generate-upload-link (fileName, companyId)
        API-->>Client: 200 OK (upload URL, documentKey)
    end

    Client->>API: GET /payments/{paymentId}
    API-->>Client: 200 OK (state: completed, target details, pricing)

Next Steps

• Execute an internal transfer with Wallet-to-Wallet Transfer.
• Query payout details and execution states with Retrieve Payment Details.
• Upload compliance attachments with Generate Upload Link.