Lookup - API Documentation

Overview

The Lookup API lets you verify account details before initiating a payment. Use these endpoints to:

Retrieve the list of banks available for bank transfer in a country
Verify a bank account holder's name before sending a bank transfer payout
Verify a mobile money account holder's name before sending a mobile money payout

💡 Best Practice: Always verify recipient account details before initiating payouts to prevent failed transactions and reduce refund delays.

POST Lookup Bank Account

https://genesyspay.com/api/v2/lookup/bank

Verify a bank account number and retrieve the account holder's name. Use this before initiating a bank_transfer payout to ensure the recipient details are correct.

Request Parameters

Parameter	Type	Required	Description
`account_number`	string	Required	Recipient's bank account number (10-digit NUBAN for Nigeria)
`bank_code`	string	Required	Bank code from the Get Banks endpoint (e.g., `058` for GTBank)
`currency`	string	Required	3-letter currency code (e.g., `NGN`)
`country`	string	Optional	2 or 3-letter country code (e.g., `NG`). Helps select the correct provider.

Example Request

curl -X POST https://genesyspay.com/api/v2/lookup/bank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{
    "account_number": "0123456789",
    "bank_code": "058",
    "currency": "NGN",
    "country": "NG"
  }'

Success Response

{
  "status": "success",
  "data": {
    "account_name": "JOHN DOE",
    "account_number": "0123456789"
  }
}

⚠️ Important: Always confirm the account_name with your user before proceeding with the payout. Once a bank transfer is sent it cannot be reversed.

Error Responses

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	422	Missing or invalid parameters
`INVALID_CURRENCY`	422	Currency not supported
`INVALID_COUNTRY`	422	Country not recognized
`INVALID_ARGUMENT`	400	Lookup not supported for this country/currency, or invalid JSON
`PROVIDER_ERROR`	400	Account not found or bank provider returned an error
`INTERNAL_ERROR`	500	An unexpected error occurred

POST Lookup Mobile Money Account

https://genesyspay.com/api/v2/lookup/mobile-money

Verify a mobile money account and retrieve the account holder's name before initiating a mobile money payout.

Request Parameters

Parameter	Type	Required	Description
`phone`	string	Required	Mobile money phone number in international format (e.g., `260773317519`)
`provider`	string	Required	Mobile money provider slug (e.g., `airtel`, `mtn`)
`country`	string	Optional	2 or 3-letter country code (e.g., `ZM`)

Example Request

curl -X POST https://genesyspay.com/api/v2/lookup/mobile-money \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{
    "phone": "260773317519",
    "provider": "airtel",
    "country": "ZM"
  }'

Success Response

{
  "status": "success",
  "data": {
    "account_name": "JOHN DOE",
    "phone": "260773317519",
    "operator": "airtel",
    "country": "ZM"
  }
}

Error Responses

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	422	Missing or invalid parameters
`INVALID_COUNTRY`	422	Country not recognized
`INVALID_ARGUMENT`	400	Lookup not supported for this method or country, or invalid JSON
`PROVIDER_ERROR`	400	Account not found or provider returned an error
`INTERNAL_ERROR`	500	An unexpected error occurred