Skip to main content
TagPay uses a tiered KYC (Know Your Customer) system. Each tier unlocks higher transaction and balance limits. Verifying a customer’s BVN or NIN moves them up tiers, enabling them to do more on your platform.

​
KYC tiers

TierRequirementsWhat it unlocks
TIER_1Basic registration (BVN or NIN at wallet creation)Entry-level limits for everyday transactions
TIER_2BVN linked and verifiedHigher daily transaction limits and balance cap
TIER_3BVN + NIN verifiedMaximum limits — suitable for salary and high-value use cases
Customers start at TIER_1 when their wallet is created. You upgrade them by supplying verified identity data and calling the tier upgrade endpoint.

​
BVN verification

​
Look up a BVN

Use GET /bvn/lookup to retrieve the information associated with a BVN from the NIBSS database.
cURL
curl -X GET "https://api.tagpay.ng/v1/bvn/lookup?bvn=12345678901" \
  -H "Authorization: Bearer <your-token>"
Response
{
  "success": true,
  "data": {
    "bvn": "12345678901",
    "firstName": "AMARA",
    "lastName": "OKAFOR",
    "dateOfBirth": "1990-06-15",
    "phoneNumber": "08012345678"
  }
}

​
Match a BVN against customer data

Use GET /bvn/match to verify that a supplied BVN corresponds to a specific customer. This is useful for confirming identity before processing high-value operations.
cURL
curl -X GET "https://api.tagpay.ng/v1/bvn/match?bvn=12345678901&firstName=Amara&lastName=Okafor&dateOfBirth=1990-06-15" \
  -H "Authorization: Bearer <your-token>"
Response
{
  "success": true,
  "data": {
    "match": true,
    "score": 100
  }
}

​
Linking a BVN to a customer

Once you’ve verified a customer’s BVN, associate it with their account using PATCH /customer/bvn.
cURL
curl -X PATCH https://api.tagpay.ng/v1/customer/bvn \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "bvn": "12345678901"
  }'
Response
{
  "success": true,
  "data": {
    "customerId": "cus_abc123",
    "bvnLinked": true
  }
}

​
Linking a NIN to a customer

Associate a National Identification Number (NIN) with a customer account using PATCH /customer/nin.
cURL
curl -X PATCH https://api.tagpay.ng/v1/customer/nin \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "nin": "98765432101"
  }'

​
Upgrading a customer’s KYC tier

After linking the required identity documents, upgrade a customer to a higher tier using PATCH /customer/tier.
1

Verify identity documents

Confirm the customer’s BVN and/or NIN are linked to their account. Tier upgrades require the documents to be present and verified.
2

Submit the tier upgrade request

cURL
curl -X PATCH https://api.tagpay.ng/v1/customer/tier \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "tier": "TIER_2"
  }'
Response
{
  "success": true,
  "data": {
    "customerId": "cus_abc123",
    "previousTier": "TIER_1",
    "currentTier": "TIER_2",
    "updatedAt": "2026-04-08T10:00:00.000Z"
  }
}
FieldTypeRequiredDescription
customerIdstringYesThe customer to upgrade
tierstringYesTarget tier: TIER_1, TIER_2, or TIER_3
Attempting to upgrade a customer to TIER_3 without a linked NIN will fail. Ensure all required documents are in place before submitting the request.

​
Phone number verification

Phone number verification adds an extra layer of identity assurance, particularly useful before upgrading to TIER_2 or TIER_3. The flow is two-step: start the verification to trigger an OTP, then complete it with the code the customer receives.

​
Start phone verification

cURL
curl -X POST https://api.tagpay.ng/v1/customer/verification/phone/start \
  -H "Authorization: Bearer <your-customer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "08012345678"
  }'
Response
{
  "success": true,
  "message": "OTP sent to 08012345678"
}
The /customer/verification/phone/start and /customer/verification/phone/complete endpoints use a customer token, not a merchant token. The customer must be authenticated on your platform before initiating phone verification.

​
Complete phone verification

Once the customer receives and enters their OTP, submit it to complete the verification:
cURL
curl -X POST https://api.tagpay.ng/v1/customer/verification/phone/complete \
  -H "Authorization: Bearer <your-customer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": "123456"
  }'
Response
{
  "success": true,
  "data": {
    "phoneVerified": true,
    "verifiedAt": "2026-04-08T10:02:00.000Z"
  }
}
The following flow shows how to take a customer from initial registration to TIER_2:
1

Create wallet

Call POST /wallet with the customer’s BVN or NIN. The customer starts at TIER_1.
2

Look up and verify BVN

Call GET /bvn/lookup to retrieve the BVN data, then GET /bvn/match to confirm it matches the customer’s declared identity.
3

Link the BVN

Call PATCH /customer/bvn to associate the verified BVN with the customer account.
4

Verify phone number

Trigger POST /customer/verification/phone/start, then complete with POST /customer/verification/phone/complete using the OTP.
5

Upgrade to TIER_2

Call PATCH /customer/tier with "tier": "TIER_2". The customer now has access to higher limits.
To reach TIER_3, repeat steps 2–4 for the customer’s NIN, link it using PATCH /customer/nin, then call PATCH /customer/tier with "tier": "TIER_3".