WebHook

Request URL

Provided by the merchant when calling the platform gateway API. Refer to the notifyUrl parameter in the payment/payout creation API request.

The WebHook address for disputes and refunds is configured in the merchant dashboard.

Request Parameters

HTTP Header

Field	Data Type	Length Limit	Required	Description
Accept	String	N/A		This field value only supports application/json.
Content-Type	String	N/A	YES	This field value only supports application/json.
Authorization	String		YES	Authorization: {type} {credentials}, refer to the Signature specifications section for details.
X-Notify-Event	String	50	YES	Refer to the Event Definition section for details.

HTTP Body

Field	Data Type	Required	Description
event	String	YES	Refer to the Event Definition section for details.
code	String	YES	The value is OK
errorMessage	String	NO	The value is null
data	JSON Object	YES	The data field represents the business entity object corresponding to the notification event, and the specific fields are the same as those in the data field of the response from each business query API.

Business Entity Object Field Description

• payment
• payout
• subscription
• refund
• dispute

Response Data

HTTP Status

When the merchant successfully receives the notification, respond with HTTP 200.

HTTP Header

Field	Data Type	Required	Description
Content-Type	String	YES	This field value only supports application/json.
Authorization	String	YES	Authorization: {type} {credentials}, refer to the Signature specifications section for details.

HTTP Body

Field	Data Type	Required	Description
code	String	YES	When code value is OK indicates the merchant has successfully received and processed the request. Any other value means the request was received successfully but processing failed.
errorMessage	String	NO

Merchant Response Error Code

Code	Explanation	Solution
OK	Processing successful
FAIL	Processing failed	The platform will notify again.

Examples

Request By Platform

curl https://{{merchant_notify_url}} \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'Authorization: V2_SHA256 appId=483f6c9c743b4a9bbd34bee0c9c81eb7,sign=7363f5c7746b79863326940e8b25ffb0f1f7fec22382f036a6b06f8b9e290229,timestamp=1715410373693,nonce=29E890BE88FFAE17DCB2985502F50C92' \
  -d '{"key1": "value1", "key2": "value2"}'

Merchant Response

• Response when processing is successful

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 06 Mar 2024 12:00:00 GMT

{
  "code": "OK"
}

• Response when processing fails

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 06 Mar 2024 12:00:00 GMT

{
  "code": "FAIL",
  "errorMessage": "Populate with a relevant error message."
}

Gateway Processing Merchant Response Strategy

The gateway will retry the notification according to the policy if any of the following conditions are met, until the system-configured threshold is exceeded:

• The notification interface responds with a non-200 status code.
• The notification interface response code is not OK.
• The notification interface times out without a response.

Event Definition

Event naming: {entity}.{domain_event}

Event	Description	Enabled by default
PAYMENT.PAID	Payment successful	YES
PAYOUT.PAID	Payout successful	YES
PAYOUT.FAILURE	Payout failed	YES
PAYOUT.REVERSED	Payout reversed	YES
PAYOUT.CANCELLED	Payout cancelled	YES
SUBSCRIPTION.ACTIVATED	Subscription activated and first payment completed	YES
SUBSCRIPTION.CHARGED	Subscription renewal succeeded	YES
SUBSCRIPTION.CANCELLED	Subscription cancelled by user	YES
SUBSCRIPTION.CLOSED	Subscription closed (user-initiated refund or system action)	YES
REFUND.SUCCEED	Refund succeeded	YES
REFUND.FAILED	Refund failed	YES
REFUND.CANCELLED	Refund cancelled	YES
REFUND.REVERSED	Refund reversed/adjusted	YES
DISPUTE.OPEN	Dispute created	YES
DISPUTE.UNDER_REVIEW	Under review	YES
DISPUTE.WON	Dispute won	YES
DISPUTE.LOST	Dispute lost	YES
DISPUTE.CLOSED	Dispute closed	YES

Merchant Processing Recommendations

TIP

• Implement idempotent processing for push messages to avoid duplicate handling.
• After successfully receiving the push message, process the business logic asynchronously to prevent the gateway from retrying due to timeouts caused by long synchronous processing times.
• When processing business logic after successfully receiving the push message, consider concurrency scenarios.