Report Sub-Merchant

Endpoint: POST /v2/gc/sub-merchants/report

Description: Report a sub-merchant using a lighter-weight registration flow that does not require full KYC/KYB onboarding documentation.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string	Yes	Merchant-generated unique request ID (UUID recommended). Used for idempotency.
reportType	string	Yes	Type of entity being reported. Enum: SUB_MERCHANT, SUPPLIER.
subMerchantType	string	Yes	Category of the sub-merchant. Enum: PERSON, INDIVIDUAL, ENTERPRISE.
platformMemberId	string	Yes	Merchant's own identifier for this member on their platform.
signedName	string	Yes	Legal name of the sub-merchant as it appears on signed agreements.
countryCode	string	Yes	Country of the sub-merchant in ISO 3166-1 alpha-3 format (e.g. HKG, CHN, SGP).
vouchers	array	Yes	List of supporting document vouchers. See vouchers object item fields below.
businessType	string	No	Primary business type of the sub-merchant (e.g. LOGISTICS_COST, GOODS_PURCHASE, ADVERTISING_SERVICE).
bankInfos	array	No	List of bank account details associated with the sub-merchant.
shopInfos	array	No	List of shop or storefront information associated with the sub-merchant.
notifyUrl	string	No	Merchant-hosted callback URL to receive asynchronous report status notifications.

vouchers object item fields:

Field Name	Type	Required	Description
voucherType	string	Yes	Type of the supporting document (e.g. BUSINESS_LICENSE, ID_CARD).
url	string	Yes	File path of the uploaded voucher document. Use the path returned by the File Upload API (POST /v2/gc/files/upload).

Request sample

{
  "requestId": "d5e6f7a8-2345-4d89-cabc-1122334455ee",
  "reportType": "SUB_MERCHANT",
  "subMerchantType": "ENTERPRISE",
  "platformMemberId": "PLT-MBR-001234",
  "signedName": "Bright Star Commerce Ltd",
  "countryCode": "HKG",
  "vouchers": [
    {
      "voucherType": "BUSINESS_LICENSE",
      "url": "gpt/NETWORK_ACCESS/20240301/biz_license_d5e6f7a8.jpg"
    }
  ],
  "businessType": "GOODS_PURCHASE",
  "bankInfos": [],
  "shopInfos": [],
  "notifyUrl": "https://merchant.example.com/webhooks/report"
}

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
state	number	State of the response.
data	object	Sub-merchant report submission result.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier.

data object fields:

Field Name	Type	Description
requestId	string	Echoes the merchant-supplied requestId.
merchantId	string	NeoX merchant identifier for the parent merchant.
subMerchantId	string	NeoX identifier assigned to the reported sub-merchant.
status	string	Current report status. Enum: ACTIVATED, FAILED, PROCESSING.
beneficiaryId	string	Beneficiary identifier assigned to the sub-merchant, used for payout targeting.

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "requestId": "d5e6f7a8-2345-4d89-cabc-1122334455ee",
    "merchantId": "MC-00012345",
    "subMerchantId": "SM-00098762",
    "status": "PROCESSING",
    "beneficiaryId": "BEN-00056789"
  },
  "message": "Successful",
  "neoResponseId": "e1f2a3b4-66cb-4c23-9d04-5a7890123456"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/sub-merchants/report" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "d5e6f7a8-2345-4d89-cabc-1122334455ee",
    "reportType": "SUB_MERCHANT",
    "subMerchantType": "ENTERPRISE",
    "platformMemberId": "PLT-MBR-001234",
    "signedName": "Bright Star Commerce Ltd",
    "countryCode": "HKG",
    "vouchers": [
      {
        "voucherType": "BUSINESS_LICENSE",
        "url": "gpt/NETWORK_ACCESS/20240301/biz_license_d5e6f7a8.jpg"
      }
    ],
    "businessType": "GOODS_PURCHASE",
    "bankInfos": [],
    "shopInfos": [],
    "notifyUrl": "https://merchant.example.com/webhooks/report"
  }'

Notes

• Requires Bearer token in the Authorization header.

• The Accept-Language header can be used to specify the response language (Support: "vi", "en").

• Use a unique requestId for each request to avoid duplicate submissions.

• The request body must be in JSON format.

• All vouchers[].url values must be path values returned by the File Upload API (POST /v2/gc/files/upload).

• This is an asynchronous operation. The final result is delivered via the SUB_MERCHANT webhook and can also be polled using GET /v2/gc/sub-merchants/report/{requestId}.