> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/virtual-accounts/webhook.md). # Webhook For webhook delivery mechanics, security verification, and retry behaviour, see [Event Notification](/docs/global/global-collections/integration/event-notification.md). {% hint style="info" %} **The event type sent is `VA_CREATION_RESULT`**, which carries both the success and failure case (distinguished by its `status` field). Do not match on `VA_CREATED`/`VA_CREATION_FAILED` — those names do not correspond to anything actually sent. {% endhint %} This page documents 3 event types related to the virtual account lifecycle: `VA_SUPPLEMENT_REQUIRED`, `VA_CREATION_RESULT`, and `VA_MATERIAL_SUPPLEMENT`. All are delivered to the `webhookUrl` supplied in the original [Create Virtual Account](/docs/global/global-collections/integration/virtual-accounts/api-create-virtual-account.md) request (or the merchant's configured default webhook URL if none was supplied for that request). ## VA\_SUPPLEMENT\_REQUIRED Sent when a virtual account application requires supplementary KYC material before it can proceed. ### Event data | Field Name | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string | Event type. Fixed value: `VA_SUPPLEMENT_REQUIRED`. | | id | string | The virtual account's NeoX `id`, as returned by Create Virtual Account. | | requestId | string | The `requestId` supplied in the original Create Virtual Account request. | | subMerchantId | string | NeoX identifier of the sub-merchant this virtual account belongs to, if applicable. | | materialCode | string | Code indicating the type of supplementary material required (e.g. `M003`). | | materialInfoJson | string | JSON-encoded array string describing the specific fields that must be supplied. Each element has `paramName`, `paramTitle`, `valueRequired`, and a `validatorRuleList` array of `{msg, datatype, len/length}` validation rules. | | extData | string | Reserved for future use. Currently always the literal string `"{}"`. | | secureHash | string | Base64-encoded SHA-256 signature. See [Event Notification](/docs/global/global-collections/integration/event-notification.md). | {% hint style="warning" %} `materialInfoJson`'s per-field validation rules are nested under **`validatorRuleList`**, an array of rule objects. {% endhint %} Call [Supplement Virtual Account Material](/docs/global/global-collections/integration/virtual-accounts/api-supplement-virtual-account-material.md) with the details indicated by `materialCode`/`materialInfoJson` to proceed. ### Sample data (real captured) ```json { "type": "VA_SUPPLEMENT_REQUIRED", "id": "ff2f112d687a4dc98ec33788c8e63b60", "requestId": "1785407163122", "subMerchantId": "10000002", "materialCode": "M003", "materialInfoJson": "[{\"paramName\":\"platformOrApplicationAccountRegisterName\",\"paramTitle\":\"Platform/Application Account Registration Name\",\"valueRequired\":true,\"validatorRuleList\":[{\"msg\":\"Length must be between 1 and 60 characters\",\"len\":\"{\\\"min\\\":1,\\\"max\\\":60}\",\"length\":\"{\\\"min\\\":1,\\\"max\\\":60}\"},{\"msg\":\"Please enter English\",\"datatype\":\"^[A-Za-z/\\\\-?:()., '+]+$\",\"msgEn\":\"Please enter English\"}]},{\"paramName\":\"platformOrApplicationUrl\",\"paramTitle\":\"Platform/Application URL\",\"valueRequired\":true,\"validatorRuleList\":[{\"msg\":\"Length must be between 1 and 200 characters\",\"len\":\"{\\\"min\\\":1,\\\"max\\\":200}\",\"length\":\"{\\\"min\\\":1,\\\"max\\\":200}\",\"msgEn\":\"maxLength 200\"},{\"msg\":\"The format is incorrect. Please start with http:// or https://\",\"datatype\":\"^(http|https)://.*$\",\"msgEn\":\"The format is incorrect. Please start with http:// or https://\"}]}]", "extData": "{}", "secureHash": "YbPgt0RkHTwsUhoZBPkIlaS/rkdC/wwqBuc7dWl1aHU=" } ``` ### `materialInfoJson` structure
materialInfoJson structure * Type: `string(256)`, containing a JSON array string. * Purpose: Returns the exact supplemental fields that must be provided via the Supplement Virtual Account Material API. Each element in the parsed JSON array may include: | Key | Meaning | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `paramName` | Supplementary field name/key. | | `paramTitle` | Human-readable field meaning/title. | | `valueRequired` | Whether the field is mandatory. | | `validatorRuleList` | Array of validation rule objects, each with `msg` (error message), `datatype` (regex), and `len`/`length` (JSON text with `min`/`max`). | {% hint style="warning" %} Each entry's validation rules are nested under **`validatorRuleList`**, an array of rule objects, not a single object. {% endhint %} #### `materialInfoJson` example value (real captured) ```json [ { "paramName": "platformOrApplicationAccountRegisterName", "paramTitle": "Platform/Application Account Registration Name", "valueRequired": true, "validatorRuleList": [ {"msg": "Length must be between 1 and 60 characters", "len": "{\"min\":1,\"max\":60}", "length": "{\"min\":1,\"max\":60}"}, {"msg": "Please enter English", "datatype": "^[A-Za-z/\\-?:()., '+]+$", "msgEn": "Please enter English"} ] }, { "paramName": "platformOrApplicationUrl", "paramTitle": "Platform/Application URL", "valueRequired": true, "validatorRuleList": [ {"msg": "Length must be between 1 and 200 characters", "len": "{\"min\":1,\"max\":200}", "length": "{\"min\":1,\"max\":200}", "msgEn": "maxLength 200"}, {"msg": "The format is incorrect. Please start with http:// or https://", "datatype": "^(http|https)://.*$", "msgEn": "The format is incorrect. Please start with http:// or https://"} ] } ] ```
## VA\_CREATION\_RESULT Sent when a virtual account application reaches a terminal outcome — either the account is successfully opened (carrying the assigned account number and bank details), or the application is rejected. ### Event data — success (`status: "APPROVED"`) | Field Name | Type | Description | | ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------ | | type | string | Event type. Fixed value: `VA_CREATION_RESULT`. | | id | string | The virtual account's NeoX `id`. | | requestId | string | The `requestId` supplied in the original Create Virtual Account request. | | subMerchantId | string | NeoX identifier of the sub-merchant this virtual account belongs to, if applicable. | | vaNo | string | Assigned virtual account number. | | vaName | string | Assigned virtual account name. | | currency | string | Currency or comma-separated currencies of the virtual account. | | openBankName | string | Name of the bank where the virtual account is held. | | openBankSwiftCode | string | SWIFT/BIC code of the bank where the virtual account is held. | | openBankAddress | string | Address of the bank where the virtual account is held. | | openBankCode | string | Code of the bank where the virtual account is held. | | openBankBranchCode | string | Branch code of the bank where the virtual account is held. | | localBankRouteNo | string | Local bank routing number (e.g. ABA for the US, sort code for the UK). | | status | string | Fixed value: `APPROVED`. | | extData | string | Reserved for future use. Currently always the literal string `"{}"`. | | secureHash | string | Base64-encoded SHA-256 signature. See [Event Notification](/docs/global/global-collections/integration/event-notification.md). | ### Event data — failure (`status: "REJECTED"`) | Field Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | | type | string | Event type. Fixed value: `VA_CREATION_RESULT`. | | id | string | The virtual account's NeoX `id`. | | requestId | string | The `requestId` supplied in the original request. | | subMerchantId | string | Sub-merchant identifier, if applicable. | | status | string | Fixed value: `REJECTED`. | | errCode | string | Error code describing the failure reason. | | errMsg | string | Human-readable failure description. | | extData | string | Reserved for future use. | | secureHash | string | Base64-encoded SHA-256 signature. See [Event Notification](/docs/global/global-collections/integration/event-notification.md). | ### Sample data (real captured — success case) ```json { "type": "VA_CREATION_RESULT", "id": "ff2f112d687a4dc98ec33788c8e63b60", "requestId": "1785407163122", "subMerchantId": "10000002", "vaNo": "5408441793000005", "vaName": "VA AUTO MOCK IT SUPPORT", "currency": "USD,EUR,HKD,CNH,GBP,CAD,AUD,JPY,SGD", "openBankName": "MOCK VIRTUAL BANK", "openBankSwiftCode": "MOCKHKHH851", "openBankAddress": "MOCK ADDRESS, FOR IT SUPPORT TEST ONLY", "openBankCode": "560678", "openBankBranchCode": "009951", "localBankRouteNo": "059077418", "status": "APPROVED", "extData": "{}", "secureHash": "WiNgL3rOsg1YW5ewFNYni0+fmlqxKcMvDK4NHsWeiIc=" } ``` No real captured failure-case sample is available yet — field names above are derived from code. ## VA\_MATERIAL\_SUPPLEMENT Sent when previously-submitted supplementary material (via [Supplement Virtual Account Material](/docs/global/global-collections/integration/virtual-accounts/api-supplement-virtual-account-material.md)) has been reviewed. ### Event data | Field Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string | Event type. Fixed value: `VA_MATERIAL_SUPPLEMENT`. | | id | string | The virtual account's NeoX `id`. | | requestId | string | The `requestId` of the supplement submission being reviewed. | | subMerchantId | string | NeoX identifier of the sub-merchant this virtual account belongs to, if applicable. | | materialId | string | Identifier of the reviewed material submission. | | status | string | Review outcome. Observed value: `PASS`. (A rejection value is expected to exist but was not captured in a real sample — do not assume its exact spelling, e.g. `REJECT` vs `FAIL`, without confirming.) | | auditOpinion | string | Reviewer's comments/code. | | extData | string | Reserved for future use. Currently always the literal string `"{}"`. | | secureHash | string | Base64-encoded SHA-256 signature. See [Event Notification](/docs/global/global-collections/integration/event-notification.md). | ### Sample data (real captured) ```json { "type": "VA_MATERIAL_SUPPLEMENT", "requestId": "1785407870418", "id": "ff2f112d687a4dc98ec33788c8e63b60", "subMerchantId": "10000002", "materialId": "01785408435640000001", "status": "PASS", "auditOpinion": "1", "extData": "{}", "secureHash": "3HTG1xC0PHCPfYAqZ0/LUh3VlRIA/AF91xg/PrkpQgU=" } ```