Lookup Beneficiary

https://sandboxapi.onbrails.com/api/v1/beneficiaries/lookup (opens in a new tab)

Verify a beneficiary's account details before making a payout. The required parameters vary depending on the destination country and payment method.

Body Parameters

Parameter	Type	Required	Description
country	`string`	✅	ISO country code — `NG` or `GH`
accountNumber	`string`	✅	Account or wallet number
bankName	`string`		Bank name — used to resolve `bankCode` (Nigeria only)
bankCode	`string`		Bank code (required for NG if no `bankName`)
network	`string`		Mobile network — only `MTN` is supported (required for GH)

Supported countries:

Nigeria (NG): Either bankName or bankCode must be provided. If only bankName is given, the bank code is resolved automatically.
Ghana (GH): network is required and must be MTN. Performs a mobile money lookup.

Request

Beneficiaries/Lookup Beneficiary [POST]

curl --request POST \
     --url https://sandboxapi.onbrails.com/api/v1/beneficiaries/lookup \
     --header 'Authorization: Bearer YOUR_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "country": "GH",
       "accountNumber": "0123456789",
       "network": "MTN"
     }'

Responses

🟢 200 - Result example

{
  "status": true,
  "message": "Lookup successful",
  "data": {
    "id": "976cd848-d69f-4914-8558-2a60dda322b1",
    "name": "JOHN DOE",
    "phone": "233123456789",
    "status": "success",
    "network": "MTN",
    "createdAt": "2026-03-27T15:46:40.795Z",
    "reference": "d9f0a2830e79f3104d94",
    "updatedAt": "2026-03-27T15:46:59.133Z",
    "webhookUrl": "https://thorny-waterspout.name/webhook",
    "ussdActionId": "5f702b9b-a33c-4564-8f72-b6effbabc4d6"
  }
}

List Supported Banks [GET]Payouts