> 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/collection-management/webhook.md).

# Webhook

For webhook delivery mechanics, security verification, and retry behaviour, see [Event Notification](/docs/global/global-collections/integration/event-notification.md).

### 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](/docs/global/global-collections/integration/collections/api-supplement-payer-information.md) 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](/docs/global/global-collections/integration/collections/api-supplement-recharge-information.md) API to supply the classification codes and supporting files.

### Sample data

```json
{
  "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=="
}
```