Customers

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"
}

Field	Required	Description
`firstName`	Yes	Customer’s first name
`lastName`	Yes	Customer’s last name
`email`	Yes	Customer’s email address
`password`	Yes	Minimum 6 characters
`phoneNumber`	Yes	Customer’s phone number
`address`	No	Customer’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:

	Merchant	Customer
Who uses it	You (the integrating business)	Your end-users
Credentials	Email + password → access token (JWT) from `POST /auth/login`	Email + password → JWT from `POST /customer/login`
Login endpoint	`POST /auth/login`	`POST /customer/login`
Scope	Merchant operations, wallet management, data access	Wallet self-service, transfers, transaction history

A customer’s JWT token is passed in the Authorization: Bearer header for customer-authenticated requests.

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:

Tier	KYC requirement	Typical limits
`TIER_1`	Basic registration only	Lowest daily limit
`TIER_2`	BVN or NIN verified	Mid-tier daily limit
`TIER_3`	BVN and NIN verified	Highest 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

Get Started

Core Concepts

Guides

Creating a customer account

Verifying the account

Customer authentication vs merchant authentication

Customer tiers (KYC levels)

Upgrading a customer’s tier

Customer profile management

Retrieving a customer profile (merchant)

Retrieving a profile (customer)

Updating a customer profile

Listing and exporting customers

KYC verification guide

Wallets

Funds transfer

Transactions

​Creating a customer account

​Verifying the account

​Customer authentication vs merchant authentication

​Customer login

​Customer tiers (KYC levels)

​Upgrading a customer’s tier

​Customer profile management

​Retrieving a customer profile (merchant)

​Retrieving a profile (customer)

​Updating a customer profile

​Listing and exporting customers

​Related pages

KYC verification guide

Wallets

Funds transfer

Transactions

Creating a customer account

Verifying the account

Customer authentication vs merchant authentication

Customer login

Customer tiers (KYC levels)

Upgrading a customer’s tier

Customer profile management

Retrieving a customer profile (merchant)

Retrieving a profile (customer)

Updating a customer profile

Listing and exporting customers

Related pages