Renew Sub-Merchant Qualification

Endpoint: POST /v2/gc/sub-merchants/qualification-renewals

Description: Submit a renewal request for an expired or expiring qualification document belonging to an active sub-merchant.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string	Yes	Merchant-generated unique request ID (UUID recommended). Used for idempotency.
subMerchantId	string	Yes	NeoX identifier of the sub-merchant whose qualification is being renewed.
inspectionNoticeId	string	Yes	Inspection notice identifier issued by the platform indicating the document that requires renewal.
certificateSubjectType	string	Yes	Type of entity the certificate belongs to (e.g. COMPANY, INDIVIDUAL).
certNo	string	Yes	Certificate or document number of the qualification being renewed.
fileType	string	Yes	Type of the qualification document being submitted (e.g. BUSINESS_LICENSE, PASSPORT).
expireDate	date string	Yes	New expiry date of the renewed qualification document (YYYY-MM-DD).
frontPath	string	Yes	File path of the front image of the qualification document. Use the path returned by the File Upload API (POST /v2/gc/files/upload).
backPath	string	No	File path of the back image of the qualification document. Use the path returned by the File Upload API (POST /v2/gc/files/upload).
notifyUrl	string	No	Merchant-hosted callback URL to receive asynchronous renewal status notifications.

Request sample

{
  "requestId": "f8b1c2d3-3456-4e90-dbcd-2233445566ff",
  "subMerchantId": "SM-00098761",
  "inspectionNoticeId": "INS-20240601-00042",
  "certificateSubjectType": "COMPANY",
  "certNo": "BR-20240001",
  "fileType": "BUSINESS_LICENSE",
  "expireDate": "2027-06-30",
  "frontPath": "gpt/NETWORK_ACCESS/20240601/license_front_f8b1c2d3.jpg",
  "backPath": "gpt/NETWORK_ACCESS/20240601/license_back_f8b1c2d3.jpg",
  "notifyUrl": "https://merchant.example.com/webhooks/qualification"
}

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
state	number	State of the response.
data	object	Qualification renewal 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 of the sub-merchant whose qualification is being renewed.
inspectionNoticeId	string	Echoes the inspectionNoticeId provided in the request.
status	string	Current renewal status. Enum: PROCESS, SUCCESS, FAILED.
errCode	string	Error code if the renewal failed; empty when not applicable.
errMsg	string	Human-readable error description if the renewal failed; empty otherwise.

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "requestId": "f8b1c2d3-3456-4e90-dbcd-2233445566ff",
    "merchantId": "MC-00012345",
    "subMerchantId": "SM-00098761",
    "inspectionNoticeId": "INS-20240601-00042",
    "status": "PROCESS",
    "errCode": "",
    "errMsg": ""
  },
  "message": "Successful",
  "neoResponseId": "a4b5c6d7-88ed-4e45-bf26-7c9012345678"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/sub-merchants/qualification-renewals" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "f8b1c2d3-3456-4e90-dbcd-2233445566ff",
    "subMerchantId": "SM-00098761",
    "inspectionNoticeId": "INS-20240601-00042",
    "certificateSubjectType": "COMPANY",
    "certNo": "BR-20240001",
    "fileType": "BUSINESS_LICENSE",
    "expireDate": "2027-06-30",
    "frontPath": "gpt/NETWORK_ACCESS/20240601/license_front_f8b1c2d3.jpg",
    "backPath": "gpt/NETWORK_ACCESS/20240601/license_back_f8b1c2d3.jpg",
    "notifyUrl": "https://merchant.example.com/webhooks/qualification"
  }'

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 renewal request to avoid duplicate submissions.

• The request body must be in JSON format.

• Both frontPath and backPath must be path values returned by the File Upload API (POST /v2/gc/files/upload) before calling this endpoint.

• The inspectionNoticeId is provided by the platform in the inspection notice alerting you that a qualification document is expiring.

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