wechatpay postman script

WeChat payment APIv3 Postman script

WeChat Payment APIv3 Postman request pre-request script (Pre-Request Script).

In order to help merchant developers get started quickly, we deploy the script to the Postman cloud workbench WeChat Pay Public Workspace. You don't need to manually import the script, you only need to fork the collection "WeChat Payment APIv3" to your workbench, and you can easily construct and send WeChat Payment APIv3 requests on Postman.

Preconditions

• Postman, an industry-renowned platform for building and using APIs. It is recommended to register an account to use its various functions.
• Become a WeChat payment merchant.
• Merchant API private key: When a merchant applies for a merchant API certificate, the merchant private key will be generated and saved in the file apiclient_key.pem in the local certificate folder.

quick start

Step 1: Fork import script

Click the button to enter the wizard, as shown below.

Click Fork Collection to proceed to the next step, fill in the label Fork Label and select the destination workspace Workspace . Under normal circumstances, it is enough to import the personal workbench My Workspace.

Click Fork Collection to complete the import. You can see "WeChat Payment APIv3" in your designated workspace.

You can also import scripts locally.

Step 2: Configure Environment

Environment is a collection of variables. The script reads variables from the environment and uses them to calculate the signature of the request.

You can fork an empty environment from the merchant parameter template provided by "WeChat Payment APIv3" to your own workbench.

Next, find the newly created environment in Environments on your workbench and click Add a new varialbe to add a new variable:

• mchid : required, merchant number.
• merchant_serial_no : required, merchant API certificate serial number.
• apiclient_key.pem : Required, merchant API private key in PEM format.

WarningFor safety, please read the safety precautions carefully.

A common set of configurations is shown below.

Step 3: Send a request

Note: We recommend using the desktop Postman app to send requests, which is faster and has a better experience!

Now return to the workbench, enter the "WeChat Payment APIv3" collection, and select the request you want to send.

Then, fill in the request parameters and modify the parameters in the Body according to the comments.

Finally, select the Environment you configured previously and click the Send button on the right side of the address bar to send the request.

Implementation principle

Pre-Request Script is a Javascript script. Postman executes this script before sending the request. The script does the following:

1. Load dependent libraries
2. Read the merchant parameter variables in Environment
3. Construct a signature string based on the requested method, URL, parameters, Body and other information, and calculate the request signature
4. Set request header Authorization

NoteFor more information about Postman scripting, see Scripting in Postman.

parameter variable

variable name	Is it required?	describe	Remark
mchid	yes	Merchant number
merchant_serial_no	yes	Certificate serial number of merchant API certificate
apiclient_key.pem	yes	Merchant API private key in PEM format
openid	no	The user's OpenID, {{openid}} in the test request
appid	no	AppID of public account or mini program
shangmi	no	Use commercial secret signature when the value is true	The default value is empty, which means using RSA signature
pubkey.pem	Required when signing with state secrets	Merchant API public key in PEM format	If the private key PEM contains the public key, this variable does not need to be filled in
server_url	no	Server address	The default setting is https://api.mch.weixin.qq.com

Dependent libraries

The script uses directly:

• forge.min.js, PKI, RSA and ASN.1 for forge.
• sm2.js, the SM2 signature of Tencent's national secret library TencentSM-javascript.

In order to avoid downloading dependent libraries on every request, the two libraries are stored in Collection Variables as source code. This greatly reduces the time taken when sending requests using the web version of Postman.

Safety precautions

Merchant API private keys are very sensitive information. When using this code, you should keep the following points in mind:

• Set the visibility of the workspace configured with the private key to Personal or Private , and do not set it to Public .
• The variable type of the private key is set to secret . The variable values ​​are displayed on the screen in the form of a mask.
• The variable value of the private key is set in Current Value . Current Value is only saved in the local Session and will not be sent to the Postman server.
• If you use a Postman script from someone else, please check the dependent libraries, variables, and scripts to make sure they have not been modified to avoid implanting unsafe code.

NoteFor information about Postman's security mechanism, please refer to Postman Security.

How to initiate a state secrets request

Use the National Secret-Merchant parameter template and set it in the environment variable:

• shangmi : The value is true .
• mchid : required, merchant number.
• merchant_serial_no : required, merchant API certificate serial number.
• apiclient_key.pem : Required, merchant API private key in PEM format.
• pubkey.pem : required, merchant API national secret public key in PEM format.

In this way, the script will use the national secret SM2 to calculate the signature and send the national secret request.

local import script

Note: It is not recommended to import scripts locally. It is cumbersome and error-prone and cannot synchronize upstream changes.

Fork Collection import requires registering a Postman account. If you don't want to register, you can import the script locally.

First, open the WeChatPay APIv3 collection, expand the options and click Export:

Download and save the wechatpay-apiv3.postman_collection.json file locally. Then, there are two ways to import the JSON file locally:

• The Import button in the upper left corner of the Postman interface
• Menu File > Import initiates the import

Select the local wechatpay-apiv3.postman_collection.json and click Confirm to complete the import.

You will find that a new set of requests named "WeChatPay APIv3" has been added to the Collections on the workbench. After configuring the Environment, you can send the request.

Sync upstream changes

We will gradually add new interfaces and update existing interfaces, but the collection branch you fork to your workbench will not automatically synchronize upstream changes. It is recommended to watch our Public Workspace so that you will receive notifications from postman when upstream changes are made.

At this time, you can use pull changes to pull the upstream changes.

Postman's pull changes may take some time to complete. If you encounter problems, re-forking is also a good idea.

FAQ

When sending a request, an error message "Error: Too few bytes to parse DER." or "Too few bytes to read ASN.1 value." is encountered.

It is usually caused by incorrectly filling in the variable merchantPrivateKey configured in the Environment. The private key received by the script is a string starting with -----BEGIN PRIVATEKEY----- and ending with -----END PRIVATE KEY----- .

Why is my sending request so slow?

If you are using the web version of Postman, please use the desktop Postman app. Due to the limitations of cross-origin resource sharing (CORS) in browsers, requests sent by the web version are forwarded by Postman in the background.

Or use Postman desktop agent. For more information, please refer to Postman related blogs.

Contact us

If you have any questions, please visit our developer community for feedback.

We also welcome all kinds of issues and Merge Requests:-)