Name enquiry

Resolve an NGN account number to its bank-of-record name. Useful for confirming a recipient before submitting a payout — the same resolution we run server-side on every NGN payout.

NGN-only. FX currencies don’t have an equivalent universal lookup.

Resolve account name

POST /v1/name-enquiry

Request

{
  "account_number": "0690000032",
  "bank_code": "044",
  "currency": "NGN",
  "bank_name": "Access Bank"
}

Field	Required	Notes
`account_number`	yes	NUBAN — exactly 10 digits
`bank_code`	yes	CBN 3-digit code
`currency`	yes	Must be `NGN`
`bank_name`	no	Optional hint to bias routing — speeds up the cascade

Behavior

The endpoint walks the routing cascade for the merchant + bank. We try each eligible rail in order until one returns a successful resolve, OR all are exhausted.

Beneficiary cache is checked first: if you’ve previously paid this account successfully, we return the cached name instantly without an upstream call. This makes repeat lookups effectively free.

Live env runs the full cascade: capability-first ordering across rails, falling through to the next if any returns “unresolvable”. Sandbox env uses a single configured resolver (Technest configures the resolver per env; sandbox favours the highest-quota rail to keep integration tests unblocked).

Example

curl https://api.swappr.me/v1/name-enquiry \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "0690000032",
    "bank_code": "044",
    "currency": "NGN"
  }'

const res = await fetch('https://api.swappr.me/v1/name-enquiry', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    account_number: '0690000032',
    bank_code: '044',
    currency: 'NGN',
  }),
});
 
const { resolved_name, source } = await res.json();
console.log(resolved_name); // "ADAEZE BLESSING NWAFOR"

res = requests.post(
    'https://api.swappr.me/v1/name-enquiry',
    headers={
        'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'account_number': '0690000032',
        'bank_code': '044',
        'currency': 'NGN',
    },
)
data = res.json()
print(data['resolved_name'])  # "ADAEZE BLESSING NWAFOR"

Response

{
  "resolved_name": "ADAEZE BLESSING NWAFOR",
  "source": "provider"
}

Field	Notes
`resolved_name`	Bank-of-record name, uppercased
`source`	`beneficiary_cache` (already saved + verified) or `provider` (live lookup)

The response also includes a resolved_by_provider string with an opaque internal identifier of the rail that handled the resolve. This value is unstable — Technest may swap rails without notice. Don’t branch on it; treat it purely as diagnostic information when filing support tickets.

Errors

Code	HTTP	Cause
`unsupported_currency`	400	Only `NGN` supported today
`invalid_account_number`	400	Not 10 digits
`recipient_unresolvable`	422	Every eligible rail returned “unresolvable”
`provider_error`	502	All upstream rails errored (transient) — retry with same idempotency key

Use cases

Confirm before paying — show the resolved name in your UI (“You’re paying: ADAEZE BLESSING NWAFOR”) so the user spots typos.
Validate beneficiary forms — call this endpoint when the user types account_number + bank_code, before allowing them to save.
Reconciliation — verify a name on file matches what the bank says today (names sometimes change after marriage / corrections).

The resolved name is always preferred over merchant-supplied names when creating payouts. The actual POST /v1/payouts flow runs the same resolve internally and overwrites whatever name you submitted with the bank-of-record value — the bank is the source of truth, not the input.

Virtual accounts Webhook endpoints