Skip to main content
A merchant is a business entity that integrates with TagPay to provide wallet and payment services to its customers. When you register with TagPay, you become a main merchant. Your account is the root of your integration — it holds its own wallet, owns its API keys, and governs all subsidiary merchants you create beneath it.

​
Merchant hierarchy

TagPay supports a two-level merchant structure:
  • Main merchant — Your primary business account. It authenticates to the API, manages access keys, and can create subsidiary merchants.
  • Subsidiary merchant — A child merchant created and owned by a main merchant. Subsidiaries operate independently but inherit configuration (charges, limits) from the parent unless overridden.
Use subsidiaries to represent different business units, product lines, or sub-brands that need separate wallet pools and transaction histories.
Only a main merchant can create subsidiary merchants. Subsidiaries cannot themselves create further subsidiaries.

​
Creating a subsidiary merchant

Send a POST request to /merchant/subsidiary. You must be authenticated as a main merchant. 
POST https://api.tagpay.ng/v1/merchant/subsidiary
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "firstName": "Amara",
  "lastName": "Obi",
  "email": "[email protected]",
  "password": "securepassword",
  "phoneNumber": "08012345678",
  "businessName": "Acme Logistics",
  "businessType": "FINANCIAL-SERVICES",
  "bvn": "12345678901",
  "charges": {
    "walletToWalletTransfer": 10,
    "walletReservationCharge": 50,
    "transferCharges": {
      "max5000": 10,
      "max50000": 25,
      "min50000": 50
    },
    "tier_1_daily_limit": 50000,
    "tier_2_daily_limit": 200000,
    "tier_3_daily_limit": 500000
  }
}
Once created, the subsidiary gets its own wallet and API credentials in sandbox mode.

​
Account modes

Every merchant account operates in one of two modes:
ModePurpose
SANDBOXTesting environment — no real money moves. You can fund the sandbox wallet freely.
PRODUCTIONLive environment — real transactions. Requires completed KYC and account activation.

​
Switching modes

Switch between modes by sending a POST request to /merchant/account-mode. Your account must have a review status of ENABLED before you can switch to PRODUCTION. 
POST https://api.tagpay.ng/v1/merchant/account-mode
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "mode": "PRODUCTION"
}
Attempting to switch to PRODUCTION before your KYC is approved returns an error: “Your LIVE environment have not been activated.”

​
Access keys

TagPay issues two keys per merchant per mode:
KeyUsage
Public keyIdentifies your merchant in client-side or read-only contexts
Private keySigns webhook payloads — use this as the HMAC secret to verify incoming webhook signatures. Keep it secret.
Never expose your private key in client-side code, public repositories, or logs. Treat it like a password.

​
Retrieving your keys

You can retrieve your key from the dashboard

​
Generating new keys

If your private key is compromised, generate a new key pair immediately. The old keys are invalidated.
Generating new keys invalidates the old private key immediately. Update any webhook verification logic that uses the old key.

​
Fee configuration

TagPay lets you configure how fees are applied to transactions processed under your merchant account. You can define fees as a fixed amount or a percentage, and set minimum and maximum caps. Supported transaction types for fee configuration:
  • BANK_TRANSFER
  • CUSTOMER_BANK_TRANSFER
  • WALLET_TO_WALLET_TRANSFER
  • WALLET_RESERVATION
  • BATCH_BANK_TRANSFER
  • BATCH_WALLET_TRANSFER

​
Creating a fee configuration

POST https://api.tagpay.ng/v1/merchant/fee-config
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "transactionType": "BANK_TRANSFER",
  "feeType": "fixed",
  "feeValue": 50,
  "minFee": 10,
  "maxFee": 500,
  "isActive": true
}
Use GET /merchant/fee-config to list all active fee configurations and POST /merchant/calculate-fees to preview what a fee will be for a given amount before committing to a transaction.

​
Transaction limits

Limits control the maximum amount a merchant or its customers can transact within a period. Limits are scoped per tier:
FieldDescription
tier_1_daily_limitMaximum daily transaction volume for Tier 1 customers
tier_2_daily_limitMaximum daily transaction volume for Tier 2 customers
tier_3_daily_limitMaximum daily transaction volume for Tier 3 customers
dailyTransactionLimitOverall daily limit across all transactions
Retrieve your current limits with GET /merchant/limits. Review global platform limits with GET /merchant/limits/global.

Authentication

Get access tokens and authenticate API requests

Wallets

Understand how merchant and customer wallets work

Webhooks

Configure callback URLs and subscribe to events

KYC Verification

Complete the KYC process and go live