Beneficiary Validation - PCX Developer Docs

Before disbursing to a new beneficiary, validate their account details to confirm the account exists and retrieve the registered account holder name. This step catches typos in account numbers and reduces failed payouts before they happen.

Nigerian account validation (NIP name enquiry)

Resolve an account number against the Nigerian interbank NIP network to get the account holder name:

curl -X POST https://prod-api.pcxpay.com/v1/payments/bank-validation/validate-nigerian-account \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "0123456789",
    "bank_code": "058",
    "org_id": "org_xxxx"
  }'

Response:

{
  "account_number": "0123456789",
  "account_name": "CHISOM OBI",
  "bank_code": "058",
  "bank_name": "GTBank"
}

Present account_name to the sender for confirmation before proceeding. If the name does not match the intended recipient, do not initiate the payout.

Fetch the Nigerian bank list

Get all supported Nigerian banks and their codes before presenting a bank selector to your users:

GET /payments/bank-validation/nigerian-banks

Use the returned bank_code values in your account validation and beneficiary creation requests.

Fetch banks by country

To present a bank or mobile money network selector for any supported country, fetch the available networks:

curl -X POST https://prod-api.pcxpay.com/v1/externals/networks \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{ "country_code": "NG" }'

Each network in the response includes name, code, and type (bank or momo). Use:

code as bank_code for bank transfer payouts
name as the provider field value in mobile_money_details for mobile money payouts

Recommended validation flow

Fetch banks:       POST /externals/networks { "country_code": "NG" }
User selects bank and enters account number
Validate account:  POST /payments/bank-validation/validate-nigerian-account
Show account_name to the sender for confirmation
Sender confirms → create beneficiary: POST /beneficiaries
Initiate payout:   POST /payments-init/initiate/public-payin

See Bank Payouts for the full payout initiation request.

​Nigerian account validation (NIP name enquiry)

​Fetch the Nigerian bank list

​Fetch banks by country

​Recommended validation flow

Nigerian account validation (NIP name enquiry)

Fetch the Nigerian bank list

Fetch banks by country

Recommended validation flow