Merchants

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:

Mode	Purpose
`SANDBOX`	Testing environment — no real money moves. You can fund the sandbox wallet freely.
`PRODUCTION`	Live 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:

Key	Usage
Public key	Identifies your merchant in client-side or read-only contexts
Private key	Signs 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:

Field	Description
`tier_1_daily_limit`	Maximum daily transaction volume for Tier 1 customers
`tier_2_daily_limit`	Maximum daily transaction volume for Tier 2 customers
`tier_3_daily_limit`	Maximum daily transaction volume for Tier 3 customers
`dailyTransactionLimit`	Overall 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

Get Started

Core Concepts

Guides

Merchant hierarchy

Creating a subsidiary merchant

Account modes

Switching modes

Access keys

Retrieving your keys

Generating new keys

Fee configuration

Creating a fee configuration

Transaction limits

Authentication

Wallets

Webhooks

KYC Verification

​Merchant hierarchy

​Creating a subsidiary merchant

​Account modes

​Switching modes

​Access keys

​Retrieving your keys

​Generating new keys

​Fee configuration

​Creating a fee configuration

​Transaction limits

​Related pages

Authentication

Wallets

Webhooks

KYC Verification

Merchant hierarchy

Creating a subsidiary merchant

Account modes

Switching modes

Access keys

Retrieving your keys

Generating new keys

Fee configuration

Creating a fee configuration

Transaction limits

Related pages