# 1. 接口規(guī)則

為了在保證支付安全的前提下，帶給商戶(hù)簡(jiǎn)單、一致且易用的開(kāi)發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請(qǐng)參考APIv3接口規(guī)則。

# 2. 開(kāi)發(fā)準(zhǔn)備

# 2.1. 搭建和配置開(kāi)發(fā)環(huán)境

為了幫助開(kāi)發(fā)者調(diào)用開(kāi)放接口，我們提供了JAVA、PHP、GO三種語(yǔ)言版本的開(kāi)發(fā)庫(kù)，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語(yǔ)言版本的開(kāi)發(fā)庫(kù)將在近期陸續(xù)提供）。

測(cè)試步驟：

1、根據(jù)自身開(kāi)發(fā)語(yǔ)言，選擇對(duì)應(yīng)的開(kāi)發(fā)庫(kù)并構(gòu)建項(xiàng)目，具體配置請(qǐng)參考下面鏈接的詳細(xì)說(shuō)明：

• wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開(kāi)發(fā)者。
  • 注：當(dāng)前開(kāi)發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
• wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開(kāi)發(fā)者。
  • 注：當(dāng)前開(kāi)發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本。
• wechatpay-go (opens new window)，適用于Go開(kāi)發(fā)者。

更多資源可前往微信支付開(kāi)發(fā)者社區(qū) (opens new window)搜索查看。

2、創(chuàng)建加載商戶(hù)私鑰、加載平臺(tái)證書(shū)、初始化httpClient的通用方法。

3、基于接口的示例代碼，替換請(qǐng)求參數(shù)后可發(fā)起測(cè)試。

說(shuō)明：

• 上面的開(kāi)發(fā)庫(kù)為微信支付官方開(kāi)發(fā)庫(kù)，其它沒(méi)有審核或者控制下的第三方工具和庫(kù)，微信支付不保證它們的安全性和可靠性。通過(guò)包管理工具引入SDK后，可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測(cè)試。
• 開(kāi)發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說(shuō)明：

1. 簽名生成
2. 簽名驗(yàn)證
3. 敏感信息加解密
4. merchantPrivateKey（私鑰）
5. wechatpayCertificates（平臺(tái)證書(shū)）
6. APIV3Key（V3 key）

• 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。

# 2.2. 業(yè)務(wù)開(kāi)發(fā)配置

# 2.2.1. 賬號(hào)申請(qǐng)指引

• 小程序開(kāi)通微信支付，即申請(qǐng)或復(fù)用微信支付商戶(hù)號(hào)，申請(qǐng)完小程序后，登錄小程序后臺(tái) (opens new window)。點(diǎn)擊左側(cè)導(dǎo)航欄的微信支付，在頁(yè)面中進(jìn)行開(kāi)通。（開(kāi)通申請(qǐng)要求小程序已發(fā)布上線(xiàn)）

• 點(diǎn)擊開(kāi)通按鈕后，有2種方式可以獲取微信支付能力，新申請(qǐng)微信支付商戶(hù)號(hào)或綁定一個(gè)已有的微信支付商戶(hù)號(hào)，請(qǐng)根據(jù)你的業(yè)務(wù)需要和具體情況選擇，只能二選一。開(kāi)通指引 (opens new window)

# 2.2.2. 服務(wù)器配置要求

1. 小程序訪(fǎng)問(wèn)商戶(hù)服務(wù)都是通過(guò)HTTPS,開(kāi)發(fā)部署的時(shí)候需要HTTPS服務(wù)器。

2. 服務(wù)器域名配置。

   • 每個(gè)微信小程序需要事先設(shè)置通信域名，小程序只可以跟指定的域名進(jìn)行網(wǎng)絡(luò)通信。包括普通 HTTPS 請(qǐng)求(wx.request)、上傳文件(wx.uploadFile)、下載文件(wx.downloadFile)和 WebSocket 通信(wx.connectSocket)
   • 從基礎(chǔ)庫(kù) 2.4.0 開(kāi)始，網(wǎng)絡(luò)接口允許與局域網(wǎng) IP 通信，但要注意 不允許與本機(jī) IP 通信

# 3. 快速接入

# 3.1. 業(yè)務(wù)流程圖

重點(diǎn)步驟說(shuō)明：

步驟4： 用戶(hù)下單發(fā)起支付，商戶(hù)可通過(guò)JSAPI下單創(chuàng)建支付訂單。

步驟9： 商戶(hù)小程序內(nèi)使用小程序調(diào)起支付API（wx.requestPayment）發(fā)起微信支付，詳見(jiàn)小程序API文檔 (opens new window)。

步驟16： 用戶(hù)支付成功后，商戶(hù)可接收到微信支付支付結(jié)果通知支付通知API。

步驟21： 商戶(hù)在沒(méi)有接收到微信支付結(jié)果通知的情況下需要主動(dòng)調(diào)用查詢(xún)訂單API查詢(xún)支付結(jié)果。

# 3.2. API接入（含示例代碼）

本章節(jié)展示了如何使用微信支付服務(wù)端 SDK 快速接入小程序支付產(chǎn)品，完成與微信支付對(duì)接的部分。

# 3.2.1. 【服務(wù)端】小程序下單

步驟說(shuō)明：

用戶(hù)通過(guò)商戶(hù)小程序進(jìn)入商戶(hù)網(wǎng)頁(yè)，當(dāng)用戶(hù)選擇相關(guān)商品購(gòu)買(mǎi)時(shí)，商戶(hù)系統(tǒng)先調(diào)用該接口在微信支付服務(wù)后臺(tái)生成預(yù)支付交易單。

