​
1. WaaS Callback Processing Flow

Callback request processing flow:
⚠️ This is the request flow initiated by WaaS system to merchant’s callback URL
Merchants need to handle callback requests received from WaaS according to the following process
Callback Data Encryption
1
WaaS prepares JSON business data
2
WaaS encrypts with merchant private key using RSA
3
Base64 encoding for transmission
Callback Request Validation
A
WaaS carries X-API-KEY in request header
B
Merchant verifies API KEY validity
C
Return 401 Unauthorized if validation fails
Merchant Decrypts Callback Data
α
Read callback data from raw input stream
β
Base64 decode to get encrypted data
γ
Merchant decrypts using RSA with public key
WaaS callback request example:

// Request sent by WaaS to merchant’s callback URL
POST /your-callback-endpoint HTTP/1.1
Host: your-merchant-domain.com
Content-Type: application/x-www-form-urlencoded
X-API-KEY: merchant_api_key_12345


ew0KICAib3JkZXJJZCI6ICIxMjM0NTY3ODk…

​
2. Key Points for Merchant Handling Callbacks

Callback API Key Validation:
When handling callback requests from WaaS:
  • Obtain key provided by WaaS from HTTP header X-API-KEY
  • Verify whether key is valid and within validity period
  • Return 401 Unauthorized if validation fails

Note: This API Key is different from the key used by merchants to call WaaS APIs

Callback Data Decryption Specifications:
Notes for handling WaaS callback data:
  • Must use HttpServletRequest raw input stream for reading
  • Base64 decode to obtain encrypted byte data
  • RSA decrypt using merchant public key

Common error: Misusing request.getParameter(“data”) will return null

Callback Handling Instructions:

The WaaS system sends event notifications to the callback URL configured by the merchant. Merchants need to correctly handle these callback requests. The encryption/decryption process is the same as when merchants call WaaS APIs, the main difference is in the way callback data is read.

​
3. Callback Idempotency Handling

Callback Idempotency Requirements:
WaaS may resend identical event callbacks
Merchants must ensure identical events are processed only once
Callback TypeIdempotency Key CompositionExplanation
Deposit Callback(txid, chain, symbol, toAddress) combined hashResolves wrapped contract duplicate deposit issues
Withdrawal CallbacktxidGlobally unique transaction ID controlled by WaaS
Other Callbacks(type, trackingId, callBackId…)All callback types must implement idempotency

WaaS Tip: Do not use requestUUID that changes each time as idempotency key

Callback Processing Principles:
  • Store unique identifiers of processed callback events
  • Return success status directly for duplicate callbacks (without repeating business processing)
  • WaaS will retry callback only when callback processing fails (only when errCode=0 is considered successful by WaaS)

​
1. WaaS Callback Processing Flow

Callback request processing flow:
⚠️ This is the request flow initiated by WaaS system to merchant’s callback URL
Merchants need to handle callback requests received from WaaS according to the following process
Callback Data Encryption
1
WaaS prepares JSON business data
2
WaaS encrypts with merchant private key using RSA
3
Base64 encoding for transmission
Callback Request Validation
A
WaaS carries X-API-KEY in request header
B
Merchant verifies API KEY validity
C
Return 401 Unauthorized if validation fails
Merchant Decrypts Callback Data
α
Read callback data from raw input stream
β
Base64 decode to get encrypted data
γ
Merchant decrypts using RSA with public key
WaaS callback request example:

// Request sent by WaaS to merchant’s callback URL
POST /your-callback-endpoint HTTP/1.1
Host: your-merchant-domain.com
Content-Type: application/x-www-form-urlencoded
X-API-KEY: merchant_api_key_12345


ew0KICAib3JkZXJJZCI6ICIxMjM0NTY3ODk…

​
2. Key Points for Merchant Handling Callbacks

Callback API Key Validation:
When handling callback requests from WaaS:
  • Obtain key provided by WaaS from HTTP header X-API-KEY
  • Verify whether key is valid and within validity period
  • Return 401 Unauthorized if validation fails

Note: This API Key is different from the key used by merchants to call WaaS APIs

Callback Data Decryption Specifications:
Notes for handling WaaS callback data:
  • Must use HttpServletRequest raw input stream for reading
  • Base64 decode to obtain encrypted byte data
  • RSA decrypt using merchant public key

Common error: Misusing request.getParameter(“data”) will return null

Callback Handling Instructions:

The WaaS system sends event notifications to the callback URL configured by the merchant. Merchants need to correctly handle these callback requests. The encryption/decryption process is the same as when merchants call WaaS APIs, the main difference is in the way callback data is read.

​
3. Callback Idempotency Handling

Callback Idempotency Requirements:
WaaS may resend identical event callbacks
Merchants must ensure identical events are processed only once
Callback TypeIdempotency Key CompositionExplanation
Deposit Callback(txid, chain, symbol, toAddress) combined hashResolves wrapped contract duplicate deposit issues
Withdrawal CallbacktxidGlobally unique transaction ID controlled by WaaS
Other Callbacks(type, trackingId, callBackId…)All callback types must implement idempotency

WaaS Tip: Do not use requestUUID that changes each time as idempotency key

Callback Processing Principles:
  • Store unique identifiers of processed callback events
  • Return success status directly for duplicate callbacks (without repeating business processing)
  • WaaS will retry callback only when callback processing fails (only when errCode=0 is considered successful by WaaS)