> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagpay.ng/llms.txt
> Use this file to discover all available pages before exploring further.
# Merchants
> Understand merchant accounts, KYC requirements, access keys, and how to manage subsidiary merchants in TagPay.
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.
```bash theme={null}
POST https://api.tagpay.ng/v1/merchant/subsidiary
Authorization: Bearer
Content-Type: application/json
```
```json theme={null}
{
"firstName": "Amara",
"lastName": "Obi",
"email": "amara@acme-logistics.ng",
"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`.
```bash theme={null}
POST https://api.tagpay.ng/v1/merchant/account-mode
Authorization: Bearer
Content-Type: application/json
```
```json theme={null}
{
"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
```bash theme={null}
POST https://api.tagpay.ng/v1/merchant/fee-config
Authorization: Bearer
Content-Type: application/json
```
```json theme={null}
{
"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`.
***
## Related pages
Get access tokens and authenticate API requests
Understand how merchant and customer wallets work
Configure callback URLs and subscribe to events
Complete the KYC process and go live