Security Requirements

Signature Method

BasicExPay uses the HMAC-SHA512 algorithm for signature generation and verification. Merchants can generate an apiKey and secretKey pair by logging into the merchant platform, navigating to "Developer" -> "API Key," and clicking on "Generate API Key."

Message Signature

The signature mechanism for the message is as follows:

1. Signature Algorithm: HMAC-SHA512.

2. Let P be the collection of all the sent data. Arrange the non-empty parameter values in P in ascending order of ASCII code of the parameter name (lexicographical order), and concatenate them in the format of URL key-value pairs (i.e., K1=V1&K2=V2) to form string A.

Note: The parameter names are case-sensitive. The sign parameter is not involved in the signature. Note: In the request parameters, the JSON string in the bizContent field is sorted according to the fixed field order. Please refer to the request parameter order in each Method. Note: In the request parameters, the bizContent field is a string format, i.e., the request parameters in each Method are serialized into JSON string and placed in the bizContent field.

3. Append the key parameter, where the value of the key parameter is the apiKey secret key, to the end of string A to obtain the signTemp string. Then, use the secretKey secret key to perform HMAC-SHA512 operation on signTemp, and convert the resulting string to uppercase to obtain the final signature value, signValue.

Note: Both the apiKey and secretKey have a length of 64 characters.

4. Assign the final generated signature value, signValue, to the common parameter sign.

Signature Example

For example, when a merchant initiates a cashier payment (basicexpay.trade.cashier), the request parameters for the cashier payment interface are as follows:

{
  "merOrderNo": "ysibWeNmphs55rse",
  "clientIp": "127.0.0.1",
  "totalAmount": 49.33,
  "currency": "USDT",
  "description": "Test Product",
  "orderSource": "APP",
  "tradeStartTime": "2023-04-01 14:50:58",
  "expireTime": 900,
  "notifyUrl": "https://api.xx.com/receive_notify.htm",
  "returnUrl": "https://xx.com/return.htm",
  "attach": ""
}

Combine all the request parameters:

{
  "bizContent": "{\"merOrderNo\":\"ysibWeNmphs55rse\",\"clientIp\":\"127.0.0.1\",\"totalAmount\":49.33,\"currency\":\"USDT\",\"description\":\"Test Product\",\"orderSource\":\"APP\",\"tradeStartTime\":\"2023-04-01 14:50:58\",\"expireTime\":900,\"notifyUrl\":\"https://api.xx.com/receive_notify.htm\",\"returnUrl\":\"https://xx.com/return.htm\",\"attach\":\"\"}",
  "merNo": "819275770875906",
  "method": "basicexpay.trade.cashier",
  "nonce": "R6mkm6sP4CpAX7Bk",
  "signType": "HmacSHA512",
  "timestamp": "20230401145058"
}

Step 1: Sort the request parameters in lexicographical order and concatenate them into a string according to the URL key-value pair format:

bizContent={"merOrderNo":"ysibWeNmphs55rse","clientIp":"127.0.0.1","totalAmount":49.33,"currency":"USDT","description":"Test Product","orderSource":"APP","tradeStartTime":"2023-04-01 14:50:58","expireTime":900,"notifyUrl":"https://api.xx.com/receive_notify.htm","returnUrl":"https://xx.com/return.htm","attach":""}&merNo=819275770875906&method=basicexpay.trade.cashier&nonce=R6mkm6sP4CpAX7Bk&signType=HmacSHA512&timestamp=20230401145058

Step 2: Append the key parameter to the end of the string. The value of the key parameter is the apiKey secret key, resulting in the signTemp string:

bizContent={"merOrderNo":"ysibWeNmphs55rse","clientIp":"127.0.0.1","totalAmount":49.33,"currency":"USDT","description":"Test Product","orderSource":"APP","tradeStartTime":"2023-04-01 14:50:58","expireTime":900,"notifyUrl":"https://api.xx.com/receive_notify.htm","returnUrl":"https://xx.com/return.htm","attach":""}&merNo=819275770875906&method=basicexpay.trade.cashier&nonce=R6mkm6sP4CpAX7Bk&signType=HmacSHA512&timestamp=20230401145058&key=7V46gR6dA83eIS0vU9w7gU5mYiy2G6Oxx1J19WcgU9ZF20g1f2HYic7fGzOG36O3

Step 3: Perform HMAC-SHA512 operation using the secretKey secret key on signTemp, and convert the resulting string to uppercase to obtain the final signature value, signValue:

88E749A59400CB705477A11C11B7557FF861D7489AE416C0630656149C87EDDE8B738DB30022B434D9BFF4031359E6B4951660B4F1B087B27ADE8318789BB3D86

Step 4: Include the sign parameter in the overall request parameters:

{
  "bizContent": "{\"merOrderNo\":\"ysibWeNmphs55rse\",\"clientIp\":\"127.0.0.1\",\"totalAmount\":49.33,\"currency\":\"USDT\",\"description\":\"Test Product\",\"orderSource\":\"APP\",\"tradeStartTime\":\"2023-04-01 14:50:58\",\"expireTime\":900,\"notifyUrl\":\"https://api.xx.com/receive_notify.htm\",\"returnUrl\":\"https://xx.com/return.htm\",\"attach\":\"\"}",
  "merNo": "819275770875906",
  "method": "basicexpay.trade.cashier",
  "nonce": "R6mkm6sP4CpAX7Bk",
  "signType": "HmacSHA512",
  "timestamp": "20230401145058",
  "sign": "88E749A59400CB70547711B7557FF861D7489AE416C0630656149C87EDDE8B738DB30022B434D9BFF4031359E6B4951660B4F1B087B27ADE8318789BB3D86"
}

Message Verification

1. During signature verification, the sign parameter is not involved in the signature calculation. After excluding the sign parameter from the received parameter list, follow the signature processing steps to obtain the signValue.

2. Compare the calculated signValue with the value of the sign parameter for verification.

For more information, refer to the Asynchronous Notification Verification section.

Testing Demo

BasicEx provides a testing demo for reference by merchants and channel partners' system analysts, system designers, system developers, and testers. For more details, please refer to: https://merchant.basicex.com/developer/demo/demo.html