Skip to main content

​
Merchant Management Schemas

API endpoints for onboarding and managing merchants within your provider platform.

​
Endpoints

MethodEndpointDescription
GET/v1/provider/merchantGet specific merchant details
GET/v1/provider/merchantsList merchants with filters
POST/v1/provider/merchantsCreate merchants in batch
PATCH/v1/provider/merchantUpdate merchant information

​
GET /v1/provider/merchant

Retrieve details for a specific merchant under your provider account.

​
Query Parameters

ParameterTypeRequiredDescription
entityIdstringYesMerchant entity identifier

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "data": {
    "id": "string",
    "ref": "string",
    "name": "string",
    "email": "string",
    "phone": "string",
    "code": "string",
    "providerId": "string",
    "userType": "merchant",
    "country": "string",
    "state": "string",
    "website": "string",
    "description": "string",
    "icon": "string",
    "trusted": true,
    "trustLevel": "basic | enhanced | premium"
  }
}

​
GET /v1/provider/merchants

List all merchants under your provider account with optional filters.

​
Query Parameters

ParameterTypeRequiredDescription
idsstring[]NoFilter by merchant IDs
trustedbooleanNoFilter by trust status
limitnumberNoNumber of results to return
offsetnumberNoNumber of results to skip

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "data": {
    "merchants": [
      {
        "id": "string",
        "name": "string",
        "email": "string",
        "trusted": true,
        "trustLevel": "basic | enhanced | premium",
        "createdAt": "string"
      }
    ],
    "total": 1
  }
}

​
POST /v1/provider/merchants

Create multiple merchants in batch for your provider platform.

​
Request Body

{
  "merchants": [
    {
      "name": "string",
      "email": "string",
      "phone": "string",
      "address": "string",
      "website": "string",
      "description": "string"
    }
  ]
}

​
Request Schema

FieldTypeRequiredDescription
merchantsarrayYesArray of merchant objects
merchants[].namestringYesMerchant business name
merchants[].emailstringYesMerchant email address
merchants[].phonestringNoMerchant phone number
merchants[].addressstringNoMerchant business address
merchants[].websitestringNoMerchant website URL
merchants[].descriptionstringNoMerchant description

​
Response Schema

{
  "statusCode": 201,
  "success": true,
  "message": "Merchants created successfully",
  "data": {
    "created": 1,
    "merchants": [
      {
        "id": "string",
        "name": "string",
        "email": "string",
        "providerId": "string"
      }
    ]
  }
}

​
PATCH /v1/provider/merchant

Update information for an existing merchant.

​
Request Body

{
  "entityId": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "website": "string",
  "description": "string",
  "icon": "string"
}

​
Request Schema

FieldTypeRequiredDescription
entityIdstringYesMerchant entity identifier
namestringNoUpdated merchant name
emailstringNoUpdated email address
phonestringNoUpdated phone number
addressstringNoUpdated business address
websitestringNoUpdated website URL
descriptionstringNoUpdated description
iconstringNoUpdated icon URL

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Merchant updated successfully",
  "data": {
    "id": "string",
    "name": "string",
    "email": "string"
  }
}

​
Merchant Schema (Sensitive Fields Hidden)

When retrieving merchant information as a provider, sensitive fields are hidden for security:
FieldTypeDescription
idstringMerchant identifier
refstringMerchant reference code
namestringBusiness name
emailstringContact email
phonestringContact phone
codestringMerchant code
providerIdstringProvider identifier
userTypestringAlways “merchant”
countrystringCountry code
statestringState/region
websitestringWebsite URL
descriptionstringBusiness description
iconstringBusiness icon URL
trustedbooleanTrust status
trustLevelstringTrust level

​
Error Responses

​
400 Bad Request

{
  "statusCode": 400,
  "success": false,
  "message": "Invalid merchant data"
}

​
404 Not Found

{
  "statusCode": 404,
  "success": false,
  "message": "Merchant not found"
}

​
409 Conflict

{
  "statusCode": 409,
  "success": false,
  "message": "Merchant with this email already exists"
}