Configure a webhook endpoint to listen for events within your account, enabling your integration to automatically respond and trigger the appropriate actions.
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.