Skip to main content
Customers are the end-users who hold wallets through your merchant integration. When you create a customer account, TagPay provisions a wallet for them with a unique account number. Customers authenticate independently from your merchant account — they have their own login credentials and session tokens.

​
Creating a customer account

Create a customer account by calling POST /customer. This is an unauthenticated endpoint, meaning your customers can self-register through your application’s frontend, or you can call it server-side on their behalf. 
POST https://api.tagpay.ng/v1/customer
Content-Type: application/json

{
  "firstName": "Amaka",
  "lastName": "Ihejirika",
  "email": "[email protected]",
  "password": "securepassword",
  "phoneNumber": "08011223344",
  "address": "12 Marina Street, Lagos"
}
FieldRequiredDescription
firstNameYesCustomer’s first name
lastNameYesCustomer’s last name
emailYesCustomer’s email address
passwordYesMinimum 6 characters
phoneNumberYesCustomer’s phone number
addressNoCustomer’s physical address
After account creation, the customer receives a 6-digit verification code to confirm their email address before they can log in.

​
Verifying the account

POST https://api.tagpay.ng/v1/customer/verification
Content-Type: application/json

{
  "verificationCode": "482910"
}

​
Customer authentication vs merchant authentication

TagPay uses two separate authentication systems:
MerchantCustomer
Who uses itYou (the integrating business)Your end-users
CredentialsEmail + password → access token (JWT) from POST /auth/loginEmail + password → JWT from POST /customer/login
Login endpointPOST /auth/loginPOST /customer/login
ScopeMerchant operations, wallet management, data accessWallet self-service, transfers, transaction history
A customer’s JWT token is passed in the Authorization: Bearer header for customer-authenticated requests.

​
Customer login

POST https://api.tagpay.ng/v1/customer/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "securepassword"
}
Customers can be associated with multiple merchants. Use POST /customer/merchants/switch to switch a customer’s active merchant context.

​
Customer tiers (KYC levels)

Every customer wallet is assigned a KYC tier that determines their transaction limits. There are three tiers:
TierKYC requirementTypical limits
TIER_1Basic registration onlyLowest daily limit
TIER_2BVN or NIN verifiedMid-tier daily limit
TIER_3BVN and NIN verifiedHighest daily limit
The exact limit values are configured per merchant. Contact your account manager or check GET /merchant/limits for your tier limits.

​
Upgrading a customer’s tier

To upgrade a customer’s tier, provide their BVN and/or NIN via the merchant-authenticated upgrade endpoint: 
PATCH https://api.tagpay.ng/v1/customer/tier
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "tier": "TIER_2",
  "bvn": "12345678901"
}
You can also update a customer’s BVN or NIN individually: 
PATCH https://api.tagpay.ng/v1/customer/bvn
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "bvn": "12345678901"
}

PATCH https://api.tagpay.ng/v1/customer/nin
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "nin": "98765432100"
}

​
Customer profile management

​
Retrieving a customer profile (merchant)

Look up a customer by their ID as the merchant: 
GET https://api.tagpay.ng/v1/customer/:customerId
Authorization: Bearer <your-access-token>
Look up a customer by phone number: 
GET https://api.tagpay.ng/v1/customer/phone?phoneNumber=08011223344
Authorization: Bearer <your-access-token>

​
Retrieving a profile (customer)

A logged-in customer can retrieve their own profile: 
GET https://api.tagpay.ng/v1/customer/profile
Authorization: Bearer <customer_token>

​
Updating a customer profile

As the merchant: 
PUT https://api.tagpay.ng/v1/customer/:customerId
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "firstName": "Amaka",
  "lastName": "Ihejirika",
  "address": "5 Victoria Island, Lagos",
  "metadata": { "internalRef": "USR-001" }
}
As the customer (with optional photo upload): 
PATCH https://api.tagpay.ng/v1/customer/profile
Authorization: Bearer <customer_token>
Content-Type: multipart/form-data

​
Listing and exporting customers

Retrieve a paginated list of all customers under your merchant account: 
GET https://api.tagpay.ng/v1/customer?page=1&perPage=20&search=amaka
Authorization: Bearer <your-access-token>
Supported searchBy values: PHONE_NUMBER, ACCOUNT_NUMBER, ACCOUNT_NAME. Export your full customer list as a CSV file: 
GET https://api.tagpay.ng/v1/customer/export
Authorization: Bearer <your-access-token>

KYC verification guide

Verify customer identity with BVN and NIN

Wallets

Understand how customer wallets work

Funds transfer

Send funds to banks and between wallets

Transactions

View and download customer transaction history