Webhook

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

Event data

Field Name	Type	Description
collectionOrderId	string	NeoX identifier of the incoming-funds collection order. Use this to correlate the webhook with your collection records and to call the Collection APIs.
type	string	Event type. Fixed value: "COLLECTION".
merchantCode	string	NeoX merchant code of the account that received the funds.
requestId	string	Unique identifier for this webhook event. Use this for idempotency — de-duplicate handlers on this value to avoid processing the same event twice.
vaNumber	string	Virtual account number that received the incoming funds.
orderType	string	Classification of the incoming collection. Enum: RECHARGE, TRADE_COLLECTION, PLATFORM_COLLECTION.
amount	number	Original incoming amount as notified by the receiving bank.
currency	string	Currency of the incoming funds (e.g. USD, EUR, HKD).
actualAmount	number	Actual settled amount after any deductions or adjustments.
payerAccountName	string	Account name of the party that sent the funds. May be absent when payer information is not yet identified.
payerAccountNum	string	Account number of the party that sent the funds. May be absent when payer information is not yet identified.
payerAccountBankName	string	Name of the payer's bank. May be absent when payer information is not yet identified.
payerAccountSwiftCode	string	SWIFT/BIC code of the payer's bank. May be absent when payer information is not yet identified.
status	string	Current processing status of the collection order. See Order Status Values below.
createdAt	string	Timestamp when the collection order was created (ISO 8601, e.g. "2024-03-02T14:30:00Z").
secureHash	string	Base64-encoded SHA256 hash of all payload fields (excluding secureHash) sorted alphabetically by key and concatenated with the Secret Key configured on the Merchant Portal. Use this to verify the authenticity of the payload.

Order Status Values

Status	Meaning
WAIT_MATCH	The collection order has been received and is waiting to be matched to a trade order.
MATCHED	The collection order has been fully matched to one or more trade orders.
REJ_WAIT_MATCH	A previous match attempt was rejected; the order is awaiting a new match.
PENDING	The collection order is under compliance or bank review.
SUCCESS	The collection order has been fully processed and settled.
CANCEL	The collection order has been cancelled.
REFUND_PROCESS	A refund for this collection order is being processed.
REFUND_SUCCESS	The refund for this collection order has completed successfully.

When a collection arrives without identifiable payer information, call the Supplement Payer Information API to provide the sender's account name, account number, SWIFT code, and payment proof documents. When a recharge-type collection (orderType=RECHARGE) requires supplementary funds-nature documentation, call the Supplement Recharge Information API to supply the classification codes and supporting files.

Sample data

{
  "collectionOrderId": "CO-20240302-000091",
  "type": "COLLECTION",
  "merchantCode": "MC-00012345",
  "requestId": "b7c8d9e0-1234-4fab-a567-890123456789",
  "vaNumber": "HK82000000012345678901",
  "orderType": "TRADE_COLLECTION",
  "amount": 15800.00,
  "currency": "USD",
  "actualAmount": 15800.00,
  "payerAccountName": "Global Retail GmbH",
  "payerAccountNum": "DE89370400440532013000",
  "payerAccountBankName": "Deutsche Bank AG",
  "payerAccountSwiftCode": "DEUTDEDBXXX",
  "status": "WAIT_MATCH",
  "createdAt": "2024-03-02T09:15:00Z",
  "secureHash": "Base64EncodedSHA256HashValue=="
}