Webhook

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

This page documents 2 event types delivered to the webhookUrl supplied in the original Create Payout Request: 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.

Sample data

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

status here is the remapped value used by NeoX, not the provider's raw status. Mapping: SUCCESS → SUCCESS, FAILED → FAILED, REFUND → REFUNDED, CANCEL → CANCELLED.

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.

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

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