wechatpay postman script

微信支付APIv3 Postman 腳本

微信支付APIv3 的Postman 請求前置腳本（Pre-Request Script）。

為了幫助商家開發者快速上手，我們將腳本部署到Postman 雲端工作台WeChat Pay Public Workspace。你不用手動導入腳本，只需要將集合《微信支付APIv3》 fork 到自己的工作台，就可以在Postman 上輕鬆地構造並發送微信支付APIv3 請求了。

前置條件

• Postman，一款業界知名的API 建置與使用平台。建議註冊一個帳戶，以便於使用它各種功能。
• 成為微信支付商戶。
• 商家API 私鑰：商家申請商家API憑證時，會產生商家私鑰，並儲存於本機憑證資料夾的檔案apiclient_key.pem 中。

快速開始

步驟1：Fork 方式匯入腳本

點選按鈕進入嚮導，如下圖所示。

點選Fork Collection進入下一步，填入標籤Fork Label並選擇目的工作台Workspace 。一般情況下，導入個人工作台My Workspace 即可。

點選Fork Collection完成匯入。在你指定的workspace 中可以看到《微信支付APIv3》了。

你也可以本地導入腳本。

步驟2：配置Environment

環境（Environment） 是一組變數(Varibles) 的集合。 腳本從環境中讀取變量，用來計算請求的簽名。

你可以從《微信支付APIv3》提供的商家參數模版中fork 一個空環境到自己的工作台。

接下來，在你工作台的Enviroments 中找到新建的環境，點選Add a new varialbe新增的變數：

• mchid ：必填，商家號碼。
• merchant_serial_no ：必填，商家API 憑證序號。
• apiclient_key.pem ：必填，PEM 格式的商家API 私鑰。

Warning為了安全，請仔細閱讀安全注意事項。

一組常見配置如下圖所示。

步驟3：發送請求

Note我們建議，使用桌面版Postman app 發送請求，速度更快，體驗更好！

現在回到工作台，進入《微信支付APIv3》集合，選擇你要發送的請求。

然後，填入請求參數，依照註解修改Body 中的參數。

最後，選​​擇你之前設定的Environment，再點擊網址列右側的Send按鈕，發送請求吧。

實現原理

Pre-Request Script是一段Javascript 腳本。 Postman 在請求發送之前，執行這段腳本。腳本做了以下操作：

1. 載入依賴函式庫
2. 讀取Environment 中的商家參數變數
3. 根據請求的方法、URL、參數、Body 等訊息，建構簽名串，並計算請求簽名
4. 設定請求頭Authorization

Note有關Postman 腳本的更多信息，請參考Scripting in Postman。

參數變數

變數名	是否必填	描述	備註
mchid	是	商家號
merchant_serial_no	是	商家API 憑證的憑證序號
apiclient_key.pem	是	PEM 格式的商家API 私鑰
openid	否	使用者的OpenID，測試請求中的{{openid}}
appid	否	公眾帳號或小程式的AppID
shangmi	否	值為true時使用商密簽名	預設值為空，即使用RSA 簽名
pubkey.pem	國密簽名時必填	PEM 格式的商家API 公鑰	如果私鑰PEM 中包含公鑰，該變數可不填
server_url	否	伺服器位址	預設為https://api.mch.weixin.qq.com

依賴函式庫

腳本直接使用了：

• forge.min.js，forge 的PKI、RSA 和ASN.1。
• sm2.js，騰訊國密庫TencentSM-javascript 的SM2 簽章。

為了避免每次請求都下載依賴庫，兩個庫以原始程式碼的方式儲存在Collection Variables。這大大減少了使用網頁版Postman 發送請求時的耗時。

安全注意事項

商家API 私鑰是非常敏感的資訊。使用此程式碼時，應記住以下幾點：

• 將配置了私鑰的工作台（workspace）的可見性（Visibility）設定為私有Personal或Private ，不要設定為公開Public 。
• 私鑰的變數類型設定為secret 。變數值會以遮罩的形式顯示在螢幕上。
• 私鑰的變數值設定在Current Value 。 Current Value只保存在本機Session，不會被傳送至Postman 的伺服器。
• 如果使用來自其他人的Postman 腳本，請檢查依賴函式庫、變數和腳本，確保沒有被修改，避免被植入不安全程式碼。

Note有關Postman 的安全機制，請參考Postman Security。

如何發起國密請求

使用國密-商家參數模版，在環境變數中設定：

• shangmi ：值為true 。
• mchid ：必填，商家號碼。
• merchant_serial_no ：必填，商家API 憑證序號。
• apiclient_key.pem ：必填，PEM 格式的商家API 私鑰。
• pubkey.pem ：必填，PEM 格式的商家API 國密公鑰。

這樣，腳本會使用國密SM2 計算簽名，發送國密請求了。

本地導入腳本

Note不建議本地導入腳本，不但麻煩而且容易出錯，還不能同步上游的變更

Fork Collection 匯入需要註冊Postman 帳戶。如果你不希望註冊，可以本地導入腳本。

首先，開啟WeChatPay APIv3 集合，展開選項後點選Export：

下載並儲存wechatpay-apiv3.postman_collection.json檔案至本地。然後，有兩種方式本地導入JSON 檔案：

• Postman 介面左上角的Import按鈕
• 選單File > Import發起導入

選擇本地的wechatpay-apiv3.postman_collection.json ，點擊確認後，匯入就完成了。

你會發現在工作台的Collections 中新增了一組名為《WeChatPay APIv3》的請求。配置Environment 後即可發送請求。

同步上游的變更

我們會逐步新增介面和更新已有接口，但是你fork 到自己工作台的集合分支並不會自動同步上游的變更。建議關注watch我們的Public Workspace，這樣上游變更時你會收到來自postman 的通知。

這時，你可使用pull changes來拉取上游的變更。

postman 的pull changes可能需要等待一定時間完成。如果遇到問題，重新fork 也是一個好方法。

常見問題

發送請求時遇到錯誤提示“Error: Too few bytes to parse DER.”或“Too few bytes to read ASN.1 value.”

通常是環境Environments 裡配置的變數merchantPrivateKey填寫有誤導致的。腳本收到的私鑰，以-----BEGIN PRIVATEKEY-----開始，以-----END PRIVATE KEY-----結束的一串字串。

為什麼我發送請求很慢？

如果你使用的網頁版Postman，請使用桌面版Postman app。因為瀏覽器中跨網域資源共享（CORS）的限制，網頁版發送請求是由Postman 後台中轉的。

或使用Postman desktop agent，更多資訊請參考Postman 相關部落格。

聯絡我們

如果你有任何疑問，歡迎造訪我們的開發者社群進行回饋。

我們也歡迎各式各樣的issue 和Merge Request:-)