Atlas Beneficiary Service - Overview

Introduction

The Atlas Beneficiary Service provides enterprise-grade recipient lifecycle management across multiple payment rails—including domestic clearing (ACH, Faster Payments, SEPA), cross-border international wires (SWIFT), mobile money wallets (e.g. M-PESA), and stablecoins (USDC / USDT on Ethereum ERC-20).

With built-in Payee Verification (UK Confirmation of Payee and Nigerian account resolution), rigorous sanction list validation (OORA screening), and support for nested regulated financial institutions, the Atlas Beneficiary Service ensures zero-error payout delivery and compliance with global travel rules.

Key Capabilities

• Multi-Rail Recipient Management: Configure beneficiaries for domestic bank clearing (LOCAL), international cross-border transfers (INTERNATIONAL), mobile wallets (MOBILE_MONEY), Hong Kong banking (HK_BANK), and crypto wallets (STABLECOIN).
• Payee Verification & Confirmation of Payee (CoP): Validate UK Sort Code + Account Number combinations against bank directory registries to verify personal vs. business account matches, or resolve Nigerian bank account holder names in real-time before initiating payments.
• Crypto & Stablecoin Wallet Support: Register dedicated custodian, exchange, or self-hosted Ethereum ERC-20 wallets for USDC/USDT settlements with verified custodian identifiers and wallet nicknames.
• Compliance & Sanction Screening: Enforces real-time Out of Risk Appetite (OORA) sanction screening on SWIFT bank codes, mandatory nested client classifications (OPEX, NESTED_CUSTOMER, NESTED_PAYEE) for financial services / crypto companies, and automated AML review pipelines.
• Full Lifecycle Operations: Programmatically create, filter, query, merge-update, and decommission recipient accounts with complete audit trails.

Authentication

All requests to the Atlas Beneficiary Service 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 merchant/tenant verification:

x-api-key: <your_api_key>

Base URLs

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

Common Headers

Header	Value	Required	Description
Authorization	Bearer {token}	Yes	JWT Bearer token returned from authentication
Content-Type	application/json	Yes (for POST/PUT)	Request payload format
Accept	application/json	Yes	Expected response format
x-api-key	string	No	Optional API key for tenant routing

Available Endpoints

Method	Endpoint	Description
POST	/recipients	Create a new beneficiary account across bank, mobile money, or stablecoin rails
GET	/recipients	Retrieve a paginated list of beneficiaries with multi-parameter filtering
GET	/recipients/{recipientId}	Retrieve detailed information for a specific beneficiary by unique ID
PUT	/recipients/{recipientId}	Update an existing beneficiary record with merged fields
DELETE	/recipients/{recipientId}	Remove or deactivate a beneficiary record
POST	/confirm-payee	Verify payee details for UK Confirmation of Payee (CoP) or Nigerian accounts

Beneficiary Onboarding & Verification Workflow

sequenceDiagram
    autonumber
    actor Client as Business Client
    participant Atlas as Atlas Beneficiary API
    participant Verification as Payee Verification Engine
    participant Compliance as AML & Sanctions Engine

    opt Pre-Creation Payee Verification
        Client->>Atlas: POST /confirm-payee (name, sortCode, accountNumber)
        Atlas->>Verification: Query UK CoP / Nigerian NIP Registry
        Verification-->>Atlas: Payee match status (CONFIRMED / MATCH_PERSONAL)
        Atlas-->>Client: 200 OK (Verification details)
    end

    Client->>Atlas: POST /recipients (currencyId, paymentMode, beneficiaryType, bank/wallet details)
    Atlas->>Compliance: Validate SWIFT code against OORA sanction lists & run AML
    Compliance-->>Atlas: Screening passed
    Atlas-->>Client: 200 OK (recipientId, verificationState: approved | pending)

    opt List & Filter Beneficiaries
        Client->>Atlas: GET /recipients?filter=approved&currencyId=4
        Atlas-->>Client: 200 OK (totalCount, items[])
    end

    opt Profile Update
        Client->>Atlas: PUT /recipients/{recipientId} (currencyId, paymentMode, beneficiaryType, updated fields)
        Atlas-->>Client: 200 OK (beneficiarySSI profile)
    end

Next Steps

• Register a new beneficiary account with Create Beneficiary.
• Search and filter recipients with List Beneficiaries.
• Verify UK & Nigerian account details with Confirm Payee Verification.