# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。
# 2. 開發(fā)準(zhǔn)備
# 2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）。
測試步驟：
1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項(xiàng)目，具體配置請參考下面鏈接的詳細(xì)說明：
- wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開發(fā)者。
- 注：當(dāng)前開發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開發(fā)者。
- 注：當(dāng)前開發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，適用于Go開發(fā)者。
更多資源可前往微信支付開發(fā)者社區(qū) (opens new window)搜索查看。
2、創(chuàng)建加載商戶私鑰、加載平臺證書、初始化httpClient的通用方法。
3、基于接口的示例代碼，替換請求參數(shù)后可發(fā)起測試。
說明：
- 上面的開發(fā)庫為微信支付官方開發(fā)庫，其它沒有審核或者控制下的第三方工具和庫，微信支付不保證它們的安全性和可靠性。通過包管理工具引入SDK后，可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測試。
- 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說明：
- 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
重點(diǎn)步驟說明：
步驟3： 用戶發(fā)起投訴后，微信支付通過投訴通知回調(diào)通知商戶投訴單需處理。
步驟6： 商戶接收投訴后，可通過回復(fù)用戶API接口向微信支付提交投訴處理回復(fù)。
步驟9： 與用戶協(xié)商一致后，商戶通過反饋處理完成API反饋投訴單處理完成。
步驟15： 商戶在沒有接收到微信投訴通知的情況下可主動調(diào)用查詢投訴單詳情查詢投訴單處理結(jié)果。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評估、修改。
# 3.2.1. 【服務(wù)端】查詢投訴單列表
步驟說明：商戶可通過調(diào)用此接口，查詢指定時(shí)間段的所有用戶投訴信息，以分頁輸出查詢結(jié)果。
重要入?yún)⒄f明：
- begin_date： 開始日期，投訴發(fā)生的開始日期，格式為yyyy-MM-dd。注意，查詢?nèi)掌诳缍炔怀^30天。
- end_date： 結(jié)束日期，投訴發(fā)生的結(jié)束日期，格式為yyyy-MM-dd。注意，查詢?nèi)掌诳缍炔怀^30天。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見查詢投訴單列表接口文檔。
# 3.2.2.【服務(wù)端】查詢投訴單詳情
步驟說明：商戶可通過調(diào)用此接口，查詢指定投訴單的用戶投訴詳情，包含投訴內(nèi)容、投訴關(guān)聯(lián)訂單、投訴人聯(lián)系方式等信息，方便商戶處理投訴。
重要入?yún)⒄f明：
- complaint_id： 投訴單對應(yīng)的投訴單號，在投訴通知回調(diào)中會返回這個(gè)參數(shù)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見查詢投訴單詳情接口文檔。
# 3.2.3. 【服務(wù)端】查詢投訴協(xié)商歷史
步驟說明： 商戶可通過調(diào)用此接口，查詢指定投訴的用戶商戶協(xié)商歷史，以分頁輸出查詢結(jié)果，方便商戶根據(jù)處理歷史來制定后續(xù)處理方案。
重要入?yún)⒄f明：
- complaint_id： 投訴單對應(yīng)的投訴單號，在投訴通知回調(diào)中會返回這個(gè)參數(shù)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見查詢投訴協(xié)商歷史接口文檔。
# 3.2.4. 【服務(wù)端】投訴通知回調(diào)
步驟說明： 商戶創(chuàng)建投訴通知回調(diào)URL 后，當(dāng)有新的投訴事件發(fā)生、投訴狀態(tài)發(fā)生變化時(shí)，商戶會收到通知回調(diào)。商戶需要接收處理，并按文檔規(guī)范返回應(yīng)答。
注意
- 投訴通知是以POST 方法訪問商戶設(shè)置的通知URL，通知的數(shù)據(jù)以JSON 格式通過請求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進(jìn)行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當(dāng)驗(yàn)證簽名，以確認(rèn)請求來自微信，而不是其他的第三方。簽名驗(yàn)證的算法請參考 《微信支付API v3簽名驗(yàn)證》。
- 投訴通知HTTP應(yīng)答碼為200或204才會當(dāng)作正常接收，當(dāng)回調(diào)處理異常時(shí)，應(yīng)答的HTTP狀態(tài)碼應(yīng)為500，或者4xx。
- 商戶成功接收到回調(diào)通知后應(yīng)返回成功的HTTP應(yīng)答碼為200或204。
- 同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。 推薦的做法是，當(dāng)商戶系統(tǒng)收到通知進(jìn)行處理時(shí)，先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，并判斷該通知是否已經(jīng)處理。如果未處理，則再進(jìn)行處理；如果已處理，則直接返回結(jié)果成功。在對業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見投訴通知回調(diào)接口文檔。
# 3.2.5. 【服務(wù)端】創(chuàng)建投訴通知回調(diào)地址
步驟說明： 商戶通過調(diào)用此接口創(chuàng)建投訴通知回調(diào)URL，當(dāng)用戶產(chǎn)生新投訴且投訴狀態(tài)已變更時(shí)，微信支付會通過回調(diào)URL通知商戶。
重要入?yún)⒄f明：
- URL: 通知地址，通知地址，僅支持HTTPS。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見創(chuàng)建投訴通知回調(diào)地址接口文檔。
# 3.2.6.【服務(wù)端】查詢投訴通知回調(diào)地址
步驟說明： 商戶通過調(diào)用此接口查詢投訴通知的回調(diào)URL。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見查詢投訴通知回調(diào)地址接口文檔。
# 3.2.7. 【服務(wù)端】更新投訴通知回調(diào)地址
步驟說明： 商戶通過調(diào)用此接口創(chuàng)建投訴通知回調(diào)URL，當(dāng)用戶產(chǎn)生新投訴且投訴狀態(tài)已變更時(shí)，微信支付會通過回 調(diào)URL通知商戶。
重要入?yún)⒄f明：
- URL: 通知地址，通知地址，僅支持HTTPS。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見更新投訴通知回調(diào)地址接口文檔。
# 3.2.8. 【服務(wù)端】刪除投訴通知回調(diào)地址
步驟說明： 商戶通過調(diào)用此接口查詢投訴通知的回調(diào)URL。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見刪除投訴通知回調(diào)地址接口文檔。
# 3.2.9. 【服務(wù)端】提交回復(fù)
步驟說明：商戶可調(diào)用此接口回復(fù)用戶。其中上傳圖片憑證需首先調(diào)用商戶上傳反饋圖片接口，得到圖片ID，再將ID填入請求。
重要入?yún)⒄f明：
- complaint_id： 投訴單對應(yīng)的投訴單號。
- complainted_mchid： 被訴商戶號，投訴單對應(yīng)的被訴商戶號。
- response_content： 回復(fù)內(nèi)容，具體的投訴處理方案，限制200個(gè)字符以內(nèi)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見提交回復(fù)接口文檔。
# 3.2.10. 【服務(wù)端】反饋處理完成
步驟說明： 商戶可通過調(diào)用此接口，反饋投訴單已處理完成。
重要入?yún)⒄f明：
- complaint_id： 投訴單對應(yīng)的投訴單號，在投訴通知回調(diào)中會返回這個(gè)參數(shù)。
- complainted_mchid： 被訴商戶號，投訴單對應(yīng)的被訴商戶號。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見反饋處理完成接口文檔。
# 3.2.11. 【服務(wù)端】商戶上傳反饋圖片
步驟說明： 商戶上傳反饋圖片的接口。 將媒體圖片進(jìn)行二進(jìn)制轉(zhuǎn)換，得到的媒體圖片二進(jìn)制內(nèi)容，在請求body中上傳此二進(jìn)制內(nèi)容。 媒體圖片只支持jpg、png、bmp格式，文件大小不能超過2M。
重要入?yún)⒄f明：
- file： 圖片文件，將媒體圖片進(jìn)行二進(jìn)制轉(zhuǎn)換，得到的媒體圖片二進(jìn)制內(nèi)容，在請求body中上傳此二進(jìn)制內(nèi)容。媒體圖片只支持jpg、png、bmp格式，文件大小不能超過2M。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見商戶上傳反饋圖片接口文檔。
# 4. 常見問題
# Q：商戶反饋API，查詢投訴單列表 API頻率是多少？
A：商戶反饋API每分鐘60次，查詢投訴單列表 API頻率是每分鐘200次。
# Q：商戶反饋API，商戶傳給微信側(cè)的反饋和留言是同步實(shí)時(shí)處理的嗎？
A：是實(shí)時(shí)的，會直接展示給用戶。
# Q：投訴通知回調(diào)API中的通知ID，在重復(fù)通知的情況下，ID是一致的嗎？
A：微信存在重復(fù)通知的情況，關(guān)于重復(fù)通知的客戶投訴，通知ID是一致的。
# Q：設(shè)置了投訴通知URL，存在用戶投訴，但收不到投訴通知的情況，如何解決？
A：請按照以下幾點(diǎn)進(jìn)行排查：
- 請檢查回調(diào)URL是否能正常公網(wǎng)訪問，不能是中文域名，不能是HTTP，必須是HTTPS；
- 請注意回調(diào)URL不能攜帶參數(shù)；
- 請檢查是否開啟了防火墻，如果開啟了防火墻，請?zhí)砑?a target="_blank" rel="noopener noreferrer">微信支付回調(diào)IP (opens new window)；
- 請檢查設(shè)置通知URL的商戶號與投訴訂單的商戶號是否為同一個(gè)；
- APIv3密鑰沒有設(shè)置，設(shè)置路徑：【微信商戶平臺 (opens new window)—>賬戶設(shè)置—>API安全—>設(shè)置APIv3密鑰】。
