Why Use Webhooks

When building an integration, you may want your application to receive events when they occur in the account so that your backend system can take appropriate actions. To enable webhook events, you need to register a webhook endpoint. After registration, real-time event data can be pushed to the application's webhook endpoint when events occur in your account. Use HTTPS to send webhook events as a JSON payload containing an Event object to your application. Receiving webhook events is particularly useful for listening to asynchronous events, such as 3ds notifications, transaction result notifications, etc.

Webhook Request

HTTP POST payload sent to the webhook endpoint URL. Request method: POSTData format: application/JSONResponse method: Returns SUCCESS for successful reception; otherwise, notifications will be resent multiple times with a delay. The payload data is encrypted and should be decrypted using your own public key. The datagram is encoded in base64 and then encrypted with the private key (encryption logic is the same as that of requests).

Interface address：Merchant provided

Request Parameters：

Sequence Number	Domain Name	Variable Name	Required	Type	Remarks
01	Type	type	M	String	Business Type
02	Datagram	data	M	JsonObject	Data Content
03	Version Number	version	M	String(6)	1.0.0
04	Merchant Number	userNo	M	int	Unique number provided to merchants

Retry logic

If your webhook endpoint is unavailable or has a long response time, we will resend the notification message multiple times within three days until a successful response is returned.

Confirm the event immediately

If your webhook script performs complex logic, the script may timeout before it is completed. Ideally, your webhook processing code (which acknowledges receipt of an event by returning a 200 status code) should be separate from any processing performed on that event. Return SUCCESS for successful reception; otherwise, multiple retries will be issued.

Handle duplicate events

Webhook endpoints may occasionally receive the same event multiple times. We recommend that you ensure your event processing is idempotent to avoid receiving duplicate events. To delete a duplicate event, use the fields sent with the event. The same event remains unchanged even if it is retried.

Event sequence

Events are not guaranteed to be delivered in the order they were generated. Your terminal should not expect these events to be delivered in this order and should process them accordingly. You can also use the in the event for sorting.