> 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/payout-requests/webhook.md).

# Webhook

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

This page documents 2 event types delivered to the `webhookUrl` supplied in the original [Create Payout Request](/docs/global/global-collections/integration/payout-requests/api-create-payout-request.md): `PAYMENT_INITIAL` and `PAYMENT_RESULT`.

## PAYMENT\_INITIAL

Sent when a payout request is accepted and initiated for processing.

### Event data

| Field Name       | Type   | Description                                                                                                                    |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| type             | string | Event type. Fixed value: `PAYMENT_INITIAL`.                                                                                    |
| requestId        | string | The `requestId` supplied in the original Create Payout Request.                                                                |
| serialNum        | string | Platform serial number assigned to this payout transaction.                                                                    |
| amount           | number | Payout amount in the sending currency (`currency`).                                                                            |
| currency         | string | ISO 4217 currency code of the payout (sending side).                                                                           |
| creditedAmount   | number | Amount expected to be credited to the beneficiary after conversion and fees.                                                   |
| creditedCurrency | string | ISO 4217 currency code of the credited (receiving) amount.                                                                     |
| fxRate           | number | FX rate applied to this payout, if a currency conversion occurred.                                                             |
| feeAmount        | number | Total fee charged for this payout in `feeCurrency`.                                                                            |
| feeCurrency      | string | ISO 4217 currency code in which the fee is denominated.                                                                        |
| status           | string | Initial processing status assigned to the payout by the settlement handler at initiation time.                                 |
| createdAt        | string | Timestamp when the payout request was created (ISO 8601).                                                                      |
| completedAt      | string | Timestamp when the payout reached this state (ISO 8601).                                                                       |
| msg              | string | Human-readable status message.                                                                                                 |
| code             | string | Result or status code accompanying `status`.                                                                                   |
| 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

```json
{
  "type": "PAYMENT_INITIAL",
  "requestId": "b2c3d4e5-2222-3333-4444-bbccddeeff00",
  "serialNum": "SN2024081500112233",
  "amount": 5000.00,
  "currency": "USD",
  "creditedAmount": 36407.50,
  "creditedCurrency": "CNH",
  "fxRate": 7.2815,
  "feeAmount": 15.00,
  "feeCurrency": "USD",
  "status": "PROCESSING",
  "createdAt": "2024-08-15T09:00:00Z",
  "completedAt": "",
  "msg": "Payout accepted and submitted for processing",
  "code": "0",
  "extData": "{}",
  "secureHash": "Base64EncodedSHA256HashValue=="
}
```

## PAYMENT\_RESULT

Sent when a payout request reaches a terminal outcome.

{% hint style="info" %}
`status` here is the **remapped** value used by NeoX, not the provider's raw status. Mapping: `SUCCESS → SUCCESS`, `FAILED → FAILED`, `REFUND → REFUNDED`, `CANCEL → CANCELLED`.
{% endhint %}

### Event data

| Field Name       | Type   | Description                                                                                                                    |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| type             | string | Event type. Fixed value: `PAYMENT_RESULT`.                                                                                     |
| requestId        | string | The `requestId` supplied in the original Create Payout Request.                                                                |
| serialNum        | string | Platform serial number assigned to this payout transaction.                                                                    |
| amount           | number | Payout amount in the sending currency (`currency`).                                                                            |
| currency         | string | ISO 4217 currency code of the payout (sending side).                                                                           |
| status           | string | Terminal payout status (remapped — see hint above). Enum: `SUCCESS`, `FAILED`, `REFUNDED`, `CANCELLED`.                        |
| createdAt        | string | Timestamp when the payout request was created (ISO 8601).                                                                      |
| completedAt      | string | Timestamp when the payout reached its terminal status (ISO 8601).                                                              |
| msg              | string | Human-readable result message or failure reason.                                                                               |
| code             | string | Result or error code accompanying `status`.                                                                                    |
| refundAmount     | number | Amount refunded, when `status` is `REFUNDED`; `0` otherwise.                                                                   |
| refundCurrency   | string | Currency of `refundAmount`.                                                                                                    |
| creditedAmount   | number | Amount credited to the beneficiary after conversion and fees.                                                                  |
| creditedCurrency | string | ISO 4217 currency code of the credited (receiving) amount.                                                                     |
| 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). |

This webhook covers both the overall payout completion result and individual per-payee distribution results in a batch payout. Both share this same payload structure, distinguished by the `requestId` value — the parent request ID for the aggregate event, and the individual distribution request ID for per-payee events.

### Sample data

```json
{
  "type": "PAYMENT_RESULT",
  "requestId": "b2c3d4e5-2222-3333-4444-bbccddeeff00",
  "serialNum": "SN2024081500112233",
  "amount": 5000.00,
  "currency": "USD",
  "status": "SUCCESS",
  "createdAt": "2024-08-15T09:00:00Z",
  "completedAt": "2024-08-15T09:45:00Z",
  "msg": "Payout completed successfully",
  "code": "0",
  "refundAmount": 0,
  "refundCurrency": "USD",
  "creditedAmount": 36407.50,
  "creditedCurrency": "CNH",
  "extData": "{}",
  "secureHash": "Base64EncodedSHA256HashValue=="
}
```