Confirm Payee Verification (Atlas)

Overview

The POST /banking/ibans/v2/confirm-payee endpoint validates payee details before payment initiation to prevent Authorized Push Payment (APP) fraud and incorrect bank transfers. It supports two primary clearing schemes:

1. UK Confirmation of Payee (CoP): Validates Sort Code, Account Number, Payee Name, and Account Type (PERSONAL or BUSINESS) against the UK Open Banking directory. Returns match verification identifiers:
   • CONFIRMED: Exact match between provided name and the registered account holder name.
   • REJECTED: No match found.
   • FAILED: Directory or processing lookup failed.
   • detailedStatusIdentifier: E.g., MATCH_PERSONAL if the name matches a personal account when BUSINESS was requested.
2. Nigeria Bank Verification: Validates Nigerian bank code and 10-digit NUBAN account number via NIBSS, returning the verified account holder name (accountName).

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/confirm-payee
• 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

Request Body

The request payload accepts either UK CoP parameters or Nigerian bank validation parameters:

Schema 1: UK Confirmation of Payee (CoP)

Field	Type	Required	Description
type	string	Yes	Verification scheme type (e.g. COP).
name	string	Yes	Beneficiary account name to verify (1–140 characters).
accountType	string (enum)	Yes	Account classification: PERSONAL or BUSINESS.
sortCode	string	Yes	Exactly 6-digit UK bank branch sort code (e.g. 200000).
accountNumber	string	Yes	Exactly 8-digit UK bank account number (e.g. 12345678).

Schema 2: Nigeria Account Verification

Field	Type	Required	Description
bankCountry	string	Yes	Country code: NG.
bankCode	string	Yes	3-digit or 6-digit Nigerian bank code (e.g. 058 for GTBank).
accountNumber	string	Yes	10-digit NUBAN account number.

Request Examples

1. UK Confirmation of Payee

{
  "type": "COP",
  "name": "Devika Sharma",
  "accountType": "PERSONAL",
  "sortCode": "123456",
  "accountNumber": "12345678"
}

2. Nigerian Account Verification

{
  "bankCountry": "NG",
  "bankCode": "058",
  "accountNumber": "0123456789"
}

Response

UK CoP Success Response (200 OK)

{
  "actualPayeeName": "Devika Sharma",
  "status": {
    "identifier": "CONFIRMED",
    "detailedStatusIdentifier": "MATCH_PERSONAL",
    "reason": "Name is a match to the registered account name."
  }
}

Nigeria Success Response (200 OK)

{
  "bankCountry": "NG",
  "bankCode": "058",
  "accountNumber": "0123456789",
  "accountName": "JOHN DOE ENTERPRISES"
}

Response Fields

Field	Type	Description
actualPayeeName	string	Name of the registered payee retrieved from bank records (UK).
status.identifier	string	CoP status: CONFIRMED, FAILED, or REJECTED.
status.detailedStatusIdentifier	string	Specific status detail (e.g., MATCH_PERSONAL, MATCH_BUSINESS, CLOSE_MATCH).
status.reason	string	Explanation of the verification outcome.
accountName	string	Account title registered on the Nigerian Inter-Bank Settlement System (NIBSS).

Error Responses

• 400 Bad Request: Invalid Sort Code / NUBAN length or missing mandatory fields.
• 401 Unauthorized: Missing or expired Bearer token.
• 404 Not Found: Account not found in directory.
• 500 Internal Server Error: Verification network gateway error.

Code Examples

cURL (UK CoP)

curl -X POST "https://gateway.ahrvo.network/banking/ibans/v2/confirm-payee" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "type": "COP",
    "name": "Devika Sharma",
    "accountType": "PERSONAL",
    "sortCode": "123456",
    "accountNumber": "12345678"
  }'

Python (Nigeria Verification)

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/confirm-payee"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "bankCountry": "NG",
    "bankCode": "058",
    "accountNumber": "0123456789"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print("Verified Account Name:", data.get("accountName"))

JavaScript (Node.js - UK CoP)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/confirm-payee';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};

const payload = {
  type: 'COP',
  name: 'Devika Sharma',
  accountType: 'PERSONAL',
  sortCode: '123456',
  accountNumber: '12345678'
};

axios.post(url, payload, { headers })
  .then(res => console.log('Verification Status:', res.data.status))
  .catch(err => console.error(err.response ? err.response.data : err.message));

Interactive API Explorer