# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。
# 2. 開發(fā)準備
# 2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）。
測試步驟：
1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項目，具體配置請參考下面鏈接的詳細說明：
- wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開發(fā)者。
- 注：當前開發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開發(fā)者。
- 注：當前開發(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ù)下面每個接口的示例代碼替換相關(guān)參數(shù)后進行快速測試。
- 開發(fā)者如果想詳細了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn)，可閱讀下面的詳細說明：
- 如想更詳細的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
重點步驟說明：
智慧商圈接入前需先郵件申請接入權(quán)限，申請發(fā)放具體可查看智慧商圈接入流程，小程序插件可參考：小程序插件開發(fā)文檔 (opens new window)
步驟10 商圈支付結(jié)果通知（已開通積分功能的用戶，在場內(nèi)發(fā)生交易時，會將交易信息返回至開通時提交的回調(diào)地址）
步驟12 商圈積分同步（只有接入該接口，才會獲取到退款信息）
步驟13 商圈退款成功通知（對已同步過積分的交易，監(jiān)控30天內(nèi)的退款情況，若發(fā)生退款，則會把相關(guān)退款通知發(fā)送給商圈商戶，商戶的回調(diào)地址同支付結(jié)果回調(diào)地址保持一致）
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入智慧商圈產(chǎn)品，完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請商戶結(jié)合自身業(yè)務(wù)需求進行評估、修改。
# 3.2.1. 【客戶端】商圈快速積分小程序插件
微信支付智慧商圈，需先接入商圈快速積分小程序插件。小程序插件可參考：小程序插件開發(fā)文檔 (opens new window)
# 3.2.2. 【服務(wù)端】接收商圈支付結(jié)果通知
步驟說明：當用戶完成支付，微信會把相關(guān)支付結(jié)果將通過異步回調(diào)的方式通知商戶，商戶需要接收處理，并按文檔規(guī)范返回應(yīng)答。
注意
- 支付結(jié)果通知是以POST 方法訪問商戶設(shè)置的通知URL，通知的數(shù)據(jù)以JSON 格式通過請求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當驗證簽名，以確認請求來自微信，而不是其他的第三方。簽名驗證的算法請參考 《微信支付API v3簽名驗證》。
- 支付通知HTTP應(yīng)答碼為200或204才會當作正常接收，當回調(diào)處理異常時，應(yīng)答的HTTP狀態(tài)碼應(yīng)為500，或者4xx。
- 商戶成功接收到回調(diào)通知后應(yīng)返回成功的HTTP應(yīng)答碼為200或204。
- 同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。 推薦的做法是，當商戶系統(tǒng)收到通知進行處理時，先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，并判斷該通知是否已經(jīng)處理。如果未處理，則再進行處理；如果已處理，則直接返回結(jié)果成功。在對業(yè)務(wù)數(shù)據(jù)進行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。
- 對后臺通知交互時，如果微信收到商戶的應(yīng)答不符合規(guī)范或超時，微信認為通知失敗，微信會通過一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 總計 24h4m）。
接入順序：
- “商圈會員快速積分”小程序插件開發(fā)文檔 (opens new window)。
- 商圈會員積分服務(wù)授權(quán)結(jié)果通知（用戶在商圈小程序完成會員積分服務(wù)授權(quán)后，會將用戶的授權(quán)情況發(fā)送至開通時配置的會員積分服務(wù)開通回調(diào)地址）。
- 商圈會員場內(nèi)支付結(jié)果通知（已授權(quán)商圈會員積分服務(wù)的用戶，在場內(nèi)發(fā)生微信支付交易時，會將消費信息發(fā)送至開通時配置的用戶消費回調(diào)地址）。
- 商圈積分通知回調(diào)（只有接入該接口，才會獲取到退款信息）。
- 商圈會員場內(nèi)退款通知（對已同步過積分的會員消費，監(jiān)控30天內(nèi)的退款情況，若發(fā)生退款，會將退款信息發(fā)送至開通時配置的用戶消費回調(diào)地址）。
- 商圈積分授權(quán)查詢 （可通過此API查詢已授權(quán)過商圈會員積分服務(wù)用戶的最新授權(quán)狀態(tài)）。
- 查詢商圈會員待積分狀態(tài)（可通過此API查詢已授權(quán)商圈會員積分服務(wù)的用戶當天是否有待積分的消費，并可在商圈小程序任意頁面引導(dǎo)用戶前往“商圈會員快速積分”插件提交積分申請）。
- 更新商圈會員停車狀態(tài)（可通過此API同步會員停車到場狀態(tài)給微信支付，對用會員的商場內(nèi)門店消費可100%自動積分）。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 商圈支付結(jié)果通知API接口文檔。
# 3.2.3. 【服務(wù)端】商圈積分同步
步驟說明：商圈服務(wù)商針對微信支付前序推送給商圈系統(tǒng)的顧客商圈內(nèi)交易通知，告知微信支付系統(tǒng)該筆交易的積分情況。
示例代碼:
重要入?yún)⒄f明：
- transaction_id：微信支付推送的商圈內(nèi)交易通知里攜帶的微信訂單號。
- earn_points：用于標明此單是否獲得積分，true為獲得積分，false為未獲得。
- increased_points：顧客此筆交易新增的積分值。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見商圈積分同步接口文檔。
# 4. 常見問題
# Q1：一個商圈擁有多個小程序，是否可以在多個小程序中都嵌入“商圈快速積分插件”？
A：可以。 若一個商圈擁有多個小程序，且在多個小程序場景里都適合引導(dǎo)會員開通【智慧商圈支付即積分】能力，請在提交支付即積分申請時，提交對應(yīng)的多個小程序的AppID，目前最多支持5個。
# Q2：是否必須使用微信支付會員卡能力，才能使用【智慧商圈支付即積分】能力？
A：建議使用微信支付會員卡能力，來提升會員開卡的體驗，但是若未使用微信支付會員卡能力，一樣可以使用【智慧商圈支付即積分】能力。
【智慧商圈支付即積分】能力的實現(xiàn)非常靈活，使用插件形式，嵌入商圈自有小程序中，由商圈自行進行會員身份判斷，若判斷是會員則可進入“商圈快速積分插件”，引導(dǎo)用戶開通【智慧商圈支付即積分】能力。
# Q3：提交積分申請時提示“網(wǎng)絡(luò)錯誤，請稍后重試”
A：該問題可通過商圈自行解決，登錄商圈小程序后臺，更新插件版本。
# Q4：提交積分申請時提示“270924805”
A：該問題可通過商圈自行解決：
- 確認是服務(wù)商模式還是商圈直連模式（登錄商戶平臺確認證書配置）：
- 若是服務(wù)商模式，則需要為服務(wù)商商戶號配置API-V3證書。
- 若是商圈直連模式，則需要為商圈商戶號配置API-V3證書。
- 按照接口文檔進行API證書配置，積分信息回調(diào)接口文檔， API證書配置
# Q5：用戶未自動獲取到積分（商圈未收到回調(diào)信息）
A：該問題可以通過商圈自檢解決。
- 用戶插件頁檢查。
- 用戶通過小程序進入插件頁面，查看是否有交易但未提交。若有，則證明提前未簽到，直接點擊提交即可獲取積分（注：插件頁只能展示當天的場內(nèi)消費信息，通過交易單號可識別是否為當天交易）;若無，則進行商圈可積分門店檢查。
- 若用戶插件頁無交易-商圈可積分門店檢查。
- 該門店未添加進商圈內(nèi)（可能原門店的商戶號變更），自檢方式：使用用戶交易單號在小程序添加該門店，查看是否可添加，并且該門店已開啟“支持積分”（若用戶消費前，該門店未被圈入商圈，則該筆交易訂單不會自動推送，用戶可在商圈圈店后進入插件頁手動推送）。
- 用戶未在門店消費。
