1. XCheckout
ANexPay Docs
  • XCheckout
    • Introduction
    • Quick Start
    • Checkout Flow
    • Payment
    • Refund
    • Settlement
    • Webhook
    • Enum Reference
    • Api Reference
      • Authentication
        • Get AccessToken
      • payment order
        • CreateOrder
        • CancelOrder
        • GetOrderInfo
        • GetOrderList
      • refund
        • CreateRefund
        • CancelRefund
        • GetRefundInfo
        • GetRefundList
      • settlement
        • CreateSettlement
        • CancelSettlement
        • GetSettlementInfo
        • GetSettlementList
      • webhook
        • webhook
  • Agentic Payment
  1. XCheckout

Webhook

ANexPay XCheckout Webhook delivers real-time event notifications for orders, refunds, settlements, and abnormal payments, allowing your system to update business status promptly and perform accurate reconciliation.

1. Server Setup#

You need to implement a publicly accessible Webhook endpoint using POST and handle both signature verification and idempotency according to the requirements below.

Recommendations#

Support only POST application/json
Use HTTPS only
Ensure idempotent processing based on eventId
Return a successful response as quickly as possible to avoid retries

2. Security and Signature Verification#

Signature Mechanism#

The Webhook signing method follows the same principle as the response signature in the authentication section.
Use your assigned signKey
Generate an HMAC signature using HMAC-SHA512
Encode the result using Base64
Compare your calculated signature against the SIGNATURE header received in the request

Request Headers#

SIGNATURE: Base64(HMAC_SHA512(signKey, stringToSign))
TIMESTAMP: Millisecond timestamp, with an allowed clock skew of ±2 minutes

String to Sign#

stringToSign = TIMESTAMP + RESPONSE_BODY_JSON

Verification Rules#

Validate that the TIMESTAMP is within 2 minutes of your server time
Recalculate the signature using the same logic
Reject the request if the signature does not match
Only deserialize and process the payload after signature verification succeeds

Java Example#

3. Response and Retry Mechanism#

Success Response#

After successfully processing a Webhook event, your endpoint must return HTTP 200 with the following JSON body:
{
  "retcode": 200,
  "retmsg": "SUCCESS"
}

Retry Policy#

If the system does not receive HTTP 200, or if the response body does not match the required format, it will retry according to the following schedule:
15s → 15s → 30s → 3m → 10m → 20m → 30m → 30m → 30m → 60m → 3h → 3h → 3h → 6h → 6h
Total retry duration is approximately 24 hours.

Recommendations#

Return HTTP 200 as soon as the event is accepted
Process downstream business logic asynchronously whenever possible
Ensure repeated deliveries of the same eventId are handled idempotently

4. Event Structure#

The basic Webhook payload structure is as follows:
{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "CHECKOUT_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {}
}

Field Definitions#

eventId: Unique event identifier, used for idempotency
eventType: Event type
timestamp: Event creation time, in seconds
data: Event-specific payload

5. Event Types and Examples#

Specific enum values such as orderStatus, refundStatus, and settleStatus should follow your status mapping documentation.

5.1 Checkout Order Update#

Event Type: CHECKOUT_ORDER_CHANGED
{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "CHECKOUT_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {
    "orderNo": "oxxxxxxx",
    "token": "ETH_USDT",
    "payingAmount": 989.19,
    "orderAmount": 989.19,
    "orderStatus": "PAID",
    "refundedAmount": 0,
    "createdTime": "2025-11-23 11:27:29",
    "updatedTime": "2025-11-23 11:27:29"
  }
}

5.2 Refund Order Update#

Event Type: REFUND_ORDER_CHANGED
{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "REFUND_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {
    "refundOrderNo": "xxxxxxx",
    "token": "ETH_USDT",
    "amount": "404.69",
    "refundStatus": "REFUNDED",
    "createdTime": "2025-01-25 00:48:39",
    "updatedTime": "2025-01-25 00:48:39"
  }
}

5.3 Settlement Order Update#

Event Type: SETTLEMENT_ORDER_CHANGED
{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "SETTLEMENT_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {
    "settlementOrderNo": "xxxxxxxx",
    "token": "ETH_USDT",
    "address": "0xxxxxxxxxxxx",
    "settlementAmount": "315.45",
    "settleStatus": "SETTLED",
    "createdTime": "2026-05-15 07:28:12",
    "updatedTime": "2026-05-15 07:28:12"
  }
}

5.4 Abnormal Payment#

Event Type: ABNORMAL_PAYMENT
This event covers scenarios such as overpayment, underpayment, and late payment, which may later be handled through the refund process.
{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "ABNORMAL_PAYMENT",
  "timestamp": 1758701681,
  "data": {
    "abnormalPaymentNo": "xxxxxxxx",
    "orderNo": "xxxxxxx",
    "token": "ETH_USDT",
    "amount": "818.89",
    "hash": "0xxxxxxxxxx",
    "pendingAmount": "739.00",
    "createdTime": "2025-12-23 12:56:47",
    "updatedTime": "2025-12-23 12:56:47"
  }
}

6. Security and Operational Best Practices#

IP Whitelisting
If available, you may request fixed outbound IP ranges and restrict source IPs on your side.
Replay Protection
Strictly validate both TIMESTAMP and SIGNATURE, and ensure idempotent handling based on eventId.
Audit and Alerting
Log raw headers, request body, and signature verification results. Trigger alerts for repeated failures or abnormal retry activity.
Performance Optimization
Persist or enqueue the event first, then return HTTP 200 immediately to reduce repeated deliveries caused by long processing time.

7. Webhook Processing Flow#

1.
ANexPay XCheckout sends a POST request to your Webhook endpoint
2.
Your server validates the timestamp and verifies the signature
3.
Your system checks whether the eventId has already been processed
4.
If not processed, the event is queued or handled by your business logic
5.
Your endpoint returns HTTP 200 with the required JSON response
6.
If verification fails or no valid response is returned, the system retries based on the retry schedule
Source reference:
Modified at 2026-03-30 18:38:44
Previous
Settlement
Next
Enum Reference
Built with