Authentication
Wonder OpenAPI adopts RSA Signature to sign API requests and Webhook requests. Please follow the instructions in this chapter to complete the development of the signature algorithm.
If you do not yet have an AppID, please create one by following the steps in the document: Create your AppID via the Wonder PortalDOC.
Request Headers
Populate the HTTP Headers in API requests following the format below.
| Header Name | Comment | Example |
|---|---|---|
| Credential | $APPID/$RequestTime/Wonder-RSA-SHA256 | d900da8b-6e16-4a85-8a66-05d29ac53f24/20240501120123/Wonder-RSA-SHA256 |
| Signature | Please refer to the document below to generate this value. | lM42cgyuLS98Dieydc8K2OD3KwYkOXibpV9pFvr/R0i/830M/FPKUKba v2UBBN3M3EdPk/PpvKQlvBNT+NbEg20C KuiDTZWDc3r7KiA1pdZsui/57XCVhC2s01W8jEM+G5lS362+p8+E0K6 UKQDrJMyVpbDT31XSkSJIxae+uDi2nJr4DnIkemeU2LlNDRPPGe9NeX7z3B3N3LwIi QgKMyauPqAjro0UrZykQM9pv4UySRSU2cT8EcjQmyKxbzy uR2A47PyeodJvotlIthdfCHIxG52D06tpRJlRVbUdvxSg14bFiPbr3F wCvruZlbR15gOanJCqE4wp4fC8qEXXsg== |
| Nonce | Generate a random 16-byte Nonce (alphanumeric) | 0000000000000000 |
| Content-Type | The stardand HTTP Header | application/json |
| X-Request-ID | Unique HTTP request tracking id | d900da8b-6e16-4a85-8a66-05d29ac53f24 |
The algorithm process is described in pseudocode. You may directly refer to the source code in various languages below or use the online signature debug tool to assist your development.
APPID = "your-appid"
PRIVATE_KEY = "your-rsa-private-key"
REQ_TIME = UTC now as "yyyyMMddHHmmss"
NONCE = random 16 alphanumeric bytes
METHOD = "GET" | "POST"
URI = full path, e.g. "/svc/payment/api/v1/echo"
BODY = raw request body (omit if empty)
// Credential header
CREDENTIAL = APPID + "/" + REQ_TIME + "/Wonder-RSA-SHA256"
// Pre-signature
PRE = METHOD + "\n" + URI
IF BODY is non-empty: PRE = PRE + "\n" + BODY
// Derive hex hash
S = HMAC_SHA256(NONCE, REQ_TIME)
S = HMAC_SHA256(S, "Wonder-RSA-SHA256")
S = HMAC_SHA256(S, PRE)
HEX = HEX(S)
// Final signature
SIGNATURE = BASE64( RSA_SHA256_PKCS1v15_SIGN(PRIVATE_KEY, HEX) )Always use UTC time. Local time will cause signature mismatch. The timestamp in credential and the value used in HMAC must be identical and in UTC.
References
Wonder support the normal program language signature for your reference. Besides, online signature debug tool — interactively test each step of the algorithm during development.
| Language | Download |
|---|---|
| PHP | php.zip |
| Python | python.zip |
| Node.js | nodejs.zip |
Troubleshooting
We have listed explanations for common issues for your troubleshooting reference.
Invalid credential
This generally indicates that your AppID is invalid. Please reconfirm the validity of the AppID with relevant personnel. Another possible cause is mistakenly using a sandbox AppID in the production environment.
No trusted remote addr
This indicates that public network IP restrictions have been configured for your AppID. Please check the IP address whitelistDOC. Once the IP whitelist is enabled, all API requests from IP addresses not included in the whitelist will be rejected. This feature is disabled by default.
Invalid signature
This generally indicates an incorrect request signature. Please check the following points:
- whether you are using the wrong RSA keypair.
- whether the signature is generated based on the original request body.
Certain programming languages or technical frameworks may apply different character escaping rules. It is recommended that you troubleshoot step by step with the online signature debug tool.
Expired request
This indicates an invalid request timestamp. Please verify the following:
- Whether you have followed the agreed datetime format.
- Whether UTC time is adopted.
- Whether more than one hour has elapsed since the timestamp was generated.