重要入?yún)⒄f(shuō)明：

• out_trade_no： 商戶(hù)系統(tǒng)內(nèi)部訂單號(hào)，只能是數(shù)字、大小寫(xiě)字母_-*且在同一個(gè)商戶(hù)號(hào)下唯一。
• description： 商品描述。
• notify_url： 支付回調(diào)通知URL，該地址必須為直接可訪(fǎng)問(wèn)的URL，不允許攜帶查詢(xún)串。
• total： 訂單總金額，單位為分。
• OpenID： OpenID是微信用戶(hù)在AppID下的唯一用戶(hù)標(biāo)識(shí)（AppID不同，則獲取到的OpenID就不同），可用于永久標(biāo)記一個(gè)用戶(hù)。OpenID獲取方式請(qǐng)參考以下文檔小程序獲取OpenID (opens new window)、公眾號(hào)獲取OpenID (opens new window)、App獲取OpenID (opens new window)。

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)JSAPI下單接口文檔。

# 3.2.2.【客戶(hù)端】小程序調(diào)起支付API

步驟說(shuō)明： 通過(guò)JSAPI下單API成功獲取預(yù)支付交易會(huì)話(huà)標(biāo)識(shí)（prepay_id） 后，需要通過(guò)JSAPI調(diào)起支付API來(lái)調(diào)起微信支付收銀臺(tái)。

重要入?yún)⒄f(shuō)明：

• package： JSAPI下單接口返回的prepay_id參數(shù)值，提交格式如：prepay_id=***。
• signType： 該接口V3版本僅支持RSA。
• paySign： 簽名。

paySign生成規(guī)則、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 小程序調(diào)起支付接口文檔。

# 3.2.3. 【服務(wù)端】接收支付結(jié)果通知

步驟說(shuō)明： 當(dāng)用戶(hù)完成支付，微信會(huì)把相關(guān)支付結(jié)果將通過(guò)異步回調(diào)的方式通知商戶(hù)，商戶(hù)需要接收處理，并按文檔規(guī)范返回應(yīng)答

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 支付結(jié)果通知接口文檔。

# 3.2.4. 【服務(wù)端】查詢(xún)訂單

步驟說(shuō)明： 當(dāng)商戶(hù)后臺(tái)、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常，商戶(hù)系統(tǒng)最終未接收到支付通知時(shí)，商戶(hù)可通過(guò)查詢(xún)訂單接口核實(shí)訂單支付狀態(tài)。

示例代碼(通過(guò)微信訂單號(hào)查詢(xún))：

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 微信支付訂單號(hào)/商戶(hù)訂單號(hào)接口文檔。

# 3.2.5. 【服務(wù)端】關(guān)閉訂單

步驟說(shuō)明： 當(dāng)商戶(hù)訂單支付失敗需要生成新單號(hào)重新發(fā)起支付，要對(duì)原訂單號(hào)調(diào)用關(guān)單，避免重復(fù)支付；系統(tǒng)下單后，用戶(hù)支付超時(shí)，系統(tǒng)退出不再受理，避免用戶(hù)繼續(xù)，請(qǐng)調(diào)用關(guān)單接口。

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 關(guān)閉訂單接口文檔

# 3.2.6. 【服務(wù)端】申請(qǐng)交易賬單

步驟說(shuō)明： 微信支付按天提供交易賬單文件，商戶(hù)可以通過(guò)該接口獲取賬單文件的下載地址。

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 申請(qǐng)交易賬單接口文檔。

# 3.2.7. 【服務(wù)端】下載賬單

步驟說(shuō)明： 申請(qǐng)交易賬單接口獲取到賬單下載地址（download_url）后，再通過(guò)該接口獲取到對(duì)應(yīng)的賬單文件，文件內(nèi)包含交易相關(guān)的金額、時(shí)間、營(yíng)銷(xiāo)等信息，供商戶(hù)核對(duì)訂單、退款、銀行到賬等情況。

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 下載賬單接口文檔。

# 4. 常見(jiàn)問(wèn)題

# Q：在小程序內(nèi)通過(guò)外部H5頁(yè)面調(diào)起支付報(bào)錯(cuò)

A：在小程序內(nèi)通過(guò)外部H5頁(yè)面調(diào)起支付報(bào)錯(cuò)。

# Q：調(diào)起小程序支付報(bào)“商戶(hù)號(hào)該產(chǎn)品權(quán)限未開(kāi)通”

A：請(qǐng)按以下幾點(diǎn)進(jìn)行排查：

1. 請(qǐng)檢查請(qǐng)求參數(shù)是否正確，如請(qǐng)求參數(shù)中的AppID是否與小程序?qū)?yīng)。
2. AppID對(duì)應(yīng)的小程序是否有開(kāi)通小程序支付功能，權(quán)限狀態(tài)是否正常，可登錄商戶(hù)平臺(tái)核實(shí)。
3. AppID與商戶(hù)號(hào)是否存在綁定關(guān)系，可登錄商戶(hù)平臺(tái)核實(shí)。

# Q：小程序開(kāi)通微信支付有哪幾種方式

A：可通過(guò)以下兩種方式開(kāi)通:

1. 綁定已有公眾號(hào)的微信支付：耗時(shí)10分鐘即可，只需原有公眾號(hào)開(kāi)通微信支付，小程序微信支付可以選擇綁定原來(lái)的微信支付商戶(hù)號(hào)，即可開(kāi)通成功。
2. 新申請(qǐng)微信支付：耗時(shí)需要1-5個(gè)工作日，需要提交和申請(qǐng)小程序一樣的資料進(jìn)行審核，審核通過(guò)后才能開(kāi)通成功。