Query Sub-Merchant Details

Application Scenario

The Agent Merchant calls this API to query detailed information of a sub-merchant.

API Endpoint

Environment	URL
Sandbox (Testing)	http://api.testbonuspay.network/agent/subMerchantDetail
Production	https://api.bonuspay.network/agent/subMerchantDetail

Request Parameters

HTTP Header

Field Name	Variable Name	Required	Type	Example Value	Description
Content Language	Content-Language	Optional	String(10)	en	en – English
Signature	Sign	Required	String	—	Request signature
Merchant ID	Partner-Id	Required	String(12)	—	Partner merchant ID

HTTP Body

Field Name	Variable Name	Required	Type	Example Value	Description
Request Time	requestTime	Required	Timestamp(3)	1581450087000	Request timestamp in milliseconds
Business Data	bizContent	Required	SubMerchantGetRequest	—	Business content payload

SubMerchantGetRequest

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant ID	merchantId	Required	String(20)	200000123456	The sub-merchant ID to be queried

Sample Request

Http Header
{
  "Content-Language": "en",
  "Content-Type": "application/json",
  "sign": "Tu3fopHy1opsWVTAk12FSr8KsGMcFTQB0dOH4fPGrG8iKvhcGCsmCr4kOy3CBmv7zXpBNfMxoRW33YPz0Zm6503CDnqxlOZGaOCFSmwnsE01vDzZL489wPj5HEKJ7kk70/muDMiUwJubZoXVtmOGhpvvczJDYIhP/5kpwSkucdkjZwrlp7IGqoFHrgKgZXXieOsUlGJHb9xg+HchtCqCYaOvX+gIK/o88SdgogvGm8NW/N4dzBhnfbwPcC7ue3MO8mwCDkJ/5KavK8TEotSeTvFEyhAvzrd41ccg47SWXZ4UnhvwT06iIYZ67G4Xg24Bc97cQe1XFM9CPd+/8w7uDA==",
  "Partner-Id": "200000344360"
}

Http Body
{
   "body": {
      "merchantId": "200000123456"
   },
   "head": {
      "applyStatus": "SUCCESS",
      "code": "0",
      "msg": "SUCCESS",
      "traceCode": "000000"
   }
}

Response Parameters HTTP Header

Field Name	Variable Name	Required	Type	Example Value	Description
Signature	sign	Required	String	—	Signature for response validation

The body field in the HTTP response is returned only when applyStatus = SUCCESS and code = 0.

HTTP Body

Field Name	Variable Name	Required	Type	Example Value	Description
Response Header	head	Required	ResponseHeader	—	Response header information
Response Body	body	Optional	SubMerchantDetail	—	Returned when query succeeds

SubMerchantDetail

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant ID	merchantId	Required	String(20)	200000123456	Sub-merchant unique ID
Merchant Type	merchantType	Required	String(10)	BUSINESS / PERSONAL	Merchant type
Merchant Name	merchantName	Required	String(256)	Test Merchant	Merchant name
Admin Email	subMerchantAdminEmail	Required	String(256)	[email protected]	Administrator login email
Business Info	businessMerchantData	Conditional	BusinessMerchantData	—	Required when type = BUSINESS
Personal Info	personalMerchantData	Conditional	PersonalMerchantData	—	Required when type = PERSONAL
Contact Info	merchantContactData	Required	MerchantContactData	—	Contact details
Address Info	merchantAddressData	Required	MerchantAddressData	—	Address details

Sample Response

Http Header
{
  "sign": "nDdClX1tAyV3qcX/Epay6AXFNRGSsWd8ysWO9SgwPrNTetSePLA9C39mGp6qRbjJeqXLEnYLwSkBu5eKdtyVX3tflGLiV2kvRjVfYpTCjXdVL2Pcnv2w+ghjHe2jL988iklk7q5AjAgdtXNphpHcTes9pk6W3bVCbvijH6at0fExUtZ91L1LrnPGELT1IJm/lFW3w4KLh0Gxs7FzDPI9RDfUemObNlRzV8kCtkWahwPgs/hBnS69GyYDKN7ihQX2UiLuP239wl6IA+VG/ZZKHPhLs8bbuOS+LKWORIp6jRt+JsAx7c/Ot1RNyOnHKxPRKJ8bVTohEp39yUz/HwG8oA=="
}

Http Body
{
    "body": {
        "merchantId": "200000123456",
        "merchantType": "BUSINESS",
        "merchantName": "Test Merchant",
        "subMerchantAdminEmail": "[email protected]",
        "businessMerchantData": {
            "legalName": "Test Company Ltd",
            "industry": "Technology",
            "webSiteURL": "https://www.example.com",
            "licenseNo": "123456789",
            "licenseExpirationTime": "2025-12-31"
        },
        "merchantContactData": {
            "contactFirstName": "John",
            "contactLastName": "Doe",
            "contactMobile": "[phone]",
            "contactEmail": "[email protected]"
        },
        "merchantAddressData": {
            "country": "AE",
            "city": "Dubai",
            "street": "Test Street"
        }
    },
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "000000"
    }
}

Return Codes

Code	Message	Cause	Resolution
0	SUCCESS	Request succeeded	—
400	INVALID_PARAMETER	Invalid or missing parameter	Adjust request parameters
400	Access denied. You do not have permission.	Caller not authorized to access this sub-merchant	Contact BonusPay support
400	Merchant not found	The specified sub-merchant ID does not exist	Verify the merchant ID

Error Details

Error Message	Cause	Resolution
Merchant not found.	The specified sub-merchant ID does not exist.	Verify the sub-merchant ID.
Access denied. You do not have permission.	Caller not authorized to access the sub-merchant information.	Contact BonusPay support.
invalid parameter: merchantId	Invalid or malformed merchant ID parameter.	Check the merchant ID format.

General Return Code Overview

Code	Message	Cause	Resolution
0	SUCCESS	Request succeeded	—
400	INVALID_PARAMETER	Invalid or missing parameter	Adjust request parameters
403	UNAUTHORIZED	API not authorized or insufficient permissions	Contact BonusPay support
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact BonusPay support
500	SYSTEM_ERROR	Internal system error	Contact BonusPay support / Retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later