For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook

For webhook delivery mechanics, security verification, and retry behaviour, see Event Notification.

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.

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 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.

Call Supplement Virtual Account Material with the details indicated by materialCode/materialInfoJson to proceed.

Sample data (real captured)

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).

materialInfoJson example value (real captured)

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.

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.

Sample data (real captured — success case)

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) 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.

Sample data (real captured)

Last updated

Was this helpful?