Merchants

Sub-merchants are the entities (shops, agents, distributors) that transact under your vendor account.

This page was rewritten against the live backend

The previous version documented /api/v1/vendor/merchants plus POST /vendor/merchants/create and POST /vendor/merchants/:merchantId/update. The list endpoint's path was wrong; the create/update endpoints don't exist anywhere in vendor.route.js (or elsewhere in paymentSystem) — merchant onboarding isn't something a vendor calls directly through this API. What follows is read directly from paymentSystem/src/modules/vendors/routes/vendor.route.js.

List Merchants

GET /vendor/merchants?page=1&limit=20
Authorization: Bearer <token>

Query param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 10)

{
  "statusCode": "00",
  "message": "Non-pending merchants",
  "data": [
    {
      "id": "m-uuid",
      "mid": "M001",
      "appid": "100234",
      "legal_name": "Main Street Shop",
      "mstatus": "APPROVED",
      "status": true,
      "riskflag": 1,
      "createdAt": "2026-01-15T10:00:00Z",
      "settlementAccount": { "...": "merchant's settlement account, if configured" },
      "callback": { "...": "merchant's callback config, if configured" }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

There's no search query param on this route (an earlier version of this page implied one) and no per-merchant "get one" endpoint — fetch the full list and filter client-side, or use GET /vendor/me which embeds each merchant's recent transactions inline.

There is no vendor-initiated merchant creation

Onboarding a new merchant under a vendor isn't exposed through this API — vendor.route.js has no POST /merchants/create or similar. If your integration needs to add merchants programmatically, ask your integration contact what onboarding flow applies (likely a separate admin/onboarding process, not a vendor-callable endpoint).