Beneficiary - Overview

Introduction

The Beneficiary API enables programmatic management of global payout recipients, supporting individual bank accounts, corporate entities, and mobile money wallets across over 170 countries.

Before initiating payouts, recipients can be validated using the built-in Name Enquiry feature to eliminate failed transactions and reduce compliance exceptions.

Key Features

• Global Recipient Types: Register and manage individual, corporate, and mobile money beneficiaries.
• Pre-Payment Name Enquiry: Validate Nigerian bank account numbers and retrieve official account holder names in real-time before executing transfers.
• Approval Lifecycle: Automatic AML and sanction screening on creation and update. Money Services Businesses (MSB) undergo dedicated verification workflows in live environments.
• Full Lifecycle Management: Create, list, retrieve, update, and delete recipient profiles programmatically.
• Webhook Status Updates: Receive real-time BENEFICIARY_STATUS_CHANGE notifications when recipient verification concludes.

Authentication

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

Authorization: Bearer <your_access_token>

An optional x-api-key header can also be supplied for merchant environment verification.

Base URLs

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

Beneficiary Workflow

graph TD
    A["Client Application"] -->|"POST /profile/v2.1/name-enquiry"| B["Ahrvo Name Enquiry Service"]
    B -->|"Returns Account Name & Verification"| C{"Account Matches?"}
    C -->|"Yes"| D["POST /profile/v2.1/beneficiaries (Create Recipient)"]
    C -->|"No"| E["Flag Discrepancy to Sender"]
    D -->|"Recipient Created (status: approved or pending)"| F["Use beneficiaryId in Payment / Payout"]

Approval Lifecycle

1. Initial Creation: When a beneficiary is registered via POST /banking/ibans/v2/profile/v2.1/beneficiaries, it is assigned an initial status (typically approved or pending verification).
2. Compliance Review: For regulated entities and Money Services Businesses (MSBs), records may enter compliance review to fulfill travel-rule and sanctions requirements.
3. Status Webhooks: Listen for BENEFICIARY_STATUS_CHANGE events to enable immediate execution as soon as a recipient is cleared.

Support

For technical assistance and beneficiary integration questions, contact support@ahrvo.com.