Create New Submerchant

Application Scenario

The Agent Merchant calls this API to create a sub-merchant within the BonusPay service backend.

Once successfully created, the sub-merchant becomes a standard merchant.

The sub-merchant administrator can log in to BonusPay using the registered email address. Upon first login, the administrator will be prompted to set a password.

API Endpoint

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

Request Parameters

HTTP Header

Field Name	Variable Name	Required	Type	Example Value	Description
Content Language	Content-Language	Optional	String(10)	en	en – English (default)
Signature	sign	Required	String	—	Request signature
Merchant ID	Partner-Id	Required	String(12)	—	Unique ID of the partner/merchant

HTTP Body

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

SubMerchantOnboardRequest

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant Type	merchantType	Required	String(10)	BUSINESS / PERSONAL	Merchant type: BUSINESS or PERSONAL
Merchant Name	merchantName	Required	String(256)	Test Merchant	Name of the sub-merchant
Admin Email	subMerchantAdminEmail	Required	String(256)	[email protected]	Login email for the sub-merchant administrator
Business Info	businessMerchantData	Conditional	BusinessMerchantData	—	Required when merchant type is BUSINESS
Personal Info	personalMerchantData	Conditional	PersonalMerchantData	—	Required when merchant type is PERSONAL
Contact Info	merchantContactData	Required	MerchantContactData	—	Merchant contact information
Address Info	merchantAddressData	Required	MerchantAddressData	—	Merchant address information

Sample Request

Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "sign": "IXJI/QicPQotIsIDBcSGIg6jtJUXs1rTuifQFZUNd3KDTl25GKmpYO7OrkaKkTV0shDRitLmkxJCe3Z60zHE2ZSeVczrhwrnmuMG+bX9N22Hw821H6MydsXetYHRnyf5dPbgpmVja582w49grA6jRlVFAVMYdxKJDPSCb2X/IpltvyrLQ1Wt+lqr+fnpYXvyON6/PIZIQIknC8BVddVahxJnaC6HEagvJf6gskz22/DFfPHT1mlMA9pg8qrbh4O7DYZahf8TB3nIzAPc/FHOUZkYYTT2c8m4eLL8740nJVK7D3IOSqSnBAU/iJ2omjPPFvRCCSqzz17pkGsT7AW91w==",
    "Partner-Id": "200000344360"
}

Http Body
{
    "bizContent": {
        "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"
        }
    },
    "requestTime": 1682574418121
}

Response Parameters

HTTP Header

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

---

The body field in the HTTP response body 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 metadata
Response Body	body	Optional	SubMerchantDetail	—	Returned when creation is successful

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	Type of merchant
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	—	Merchant contact details
Address Info	merchantAddressData	Required	MerchantAddressData	—	Merchant address details

Sample Response

Http Header
{
  "sign": "JzWjVQ245trg3p0CyuwUUHN+Ck40q/HDaMvhqueHDP8YHqC/Uw3c9VWCw4gKsNbk+CRShjT+bvKkck8Fc3aAiRK8wIVQz6eu95sPkJgZp5A0P+tfMH/44F+3CrejtbEIkrHdSwhy98Tv9TYs9QFe7Yni/vEJ8P4OU6FZJOi8LGOMF6Nc8+S5qftc7qLA17cNJ7NJYC+EW8suGe/NmGA9c5NMK5BwHTHzXYOjXwXLx8mw4M3hiirl0wtVym3hrOmbkujYZCH56h8uOVF0FbHGu5uoq61NuniJitLLs9qyiEprQzUe8oWsJnHKXeGAgEr//fLXIXgYsRYb7AWoJzs6Eg=="
}

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	Successful request	—
400	INVALID_PARAMETER	Parameter error	Adjust request parameters
403	UNAUTHORIZED	Caller not authorized to create merchant	Contact BonusPay support

Error Details

Error Message	Cause	Resolution
Access denied. You do not have permission.	The caller is not authorized to create merchants.	Contact BonusPay support.
invalid parameter: subMerchantAdminEmail	Invalid admin email format.	Check and provide a valid email format.
invalid parameter: contactEmail	Invalid contact email format.	Check and provide a valid email format.
invalid parameter: type. Valid values are: BUSINESS, PERSONAL.	Missing or incorrect merchant type.	Provide the correct BUSINESS or PERSONAL value.
invalid parameter: websiteURL. Please provide a valid URL.	Invalid website URL format.	Provide a valid URL.
invalid parameter: ownerNationality. It must be a valid ISO 3166-1 alpha-2 country code.	Missing or incorrect nationality code.	Provide a valid ISO 3166-1 two-letter code.
invalid parameter: certType. Valid values are: ID, passport.	Invalid or missing ID type.	Provide the correct document type (ID or Passport).
invalid parameter: country. It must be a valid ISO 3166-1 alpha-2 country code.	Invalid or missing country code.	Provide a valid ISO 3166-1 two-letter country code.
invalid parameter: contactMobile	Invalid contact mobile number format.	Provide a valid phone number format.