Webhook Event Notification

Brief Description

• Webhook Event Notification
• When a relevant business event occurs, the system will push an event notification to your configured callback URL.

Retry Policy

• Success Criteria

  A push is considered successful if the merchant's callback URL returns HTTP status code 200; any other status code, connection failure, or timeout is considered a failure.

• Retry on Failure

  Upon a failed push, the system automatically retries until a 200 response is received or the maximum retry duration is reached. Retry intervals are categorized into three tiers:

  • Within 10 minutes of failure: Retry every 2 minutes;
  • Between 10 minutes and 1 hour: Retry every 10 minutes;
  • Between 1 hour and 12 hours: Retry every 1 hour;
  • Automatic retries cease if success is not achieved within 12 hours of the initial failure.

• Consistent Retry Content
  The eventId, eventType, data, and sign sent during each retry attempt are identical to those in the initial push; the event content is not altered, and the signature is not regenerated.

• Recommendations

  • The callback endpoint should complete signature verification and business processing quickly and return a 200 status code promptly to avoid being marked as a timeout failure due to excessive processing time;
  • If a callback for an expected event is not received after 12 hours, please contact technical support for verification.

Request URL

• open/api/card/setWebhook

Request Method

• POST

Request Headers

Top-Level Structure

Signature Verification

Compute the HmacSHA256 hash of the raw data string using your merchant secret (secret). If the result matches the sign field, the verification passes.

sign = HmacSHA256(data_string, merchant_secret)

Note: data is the raw JSON string representation of the event data object. Both signature verification and parsing must be based on this raw string.

Event Type List

1. card.create — Virtual Card Creation Result

Virtual card creation is an asynchronous operation. The creation result is notified via this Webhook.

Data Field Description

Callback Example

{
  "eventId": "b2c3d4e5-2222-3333-4444-bbccddeeff00",
  "eventType": "card.create",
  "data": "{\"cardId\":\"XXXXX\",\"amount\":1000,\"orderNo\":\"XXX\",\"status\":\"SUCCESS\"}",
  "sign": "7f4c2d9b1a3e8f0c5XXXc3d9b2a0e5f1c8d3b7a4e2f6c0d9b1a5e3f7"
}

2. card.recharge — Virtual Card Recharge Result

Data Field Description

Callback Example

{
  "eventId": "c3d4e5f6-3333-4444-5555-ccddeeff0011",
  "eventType": "card.recharge",
  "data": "{\"cardId\":\"XXXXX\",\"orderNo\":\"XXX\",\"amount\":1000,\"status\":\"SUCCESS\"}",
  "sign": "2a0e5f1c8d3b7a4e9f6c2XXX8b2a6e0f3c9d1b4a7e2f5c8d0b3a6"
}

3. card.withdraw — Virtual Card Withdrawal / Refund Result

Data Field Description

Callback Example

{
  "eventId": "d4e5f6a7-4444-5555-6666-ddeeff001122",
  "eventType": "card.withdraw",
  "data": "{\"cardId\":\"XXXX\",\"orderNo\":\"XXXXX\",\"amount\":1000,\"status\":\"SUCCESS\"}",
  "sign": "9d1b4a7e2f5c8d0b3a6e1f4c7XXXX4b7a2e5f9c0d3b6a1e4f7c2d5"
}

4. card.cancel — Virtual Card Cancellation Result

Data Field Description

Callback Example

{
  "eventId": "e5f6a7b8-5555-6666-7777-eeff00112233",
  "eventType": "card.cancel",
  "data": "{\"cardId\":\"XXXX\",\"orderNo\":\"XXXXX\",\"status\":\"SUCCESS\"}",
  "sign": "1e4f7c2d5b0a3e8f1c4d7b2XXXXX4e7f2c5d8b0a3e6f1c4d7b2a5e8"
}

5. card.activation — Physical Card Activation Result

After a physical card is successfully bound, the system automatically completes the PIN setting, activation code retrieval, and activation workflow. The activation result is notified via this Webhook.

Data Field Description

Callback Example

{
  "eventId": "f6a7b8c9-6666-7777-8888-ff0011223344",
  "eventType": "card.activation",
  "data": "{\"cardId\":\"XXXXX\",\"orderNo\":\"XXXX\",\"status\":\"SUCCESS\"}",
  "sign": "3c9d1b4a7e2f5c8d0b3a6e1f4c7d2b5XXXXe5f9c0d3b6a1e4f7c2d"
}

Notes

• The data field is a JSON-serialized string of the event data object. It must be deserialized (e.g., JSON.parse) before usage upon receipt.
• All monetary amounts are uniformly measured in cents (e.g., 1000 = $10.00).