Digital signature

Digital signatures can ensure the reliability and anti-repudiation of the API data transmitted. When Merchant’s backend system sends API request to the payment system, the request must be signed to identify who send the request and ensure that the request is not tampered in data transmission.

There are two steps to create digital signature: 1) generating pre-sign string 2) signing this request by using pre-sign string and key with signature alogrithm。

Generating pre-sign string

For both API request and response, the pre-sign string should be generated according to the following step:

1. Presume all data sent and received is the set M. Sort non-empty values in M in ascending alphabetical order (i.e. lexicographical sequence), and join them into string A via the corresponding URL key-value format (e.g. key1=value1&key2=value2...).
   
   Notes:
   • Sort parameter names in ascending alphabetical order based on their ASCII encoded names (e.g. lexicographical sequence);
   • Empty parameter values are excluded in the signature;
   • Parameter names are case-sensitive;
   • When checking returned data from the payment system, the transferred sign parameter is excluded in this signature as it is compared with the created signature.

Example

The correct sorting order of the data is:

{
    "attach" : "It is the description of the product.",
    "body" : "測試產品",
    "mch_create_ip" : "127.0.0.1",
    "mch_id" : "10085200000000",
    "nonce_str" : "54fa7f8e1006aecb8b58ef6059abb09c",
    "notify_url" : "http://www.ionline.com.hk/notify_callback",
    "out_trade_no" : "TRDNO150271173415530",
    "service" : "ionline.pay.weixin.native.intl",
    "sign_type" : "MD5",
    "total_fee" : "10"
}

The correct pre-sign string is:

attach=It is the description of the product.&body=測試產品&mch_create_ip=127.0.0.1&mch_id=10085200000000&nonce_str=54fa7f8e1006aecb8b58ef6059abb09c&notify_url=http://www.ionline.com.hk/notify_callback&out_trade_no=TRDNO150271173415530&service=ionline.pay.weixin.native.intl&sign_type=MD5&total_fee=10

Signing the request

Signature Algorithm

Currently, only MD5 is supported.

MD5 Sign Type

After the pre-sign string is generated, perform the following steps to generate the signature:

1. Append the MD5 secret key to the pre-sign string to generate a new string.
2. Calculate the new string with the MD5 signature algorithm (by using the MD5 signature function).

The result 32-byte string is the signature, which is used as the value of the sign parameter.

How to sign?

sign=MD5(PRE-SIGN_STRING&key=API_KEY).toUpperCase()

Example:

Suppose the request parameters are

{
    "attach" : "It is the description of the product.",
    "body" : "測試產品",
    "mch_create_ip" : "127.0.0.1",
    "mch_id" : "10085200000000",
    "nonce_str" : "54fa7f8e1006aecb8b58ef6059abb09c",
    "notify_url" : "http://www.ionline.com.hk/notify_callback",
    "out_trade_no" : "TRDNO150271173415530",
    "service" : "ionline.pay.weixin.native.intl",
    "sign_type" : "MD5",
    "total_fee" : "10"
}

And the API_KEY is "902d9aa50087b9fbc7898b926c2cd9f0"

The pre-sign string "string1" is:

attach=It is the description of the product.&body=測試產品&mch_create_ip=127.0.0.1&mch_id=10085200000000&nonce_str=54fa7f8e1006aecb8b58ef6059abb09c&notify_url=http://www.ionline.com.hk/notify_callback&out_trade_no=TRDNO150271173415530&service=ionline.pay.weixin.native.intl&sign_type=MD5&total_fee=10
	
    
Append &key=API_KEY to "string1" and perform MD5 arithmetic to get "sign" value:
sign
=MD5(string1&key=902d9aa50087b9fbc7898b926c2cd9f0).toUpperCase()
=MD5(attach=It is the description of the product.&body=測試產品&mch_create_ip=127.0.0.1&mch_id=10085200000000&nonce_str=54fa7f8e1006aecb8b58ef6059abb09c&notify_url=http://www.ionline.com.hk/notify_callback&out_trade_no=TRDNO150271173415530&service=ionline.pay.weixin.native.intl&sign_type=MD5&total_fee=10&key=902d9aa50087b9fbc7898b926c2cd9f0).toUpperCase()
="6C3441C872CEEC1ACF7AB1E69D1C2C76"

Verifying the signature

How to verify?

MD5 Sign Type

After receiving the data of the JSON response or XML payment result notification from the payment system, merchant’s backend should perform the following steps to verify signature.

1. Generating pre-sign string similar to the step 1 of Signing the request
2. Append API_KEY to the character string to generate a new string
3. Calculate the "sign" value with the signature algorithm
4. Compare the "sign" value of the JSON response or XML payment result notification with the calculated "sign" value in step 3. If the value is equal, the verification is successsul.