Supplement Virtual Account Material

Endpoint: POST /v2/gc/virtual-accounts/{virtualAccountRequestId}/supplement-material

Description: Submit additional KYC material requested for a virtual account application whose status is INIT.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string	Yes	Merchant-generated unique request ID (UUID recommended). Used for idempotency.
supplementMaterialInfo	object	Yes	Nested object containing the supplementary KYC material details. See supplementMaterialInfo object fields below.
subMerchantId	string	No	NeoX sub-merchant identifier if the virtual account belongs to a sub-merchant.
notifyUrl	string	No	Merchant-hosted callback URL to receive asynchronous material review status notifications.

supplementMaterialInfo object fields:

Field Name	Type	Required	Description
englishName	string	Yes	Full legal English name of the enterprise or account holder.
regAddressEng	string	Yes	Registered address of the enterprise in English.
bizAddressEng	string	Yes	Principal business address of the enterprise in English.
enterpriseSubjectType	string	Yes	Type of enterprise entity (e.g. COMPANY, INSTITUTION).
independentWebsiteUrl	string	No	URL of the merchant's independent website. Required when applyUse is PLATFORM_INDEPENDENT_WEBSITE.

Request sample

{
  "requestId": "f7a8b9c0-1234-4d56-e789-012345678901",
  "supplementMaterialInfo": {
    "englishName": "Acme Trading Limited",
    "regAddressEng": "Suite 1201, Tower B, 88 Queensway, Admiralty, Hong Kong",
    "bizAddressEng": "Suite 1201, Tower B, 88 Queensway, Admiralty, Hong Kong",
    "enterpriseSubjectType": "COMPANY",
    "independentWebsiteUrl": "https://www.acme-trading.com"
  },
  "subMerchantId": "SM-00098761",
  "notifyUrl": "https://merchant.example.com/webhooks/virtual-account"
}

Response

Response Field Descriptions

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

data object fields:

Field Name	Type	Description
materialId	string	Identifier for the submitted material. Use this value to reference the submission if needed.
status	string	Status of the material submission. Enum: WAIT_AUDIT (awaiting review).

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "materialId": "MAT-20240301-00056789",
    "status": "WAIT_AUDIT"
  },
  "message": "Successful",
  "neoResponseId": "c1d2e3f4-5678-4a90-b123-456789012345"
}

Example cURL

curl -X POST "https://{base_url_openapi}/v2/gc/virtual-accounts/{virtualAccountRequestId}/supplement-material" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "requestId": "f7a8b9c0-1234-4d56-e789-012345678901",
    "supplementMaterialInfo": {
      "englishName": "Acme Trading Limited",
      "regAddressEng": "Suite 1201, Tower B, 88 Queensway, Admiralty, Hong Kong",
      "bizAddressEng": "Suite 1201, Tower B, 88 Queensway, Admiralty, Hong Kong",
      "enterpriseSubjectType": "COMPANY",
      "independentWebsiteUrl": "https://www.acme-trading.com"
    },
    "subMerchantId": "SM-00098761",
    "notifyUrl": "https://merchant.example.com/webhooks/virtual-account"
  }'

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.

• Replace {virtualAccountRequestId} with the actual virtual account request ID returned by the Create Virtual Account API.

• This endpoint should be called when the Create Virtual Account API returns status = INIT. The required fields are indicated by materialCode and materialInfoJson in that response.

• The review result is delivered asynchronously via the VIRTUAL_ACCOUNT webhook and can also be polled using Get Supplement Material Status (GET /v2/gc/virtual-accounts/{virtualAccountRequestId}/supplement-material).