Skip to main content
This guide walks you through registering a merchant account, authenticating, creating your first customer wallet, and checking its balance. By the end you will have a working wallet ready to send and receive funds. Base URL: https://api.tagpay.ng/v1
1

Register a merchant account

Send a POST request to /merchant with your business and personal details. The API creates your merchant account and sends a verification code to your email and phone number.
curl -X POST https://api.tagpay.ng/v1/merchant \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Obi",
    "email": "[email protected]",
    "password": "securepassword",
    "phoneNumber": "08012345678",
    "businessName": "Ada Ventures",
    "businessType": "FINANCIAL-SERVICES",
    "sendEmail": true
  }'
Response
{
  "status": true,
  "requireVerification": true,
  "message": "Your verification code has been sent to your email. It expires in 24 hours!"
}
businessType must be one of FINANCIAL-SERVICES or INFORMATION-TECHNOLOGY. Set sendEmail: true to receive the verification code by email; set it to false and the code is returned directly in the response body (useful for testing).
2

Verify your account

Check your email or SMS for the 6-digit verification code. Send it to PUT /merchant/verify to activate your account. This also provisions your sandbox wallet and generates your API keys.
curl -X PUT https://api.tagpay.ng/v1/merchant/verify \
  -H "Content-Type: application/json" \
  -d '{
    "activationCode": "847291"
  }'
Response
{
  "status": true,
  "message": "Your account has been successfully verified."
}
3

Log in to get an access token

Call POST /auth/login with your Base64-encoded email and password. The API returns your user and merchant data in the response body. Your access token is returned in the X-Access-Token response header, and your refresh token is in X-Refresh-Token.
The login endpoint requires email and password to be Base64-encoded before sending. In Node.js: Buffer.from("[email protected]").toString("base64"). In bash: echo -n "[email protected]" | base64.
# Base64-encode credentials first:
# echo -n "[email protected]" | base64  →  YWRhQGV4YW1wbGUuY29t
# echo -n "securepassword" | base64   →  c2VjdXJlcGFzc3dvcmQ=

curl -X POST https://api.tagpay.ng/v1/auth/login \
  -H "Content-Type: application/json" \
  -D - \
  -d '{
    "email": "YWRhQGV4YW1wbGUuY29t",
    "password": "c2VjdXJlcGFzc3dvcmQ="
  }'
Response headers
X-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Refresh-Token: d4f9a2c1e8b3...
Response body
{
  "status": true,
  "data": {
    "id": "usr_01hw...",
    "role": "MERCHANT",
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Obi",
    "mode": "SANDBOX",
    "createdAt": "2026-04-08T10:00:00.000Z",
    "updatedAt": "2026-04-08T10:00:00.000Z"
  },
  "merchant": {
    "id": "mer_01hw...",
    "businessName": "Ada Ventures",
    "businessType": "FINANCIAL-SERVICES",
    "mode": "SANDBOX",
    "review": "PENDING",
    "callbackURL": null,
    "sandboxCallbackURL": null,
    "owner": true,
    "canDebitCustomer": false
  },
  "availableMerchants": [...],
  "hasMultipleMerchants": false
}
Save the X-Access-Token value. You will include it as Authorization: Bearer <token> on every subsequent request.
Tokens expire. When a request returns 401 Unauthorized, use your refresh token to get a new access token. See Authentication for details.
4

Create a customer wallet

Call POST /wallet to provision a wallet for one of your customers. The API verifies the customer’s identity using BVN or NIN before creating the wallet.
curl -X POST https://api.tagpay.ng/v1/wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "firstName": "Emeka",
    "lastName": "Nwosu",
    "phoneNumber": "09087654321",
    "dateOfBirth": "1995-06-15",
    "bvn": "12345678901",
    "tier": "TIER_1"
  }'
Response
{
  "status": true,
  "wallet": {
    "id": "wal_01hw...",
    "currency": "NGN",
    "bankName": "TagPay Microfinance Bank",
    "bankCode": "090XXX",
    "accountName": "Emeka Nwosu",
    "accountNumber": "9012345678",
    "accountReference": "ref_01hw...",
    "bookedBalance": 0,
    "availableBalance": 0
  },
  "customer": {
    "id": "cus_01hw...",
    "firstName": "Emeka",
    "lastName": "Nwosu",
    "phoneNumber": "+2349087654321",
    "tier": "TIER_1",
    "mode": "SANDBOX"
  }
}
You must provide either bvn or nin (or both). The wallet’s status and tier are set automatically based on the verification result. A wallet with a verified BVN or NIN is created as ACTIVE; otherwise it is FROZEN until verified.
5

Check the merchant wallet balance

Call GET /merchant/wallet to retrieve your merchant wallet balance. This is the wallet that holds your operating funds and is charged when you create customer wallets.
curl -X GET https://api.tagpay.ng/v1/merchant/wallet \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response
{
  "status": true,
  "data": {
    "email": "[email protected]",
    "businessName": "Ada Ventures",
    "id": "wal_01hw...",
    "currency": "NGN",
    "mode": "SANDBOX",
    "accountNumber": "9000000001",
    "accountName": "Ada Ventures",
    "bankName": "TagPay Microfinance Bank",
    "bookedBalance": 0,
    "availableBalance": 0
  }
}
In sandbox mode, fund your merchant wallet using POST /merchant/fund-wallet with { "amount": 50000 } to simulate receiving funds without a real bank transfer.

​
What’s next

Now that you have created a wallet, explore what else you can do:

Authentication

Understand token expiry, refresh flow, and access keys

Wallet management

Credit, debit, transfer, and close customer wallets

Webhooks

Receive real-time events for every transaction

API reference

Browse the full endpoint reference