Overview
Developers must sign and verify signatures for all request-response scenarios, API callbacks, and payment initiation within the superapp's payment API.
1. When is a signature required? How to sign?
1.1 Request the superapp's payment API
Merchants need to use their API certificate to create request signatures when calling the superapp's payment API. The signing method varies based on the request parameters. Refer to the following guidelines for details.
How to create a request signature
Merchant API certificate
The merchant API certificate is required to create a request signature.
We have got the merchant API certificate and stored the corresponding merchant API private key (apiclient_key.pem) locally.
Merchant ID: 202003191046
Certificate serial number: 526807E51G82219FOC2D5D3E6AB8ED1S8SDS8787AS
API certificate private key: Save the following file in PEM format. To avoid confusion with your actual public and private keys, we have saved it as apiclient_test_key.pem.
Note:
The following is a sample key and is not actually usable.
-----BEGIN PRIVATE KEY-----\\nMIIEuwIBADALBgkqhkiG9w0BAQEEggSnMIIEowIBAAKCAQEA1WFrv7DQ2FeBB2ZR\\n/bh+W/38+Rgcs/yxTdd0/9r5DWYvB6Lhc0pqaNnrmZUc+Uih6CELe1K3AAvg0+6A\\njfcLV/aqNx4xdwqfLt2P1F7TsyGJZWMe5OoPmwzel8zRpGcqY/WdmevEEFqmIc/r\\nWVa1fOCM9eIzP9QQbgT7tKXa/ixi5B5y8B0pShYJuyE2M8GimvbDbnaatMQJlwFP\\nO9fxU7cRZBdkDcUB8dMxl2ZfTHZjEC6ypR4Ux5vnPIB9hH7qHFbc6W9ueEfVRTk3\\neeoVnbmZJHliWBqtv89Tm0uMk+fD2ZayRA+TuwFajt0NTcbnM6kM0cuuyEyd7bnE\\nWFKuAwIDAQABAoIBACS+8CVEt9Jpz0iM8FW3Ldt9s9DZvCeqvoXfMsDU3srV7Adu\\nn1CRYh3IWXBLY3/yaB9ngWitZ+JUKVWV3wGTp5pwWgO/6VjMtXkGorw50E8q2VRi\\na3GUdTeIUdTmarvbIEuygn99QHhog++StL7f1cU5jkzRtW2qgWHQ7d/AKCRZA+R1\\nnUwNaQHdz2Fn5a5cQsULgNCf0Rfn4MxgsvGl3ZVcJVUiumEDfV2TDcLz2wEaWvTo\\nOhD6bN+Ug0LuucmuwC9FzR7DUNxWxmQpAdPMbAfku47K9ARqHfUjNXtBUktGdo6x\\nfmdm/fNTodSzziu4Sn87iQU0R7VU8TT2Wx1l/jECgYEA3/3yqEWSwjCY/hs+rq9O\\nrhF4vVyd8az7X+KCKiYZl51oRiRSso8dWvuVixpx3ZW8vp81K2eq9h6BmuePMVZK\\nH8PV8LbNbuLUn/cTREo7JcT0jUFSfwyMiu6De23fyCSb3fM4EFdjuywTn0d+RIr5\\nlnurFc8mRWTTX0E+kht7K50CgYEA899JYDMqs7GU+Gg8vNEHL3ux4VIGWaV0LPFj\\nn4UNn0aT3t0M+OgWm9K1tCSi5PPkmkAt8wCOtKPmSiq1CQeWa8HX+JHkMiEYO6Ki\\nHecXmZlUr/yXMhCTkkxwNsFAFxP1KYOm91+ka6w+l7/qcjan+WZsYT2XpSTx0LV5\\nPma8Hh8CgYABUNuZE3eOPnzXmU9f9VWv/hhIfH/NCKgdYxZCqyChXGJdbx8xP1f7\\nzdiODaS3mYaXVBYa4CwH8BvwzgVwU8Jxt1PNazV/vkNjgS8SyqDYUvTg045pgqhc\\ntJP/KKEU6uojfqdIqUrDsbmXyPK78lkPAkD6CtJ9u97mA1sbvp+VnQKBgFp41qba\\ntJfPZJ23RfkibtD9yaL2pCZzzCK0NqpCWShirY77YMmiiGishf5brRbVKFTVRHan\\nGUoIl/Gh4GGGMBav5ihwL0Etp+jPz+baCZZRHOrhAVJwdd7LfsHBdb5aCBSro7CY\\nCc5sKxhu+VH/1tceWUzF5dE9YHx2JpGw2U8vAoGBAL2Wp4S2dA+zKfhX7QOCLl3q\\nXYujhL1dgZBaDonWtOrn7llLSqaryD/TH8C6QRVrsXpLdwuSLx7tzQnG81ptO49Q\\nuCVFbGF5RwCf8Wq8OlYuJ/MS9GsE+Ux2EYVX3DD5zV6gtN11c7NsTEan9fRpgZjt\\n2kuvKl1oec/Rh8fbmqid\\n-----END PRIVATE KEY-----
Construct the signature string
We ask that the merchant's technical developers construct the signature string according to the rules outlined in this document. The superapp's payment will use the same method to construct the signature string. If the merchant constructs the signature string incorrectly, the signature verification will fail. Below is the specific format of the signature string.
The signature string consists of five lines, with each line representing a parameter. It ends with a newline character (\\n, ASCII value 0x0A), including the last line. If a parameter itself ends with \\n, an additional \\n should be appended.
HTTP request method\\n
URL\\n
Request timestamp\\n
Request random string\\n
Request body\\n
1. Request parameters with path parameters
Take the order query API as an example.
Step 1: Get the HTTP request method.
GET
Step 2: Get the absolute URL of the request.
The URL for the query order API is /v3/pay/transactions/out-trade-no/{out_trade_no}. The path includes the parameter out_trade_no, which should be replaced with the actual merchant order number, e.g., 1217752501201407033233368018.
/v3/pay/transactions/out-trade-no/1217752501201407033233368018
Step 3: Get the current system timestamp when the request is initiated.
This is the total number of seconds from 00:00:00 GMT on January 1, 1970 (08:00:00 Beijing time on January 1, 1970) to the present. The superapp's payment will reject requests made a long time ago, so merchants should ensure their system time is accurate.
date +%s
1554208460
Step 4: Generate a request random string.
E6F165123B4E32D8D0D6
Step 5: Get the request body.
For this API, the request body is an empty string, so just append a \\n.
Step 6: Construct the request signature string according to the rules above.
POST\\n
/v3/pay/transactions/jsapi\\n
1554208460\\n
E6F165123B4E32D8D0D6\\n
{"appid":"wxd678efh567hg6787","mchid":"1230000109","description":"Image","out_trade_no":"1217752501201407033233368018","notify_url":"https://www.weixin.qq.com/wxpay/pay.php","amount":{"total":100,"currency":"CNY"},"payer":{"openid":"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"}}\\n
2. Request parameters with body parameters
Take the order API as an example.
Step 1: Get the HTTP request method.
POST
Step 2: Get the absolute URL of the request, excluding the domain part.
/v3/pay/transactions/jsapi
Step 3: Get the current system timestamp when the request is initiated.
This is the total number of seconds from 00:00:00 GMT on January 1, 1970 (08:00:00 Beijing time on January 1, 1970) to the present. The superapp's payment will reject requests made a long time ago, so merchants should ensure their system time is accurate.
date +%s
1554208460
Step 4: Generate a request random string.
E6F165123B4E32D8D0D6
Step 5: Get the request body.
You can place all parameters on one line; the body parameter in the signature request should also be on one line.
Alternatively, you can calculate the signature with parameters on multiple lines; the body parameter in the request should match this format. Essentially, the body in the signature calculation should be identical to the body in the request.
Here is an example with all parameters on one line:
{"appid":"wxd678efh567hg6787","mchid":"1230000109","description":"describe","out_trade_no":"1217752501201407033233368018","notify_url":"https://www.weixin.qq.com/wxpay/pay.php","amount":{"total":100,"currency":"CNY"},"payer":{"openid":"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"}}
Step 6: Construct the request signature string according to the rules above.
POST\\n
/v3/pay/transactions/jsapi\\n
1554208460\\n
E6F165123B4E32D8D0D6\\n
{"appid":"wxd678efh567hg6787","mchid":"1230000109","description":"describe","out_trade_no":"1217752501201407033233368018","notify_url":"https://www.weixin.qq.com/wxpay/pay.php","amount":{"total":100,"currency":"CNY"},"payer":{"openid":"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"}}
When the request body is an empty string, simply append a \\n.
3. Request parameters query parameters
Take querying the order by merchant order number as an example:
Step 1: Get the HTTP request method.
GET
Step 2: Get the absolute URL of the request, excluding the domain part.
Concatenate your query parameters. Suppose your query parameters are as follows:
limit=52offset=103authorized_data={"business_type":"FAVOR_STOCK", "stock_id":"2433405"}4partner={"type":"APPID","appid":"wx4e1916a585d1f4e9","merchant_id":"2480029552"}
(1) First, URL encode the authorized_data and partner parameters:
limit=52offset=103authorized_data%3D%7B%22business_type%22%3A%22FAVOR_STOCK%22%2C%20%22stock_id%22%3A%222433405%22%7D4partner%3D%7B%22type%22%3A%22APPID%22%2C%22appid%22%3A%22wx4e1916a585d1f4e9%22%2C%22merchant_id%22%3A%222480029552%22%7D
(2) Concatenate your request URL. The query parameters need to be appended at the end with '?' and the corresponding query string. Multiple strings should be linked with & (Note: The following URL is on one line; due to formatting, it may appear as multiple lines, but the actual data should be on one line).
/v3/pay/transactions/out-trade-no/112233445566?limit=5&offset=10&authorized_data%3D%7B%22business_type%22%3A%22FAVOR_STOCK%22%2C%20%22stock_id%22%3A%222433405%22%7D&partner%3D%7B%22type%22%3A%22APPID%22%2C%22appid%22%3A%22wx4e1916a585d1f4e9%22%2C%22merchant_id%22%3A%222480029552%22%7D
Step 3: Get the current system timestamp when the request is initiated.
This is the total number of seconds from 00:00:00 GMT on January 1, 1970 (08:00:00 Beijing time on January 1, 1970) to the present. The superapp's payment will reject requests made a long time ago, so merchants should ensure their system time is accurate.
date +%s
1554208460
Step 4: Generate a request random string.
E6F165123B4E32D8D0D6
Step 5: Get the request body.
The request body is an empty string, simply append a \\n.
Step 6: Construct the request signature string according to the rules above.
When the request body is an empty string, simply append a \\n.
GET\\n /v3/marketing/partnerships?limit=5&offset=10&authorized_data%3D%7B%22business_type%22%3A%22FAVOR_STOCK%22%2C%20%22stock_id%22%3A%222433405%22%7D&partner%3D%7B%22type%22%3A%22APPID%22%2C%22appid%22%3A%22wx4e1916a585d1f4e9%22%2C%22merchant_id%22%3A%222480029552%22%7D\\n 31554208460\\n E6F165123B4E32D8D0D6\\n \\n
Calculate the signature value
Most programming languages provide functions to sign data. We strongly recommend that merchants use these functions to perform SHA256 with RSA signing on the signature string using their private key, and then Base64 encode the result to get the signature value.
Please pay attention to handling single and double quote escape issues. If the outer layer of the second line uses single quotes, the inner parameters do not need to be escaped. If the outer layer uses double quotes, then the double quotes within the body parameter need to be escaped.
1. Set the HTTP Authorization Header
The request passes the signature through the HTTP Authorization Header. The Authorization Header consists of two parts: the authentication type and the signature information.
Below, we demonstrate how to generate the signature using the command line.
Authorization Header: Authentication type and signature information
The specific composition is:
2. Authentication type. currently WECHATPAY2-SHA256-RSA2048
Merchant ID (mchid) of the merchant initiating the request (including direct merchants, service providers, or channel merchants).
Merchant API certificate serial number (serial_no), used to declare the certificate being used.
Request nonce (nonce_str), which should be consistent with the nonce string used in the signature string construction.
Timestamp (timestamp), which should be consistent with the timestamp used in the signature string construction.
Signature value (signature), calculated as described above.
Note：
The above five signature information items do not have a specific order requirement.
An example of the Authorization Header is as follows. (Note that the example may have line breaks due to formatting, but the actual data should be in one line):
Authorization Header: WECHATPAY2-SHA256-RSA2048 mchid="1900007291",nonce_str="593BEC0C930BF1AFEB40B4A08C8FB242",signature="gEuexJ547PHFV77TQ6eiE4tphVYfWfUe1Wc2dBmVnoMYU2rl/M4zhw+b3vBhuMw6AC7pteNkryLA7UWU2h+umo0OdSuuLm1++O3NckQPCSfm6dypsjn4GYm84KMqXWFrhFmyxEwIdEJDr3w1UYfxOcu55OQupfLkrt/ZzuOspnliJFrPzGQFUk7lGqMMtpz3EfbDUNxnVsHblORg3hVmuYNmbGWnS2ovU30Y2Q+iKFDxzkaXBk8LTy6HzvxizRo6Q+J4SVM7O0hKXfgo1QdI68kpzNULb3EVBXlhTyPUzhkHzzLxECL1qHl3HH2hEv8++C+4wBlsagF3j/O6PABojA==",timestamp="1554208460",serial_no="408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB"
Finally, we can construct an HTTP request that includes the signature.
(1) Please note that the body parameter in the sixth line must be on one line and cannot have line breaks, as the signature calculation was done with the body on one line. The request must be consistent with the signature calculation.
(2) Please ensure that the timestamp="1554208460" and serial_no="408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB" in the Authorization Header are consistent with the values used in the signature calculation.
(3) This is just an example to illustrate the format for reference. Since the example key itself is not functional, the following request is not actually usable.
curl -X POST \\
https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi \\
-H 'Authorization: WECHATPAY2-SHA256-RSA2048 mchid="202003191046",nonce_str="E6F165123B4E32D8D0D6",signature="gEuexJ547PHFV77TQ6eiE4tphVYfWfUe1Wc2dBmVnoMYU2rl/M4zhw+b3vBhuMw6AC7pteNkryLA7UWU2h+umo0OdSuuLm1++O3NckQPCSfm6dypsjn4GYm84KMqXWFrhFmyxEwIdEJDr3w1UYfxOcu55OQupfLkrt/ZzuOspnliJFrPzGQFUk7lGqMMtpz3EfbDUNxnVsHblORg3hVmuYNmbGWnS2ovU30Y2Q+iKFDxzkaXBk8LTy6HzvxizRo6Q+J4SVM7O0hKXfgo1QdI68kpzNULb3EVBXlhTyPUzhkHzzLxECL1qHl3HH2hEv8++C+4wBlsagF3j/O6PABojA==",timestamp="1554208460",serial_no="408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB"' \\
-H 'Accept: application/json' \\
-H 'Content-Type: application/json' \\
-d '{"appid":"mp1bfa1hnwvaluqb","mchid":"202003191046","description":"goods desc","out_trade_no":"84ssadasd125e32463542341342","notify_url":"https://mini.demo.com/pay/callback:","amount":{"total":100,"currency":"USD"},"payer":{"openid":"oae60e19213a17344EhDZBb25849"}}'
