DOCSEARCHbyAlgolia
Submit Docs

WeChat Pay APIv3 Postman Script

repository·master·Indexed 19 days ago

https://github.com/wechatpay-apiv3/wechatpay-postman-script

A Postman collection and Pre-Request script for testing WeChat Pay APIv3. It automates header construction and complex signature generation using RSA and SM2 (Guomi) based on merchant credentials, including mchid, merchant_serial_no, and apiclient_key.pem.

Tokens
1.2K
Snippets
1
Records
6
Agent score
15%

What's inside wechatpay-postman-script

  1. How the Pre-Request Script works

    master

    The script is a JavaScript snippet executed by Postman before every request. It automates the following lifecycle:

    1. Loads dependencies: Uses forge.min.js (for PKI/RSA/ASN.1) and sm2.js (for Tencent SM2 signatures) stored in Collection Variables to avoid network latency.
    2. Reads Environment: Retrieves merchant parameters (mchid, keys, etc.) from the active Postman Environment.
    3. Constructs Signature: Based on the HTTP method, URL, parameters, and Body, it generates the signature string and calculates the signature.
    4. Sets Headers: Automatically populates the Authorization header required by WeChat Pay APIv3.

  2. Quickstart: Import WeChat Pay APIv3 Collection via Fork

    master

    The easiest way to use the script is to fork the official collection to your own Postman workspace. This avoids manual imports and allows you to sync future updates.

    1. Click the Run in Postman button.
    2. Click Fork Collection.
    3. Enter a Fork Label and select your destination Workspace (usually My Workspace).
    4. Click Fork Collection again to complete the process.
    [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/3391715-85f478d8-2596-420a-9f21-53376fc6ad0a?action=collection%2Ffork&collection-url=entityId%3D3391715-85f478d8-2596-420a-9f21-53376fc6ad0a%26entityType%3Dcollection%26workspaceId%3D5f619604-11ee-42a4-b148-22abec1f0611)

  3. Configure Postman Environment Variables

    master

    The Pre-Request Script calculates signatures by reading variables from a Postman Environment. You should fork the Merchant Parameter Template to your workspace and then add/update the following variables:

    • mchid: (Required) Merchant ID.
    • merchant_serial_no: (Required) Merchant API certificate serial number.
    • apiclient_key.pem: (Required) Merchant API private key in PEM format.
    • openid: (Optional) User's OpenID.
    • appid: (Optional) Public Account or Mini Program AppID.
    • shangmi: (Optional) Set to true to use SM2 (Guomi) signatures. Defaults to RSA.
    • pubkey.pem: (Required for SM2) Merchant API public key in PEM format. If the private key PEM already contains the public key, this is not required.
    • server_url: (Optional) Server URL. Defaults to https://api.mch.weixin.qq.com.

  5. Security Best Practices for Merchant Private Keys

    master

    Since the apiclient_key.pem is highly sensitive, follow these security rules in Postman:

    • Workspace Visibility: Set your workspace visibility to Personal or Private. Never use a Public workspace for sensitive keys.
    • Variable Type: Set the variable type to secret. This masks the value on your screen.
    • Variable Value: Always put the actual key in the Current Value column. Current Value is only saved in your local Postman session and is not synced to Postman's servers. Avoid putting sensitive keys in Initial Value.

  6. Troubleshooting common Postman errors

    master

    DER/ASN.1 Parsing Errors

    Error: Error: Too few bytes to parse DER. or Too few bytes to read ASN.1 value. Cause: The apiclient_key.pem variable is incorrect. The script expects a string starting with -----BEGIN PRIVATE KEY----- and ending with -----END PRIVATE KEY-----.

    PEM Formatting Errors

    Error: There was an error in evaluating the Pre-request Script: Error: Invalid PEM formatted message. Cause: You likely placed the key in the Initial value column instead of the Current value column. Move the value to Current value to ensure the script can read it.

    Slow Request Performance

    Issue: Requests are slow or timing out. Solution: If using the web version of Postman, requests are proxied through Postman's backend due to CORS limits. Use the Postman Desktop App or the Postman Desktop Agent for significantly better performance.