微信支付境外商戶技術文檔(繁體中文版)

一、關於本文件

本文檔是由AApay微信支付服務翻譯的微信支付API的官方手冊中文版。因此,它是為集成微信支付系統的技術架構師,研發工程師,測試工程師和服務工程師編寫的中文教程,其中包括商家的系統,如在線購物平台,收銀系統或自動智能POS系統。原微信支付API的官方手冊為英文版,此中文版僅供參考,如有任何出入,請以英文版爲準。以下主題旨在按順序閱讀,並且引用了“之前看到的”主題和“尚未到來”的主題。這些引用是相應的鏈接,因此在其他主題上提前閱讀通常不是問題。

二、本文檔中使用的條款

1. 付款方法

1)微信付款碼快速支付,即快速支付

付款人在微信的快速付款頁面上顯示他們的條形碼或QR碼,供商家掃描以便直接付款。此模式適用於離線支付方案。

2)微信二維碼付款,即原生付款

賣家根據微信支付協議生成交易QR碼,付款人在其微信中轉到“掃描二維碼”以完成付款。此模式適用於在網站,實體店,媒體廣告或其他方案上進行的付款。

3)微信H5網頁支付,即應用內基於Web的支付(官方賬戶支付)

付款人在他們的微信上打開商家的HTML5頁面,並通過JSAPI界面調用微信支付模塊來支付他們的交易。此模式適用於以下場景:

• 付款人進入賣家的官方賬戶並在交易頁面上完成付款;

• 付款人的朋友在聊天或片刻中共享商家的付款URL,付款人點擊該鏈接以完成付款;

• 付款人掃描商家頁面中顯示的付款QR碼,並在瀏覽器中打開它以完成付款。

4)微信IN-APP付款,即應用內付款

應用程序內支付還指基於移動的支付,其中商家通過使用集成在其基於移動的應用程序中的開放式SDK來支付交易來調用微信支付模塊。

2. 定義

1)微信官方賬號管理平台

微信官方賬號管理平台作為官方賬戶的應用程序輸入和管理平台。使用此平台,商家可以提交其基本信息,業務數據和財務信息,以實現微信支付。

網址:http://mp.weixin.qq.com

2)微信開放平台

微信開放平台是商家應用訪問微信支付開放API的切入點。使用此平台,商家可以申請微信應用內付款。

網址:http://open.weixin.qq.com

3)微信商家平台

微信商家平台作為與微信支付相關的商家功能的功能中心,包括參數設置,支付數據查詢和統計,在線退款,移動優惠券管理和其他功能。

網址:http://pay.weixin.qq.com

4)微信支付系統

微信支付系統是用於API,賬戶系統和微信支付流程的回叫通知系統的後臺服務處理系統的通用術語。

5)商家銷售點終端

賣家銷售點終端是指出納員常用的POS系統,它有助於記錄產品數據,創建訂單,協助付款人的付款並打印交易賬單。當與微信支付集成時,該系統需要開發和測試POS系統。

6)商家後臺系統

商家後臺系統是商家後臺服務處理系統的通用術語,包括商家的網站,結賬系統,採購 – 銷售 – 庫存系統,交付系統和客戶服務系統。

7)掃碼器

掃碼器用於幫助商家的系統快速讀取圖像中的編碼數據。根據圖像編碼的類型,商家可以使用QR碼掃碼器或條形碼掃碼器。在掃碼器類型方面,有紅外掃碼器和激光掃碼器。

8)商家證書

商家證書是微信提供的二進製文件,當商家的系統啟動與微信後臺支付服務器的請求會話時,該證書用作識別商家身份的證書。

9)簽名

商家的後臺和微信支付系統基於相同的密鑰和算法創建相同的簽名,並使用它來驗證彼此的身份。簽名算法由微信創建和提供。常用的簽名模式是MD5,SHA1,SHA256和HMAC。

10)付款密碼

付款人在啟用微信支付時獨立設置付款密碼,用於確認付款和授權交易。此密碼與用於登錄微信的微信密碼不同。

11)OpenID

OpenID用於將用戶的身份共享給官方賬號,並且官方賬號之間不同。商家的後臺在登錄授權,付款通知以及調用查詢訂單API時獲取付款人的OpenID。使用OpenID,系統可以檢查付款相關操作是否由同一付款人完成,並將服務訂閱源和模板消息發送給付款人。

三、付款帳戶

商家可以按照指示在微信官方賬戶管理平台(用於本地快速支付和官方賬戶支付)或微信開放平台(用於應用內支付)中申請支付方式。微信支付人員收到並審核申請後,將為賣家開立相應的支付許可。然後,商家將收到一封電子郵件,其中包含微信支付助手所需的付款指示,如圖3.1所示。

圖3.1應用程序批准的電子郵件模板

圖3.1應用程序批准的電子郵件模板

表3.1顯示了電子郵件參數和API參數之間的關係。

表3.1帳戶參數

Parameters in Email

API Parameter Name

Description

APPID

appid

appid is a unique identity key for each app within the WeChat Official Account Admin Platform or WeChat Open Platform, and is assigned by WeChat after developers apply for it on these platforms. The application approval email also contains this field.

Vendor ID for WeChat Payment

mch_id

Specifies vendor’s receipt ID assigned by WeChat Payment after they have applied for WeChat Payment

API Key

key

This key is created for transaction signatures and is retained in the Vendor’s backend and WeChat payment system, and should not be made available publicly or on the Internet. The Vendor should keep this key secured and avoid disclosing it to others. Vendors may configure the key according to the email instructions.

Appsecret

secret

AppSecret is the API password corresponding to APPID, and is used to obtain a certificate (access_token) for calling API access_token. Using WeChat payment, you should obtain an OpenID via the OAuth2.0 interface and use it within the single interface for Official Account Payment. Developers shall be qualified to get AppSecret in development mode.

四、API規則

1. 協議規則

以下指定商家訪問微信支付時調用API的規則:表4.1 API規則

Transfer Mode

Use HTTPS for secure transactions

Submit Mode

Use POST method

Data Format

Data submitted and returned is in XML format

Char Encoding

Use UTF-8 character encoding

Signature Algorithm

MD5 or HMAC-SHA256

Signature Requirement

Signature-checking is required for requesting and receiving data. For more information, see Section 4.3.1 Signature Algorithm.

Certificate Requirement

A vendor certificate is required for calling the Submit Refund API or Revoke Order API.

Logic Judgment

Determine protocol field, service field and transaction status.

2. 參數規格

1)支付金額

交易的貨幣類型默認為CNY(人民幣)。支付金額中使用的單位為【cent】,必須為整數。但是,下載交易歷史時,單位【yuan】用於交易金額。

對於外國交易,交易金額將使用最小的貨幣單位,但參考值必須是不帶小數的整數。例如,使用貨幣類型“美元”,支付金額中的參考值“1750”將相當於17.50美元。

2)貨幣類型

貨幣類型列表如下:

GBP: 英鎊

HKD: 港幣

USD: 美元

JPY: 日元

CAD: 加元

AUD: 澳元

EUR: 歐元

NZD:新西蘭幣

KRW:韓幣

THB: 泰銖

SGD: 新幣

RUB: 盧布

注意:付款和退款的貨幣類型必須相同。

3)時間協議

中國標準時間(UTC + 08)用於本文件。如果商家不在此時區,則應將當前時間轉換為中國標準時間。例如,如果商家在2014年11月11日當地時間0:00在倫敦,則將於2014年11月11日上午8:00在北京。

4)時間戳

以中國標準時間(UTC + 08)作為標準時區,時間戳計算為自1970/01/01
00:00:00 UTC以來的秒數,並且是在此文檔中存儲時間戳的必需方法。注意:毫秒應舍入為秒(10位)。

5)商家的訂單號

付款的訂單號由商家定義,並且必須是唯一的。我們建議在當前時間結束時添加隨機序列,以便創建唯一的序列號。在再次發起付款時使用原始訂單號以避免重複交易。

但是,無法再次支付已付款,已關閉或已撤銷的訂單(有關詳細信息,請參閱第9節“公共API”)。

6)field body的要求

調用微信支付API時,field “body”需要一些特殊標準:

Scenario

場景

Payment Method

微信支付方式

Input Standard

輸入標準

Example

Remark

備注

PC web site

電腦網站

Native Quick Pay

原生快速支付

Web site title— Product description

網站標題—產品描述

Tencent recharge center—QQ member recharging

騰訊充值中心—QQ會員充值

WeChat browser

微信瀏覽器

Official
Account Payment

微信官方賬號支付

Merchant
name— Product category

商家名稱—產品類別

Dangdang-Books

當當網—圖書

QR code in stores

店内二維碼

Official Account Payment

微信官方賬號支付

Store name— Product category

商店名稱—產品類別

Southern store Super market

南方商店超市

Offline store payment

實體門店付款

QR code in stores

店内二維碼

Native
Quick Pay

原生快速支付

Store
name— Product category

商店名稱—產品類別

Southern
store Super market

南方商店超市

Offline
store payment

實體門店付款

Quick Pay in stores

店内快速支付

Quick Pay

快速支付

Store name— Product category

商店名稱—產品類別

Southern store Super market

南方商店超市

Offline store payment

實體門店付款

Third party mobile browser

第三方手機瀏覽器

H5
Payment

H5支付

Mobile
web site title—Product description

手機網站標題

—產品描述

Tencent
recharge center—QQ member

Recharging

騰訊充值中心—QQ會員充值

Third party APP

第三方APP

In-App Payment

應用内付款

App name— Product description

App名稱—產品描述

Cool Running Recharging

酷跑充值

3. 訪問微信支付API的節點

海外商家有兩種微信支付API接入節點:

部署在東南亞的服務器:https://apihk.mch.weixin.qq.com/

部署在歐洲或美國的服務器:https://apius.mch.weixin.qq.com/

在中國部署的服務器:https://api.mch.weixin.qq.com/

注意:商家應根據其服務器部署區域為微信支付API選擇最佳訪問節點。建議考慮其他接入節點的兼容性。一旦主節點出現問題,系統就會自動切換到其他節點。

4. 安全規範

A. 簽名算法

創建簽名的一般步驟:

步驟1:假設發送和接收的所有數據都是M. Sort按字母順序升序排序M中的非空值(即字典順序),並通過相應的URL鍵值格式將它們連接成字符串A(例如key1=value1&key2=value2…)。

注意:

• 根據ASCII編碼名稱按字母順序升序對參數名稱進行排序(例如,詞典序列);

• 簽名中排除了空參數值;

• 參數名稱區分大小寫;

• 在檢查返回的數據或微信推送通知簽名時,傳輸的簽名參數將被排除在此簽名中,因為它與創建的簽名進行比較。

步驟2:將“key =(API鍵值)添加到stringA的末尾以獲取stringSignTemp,對stringSignTemp執行MD5算術,將所有結果字符轉換為大寫,從而得到符號的值(signValue)。

例如:

對於以下傳輸的參數:

Appid: wxd930ea5d5a258f4f
mch_id: 10000100
device_info: 1000
body: test
nonce_str: ibuaiVcKdpRxkhJA

(1) 根據“key = value”格式按字典順序對參數名稱的ASCII碼進行排序

stringA=”appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA”;

(2) 加入API密鑰

stringSignTemp=”stringA&key=192006250b4c09247ec02edce69f6a2d”
sign=MD5(stringSignTemp).toUpperCase()=”9A0A8659F005D6984697E2CA0A9CF3B7″

獲取下面要傳輸的數據:

<xml>
<appid>
wxd930ea5d5a258f4f</appid>
<mch_id>
10000100</mch_id>
<device_info>
1000<device_info>
<body>
test</body>
<nonce_str>
ibuaiVcKdpRxkhJA</nonce_str>
<sign>
9A0A8659F005D6984697E2CA0A9CF3B7</sign>
<xml>

微信為此API提供在線簽名工具:URL1。

B. 隨機字符串算法

nonce_str包含在微信支付API協議中,以確保簽名的不可預測性。我們建議調用random()函數來創建簽名並將其值轉換為字符串。

c. 商家證書

1)獲得商家證書

與付款回滾相關的API(例如退款或撤銷訂單)需要商家的證書。在商家成功申請微信支付後,通過電子郵件通知向商家頒發證書。如下所示,可能需要四個證書:

表4.2:證書說明

Certificate
Attachment

證書附件

Description

描述

Use
Case

使用案例

Remarks

備註

pkcs12
format (apiclient_cert.p12)

pkcs12格式(apiclient_cert.p12)

Includes
certificate for private key information, in p12(pfx) format and issued by WeChat payment for identity verification

包括私人密鑰信息證書,採用p12(pfx)格式,由微信支付,用於身份驗證

Calling
the Revoke Order API and Submit Refund API

調用Revoke Order API並提交Refund
API

Double-click
to import into a Windows system and enter certificate password as prompted. By default, the certificate password is the vendor’s ID (e.g. 10010000)

雙擊導入Windows系統並根據提示輸入證書密碼。默認情況下,證書密碼是商家的ID(例如10010000)

pem
format for certificate (apiclient_cert.pem)

證書的pem格式(apiclient_cert.pem)

apiclient_cert.p12 certificate files may be imported to create a certificate in pem format. Do not disclose to others.

可以導入apiclient_cert.p12證書文件以創建pem格式的證書。不要向他人透露

pem
format should be used for PHP applications as PHP can’t use the p12 format

pem格式應該用於PHP應用程序,因為PHP不能使用p12格式

You
can also use the “openssl”
command to import the p12-
format certificate as below:
openssl pkcs12 -clcerts –
nokeys -in apiclient_cert.p12 –
out apiclient_cert.pem

您還可以使用“openssl”命令導入p12格式證書,如下所示:openssl
pkcs12 -clcerts – nokeys -in apiclient_cert.p12 – out apiclient_cert.pem

pem
format for certificate secret key (apiclient_key.pem)

證書密鑰的pem格式(apiclient_key.pem)

apiclient_cert.p12 certificate files may be imported to create a certificate in pem format.

可以導入apiclient_cert.p12證書文件以創建pem格式的證書

pem
format should be used for PHP applications as PHP can’t use the p12 format

pem格式應該用於PHP應用程序,因為PHP不能使用p12格式

You
can also use the “openssl”
command to import the p12-
format certificate as below:
openssl pkcs12 -nocerts -in
apiclient_cert.p12 -out
apiclient_key.pem

您還可以使用“openssl”命令導入p12格式證書,如下所示:openssl
pkcs12 -nocerts -in apiclient_cert.p12 -out apiclient_key.pem

CA
certificate
(rootca.pem)

CA證書(rootca.pem)

WeChat
payment API server also deploys server certificates to verify identity for WeChat payment. When vendors call APIs, the authenticity of the server called and domain name shall be verified.

微信支付API服務器還部署服務器證書以驗證微信支付的身份。

當商家調用API時,應驗證所調用的服務器和域名的真實性。

This
file is the root certificate issued by authorities that sign WeChat payment certificates, which can be used to verify the authenticity of WeChat payment server certificates.

該文件是簽署微信支付證書的機關簽發的根證書,可用於驗證微信支付服務器證書的真實性

Root
certificates are built-n to some tools. For tools without root certificates, the ones provided here may be used.

根證書是針對某些工具構建的。對於沒有根證書的工具,可以使用此處提供的工具

2)使用商家證書

apiclient_cert.p12是商家的證書文件,用於除基於PHP的開發之外的所有研發操作。

使用.NET環境的商家應確保其框架版本大於2.0。他們可以在使用之前雙擊以安裝證書“apiclient_cert.p12”。

調用商家的證書和安裝的默認密碼是商家的ID(mch_id)。

基於PHP的開發需要“apiclient_cert.pem”和“apiclient_key.pem”,rootca.pem是CA證書。

微信支付提供的演示。

3)商家證書安全

證書文件不應存儲在Web服務器上的虛擬目錄中。相反,它們應放在具有嚴格訪問控制的目錄中,以避免其他人下載證書。商家的服務器也應該沒有病毒和特洛伊木馬,以避免潛在的證書被盜。

D. 商家的回調API安全性

在許多網絡環境中,HTTP請求都存在DNS欺騙,不需要的彈出窗口以及數據被盜和修改的風險。商家的回調API應使用HTTPS來確保數據傳輸安全性。因此,我們建議所有商家都使用HTTPS進行所有微信支付回調。有關更多信息,請參閱構建指南” 。

5.獲得OpenID

微信官方賬號管理平台:

在關注者和官方賬號之間發送消息後,官方賬號可以獲得關注者的OpenID。在微信ID加密後,每個用戶都有一個唯一的OpenID。用戶的OpenID因官方賬號而異。

官方賬號可以通過以下API獲取用戶的OpenID。有關用戶別名,照片圖片,性別,位置,語言和以下時間的信息,則需要用戶的授權。

網址:http://admin.wechat.com/wiki/index.php?title=User_Profile_via_Web

要將來自不同平台的OpenID用作同一用戶的一個ID,開發人員可以使用以下API:

網址:https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140839

微信開放平台:

移動應用可以使用以下API獲取用戶的OpenID:

網址:https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open1419317851&token=&lang=zh_CN

網站應用可以使用以下API獲取用戶OpenID:

https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open1419316505&token=&lang=zh_CN

五、快速付費編程指南

1.使用案例

步驟1:登錄微信後,付款人在“我” → “錢包”中輸入“快速付款”,如圖5.1;

步驟2:收銀員創建交易訂單,付款人確認銷售點終端上顯示的付款金額;

步驟3:收銀員將付款人顯示的條形碼或QR碼掃描到銷售點終端,並將交易訂單提交給微信支付服務器上的交易系統;

步驟4:在交易系統收到支付請求之後,交易系統確定是否必須驗證付款人的支付密碼。如果不需要付款密碼,則直接付款。否則,提示付款人輸入密碼,如圖5.2所示。如果付款成功,付款人將在微信中看到“成功付款”消息,如圖5.3所示; 如果付款失敗,將顯示付款錯誤頁面。

注意:微信條形碼由18個數字構成,起始值分別為10,11,12,13,14或15。

圖5.1快速支付 圖5.2確認付款 圖5.3成功付款
圖5.1快速支付 圖5.2確認付款 圖5.3成功付款

2.付款驗證碼規則

• 任何總額超過1000元的交易必須驗證付款人的付款密碼;

• 對於低於1000元人民幣的交易,每個微信賬號每天最多允許5次密碼豁免交易,並在達到此限制後要求密碼驗證;

• 要求對任何不受信任或可疑交易進行密碼驗證;

3.參與的商家

用戶可以在支持微信支付的商店和商店中體驗這種付款方式。

便利店:7-Eleven,Guoda36524,Hi-24等

連鎖藥店:LBX藥房,國大藥店,Nepstar藥店等

百貨商店:彩虹等

4.商家流程

根據商家的環境,商家可以通過後臺訪問或物理商店訪問來處理付款。付款方案包括需要密碼驗證的付款和免於密碼驗證的付款。

A. 訪問模式 – 商家的後臺訪問

此模式適用於配備統一後臺的商家。在這種模式下,收銀員首先與商家的後臺通信,後臺將隨後向微信支付系統發送交易請求並從微信支付系統接收結果。

圖5.4商家的後臺訪問過程圖5.4商家的後臺訪問過程

B. 訪問模式 – 物理存儲訪問

圖5.5物理存儲訪問過程

圖5.5物理存儲訪問過程

此模式適用於通過公共網絡與微信支付系統通信的商家。在此模式下,出納員啟動交易請求並直接使用微信支付系統處理返回的結果。但是,商家可以根據他們的要求處理其實體店和後臺之間的其他交易。

C. 密碼豁免付款流程

本節使用商家的後臺訪問模式來說明付款流程,如下面的順序圖所示。

圖5.6免密碼付款順序圖

圖5.6免密碼付款順序圖

免密碼付款步驟:

1) 收銀員在其銷售點終端上創建付款訂單,並向付款人顯示付款金額;

2) 付款人打開微信並在“In Me” → “Wallet”中輸入“快速付款”;

3)收銀員通過掃碼器掃描“快速支付”屏幕上的條形碼;

4)掃碼器讀取代碼數據並將其傳輸到收銀台的銷售點終端;

5)收銀員在收到付款信息後向商家後臺發起付款請求。

6)商家後臺處理實體店銷售點終端發送的支付請求,並為其創建簽名,然後撥打【Submit Quick Pay API 】,向微信支付系統發起支付請求;

7)微信支付系統接收商家的支付請求,在驗證後處理數據,並將支付結果返回給商家後臺。如果交易成功支付,微信支付系統通過短信或微信消息同時將支付結果發送給賣家和付款人;

8)商家後臺驗證簽名以處理相關數據,並將付款結果發送到收銀員的銷售點終端。

9)收銀員在收到成功的付​​款結果後將貨物交付給付款人。

D. 密碼驗證付款流程

密碼驗證付款流程與密碼免稅付款非常相似。前5個步驟完全相同。在密碼驗證支付過程中,在商家後臺叫用【Submit Quick Pay API】後,微信後臺提示付款人輸入支付密碼以發起付款請求。付款人成功驗證其付款密碼後,API立即向商家的後臺返回USERPAYING狀態,商家的後臺與微信支付系統查詢訂單API進行通信,以確認訂單是否已成功付款。

密碼驗證付款流程如以下順序圖所示:

圖5.7密碼驗證付款的流程圖

圖5.7密碼驗證付款的流程圖

這裡我們只顯示與前面描述的步驟不同的步驟。

1)收銀員的銷售點終端在創建訂單後向商家後臺發起付款請求;

2)商家的後臺調用【Submit Quick Pay API 】來創建支付交易;

3)微信支付系統驗證商家的請求,並確定是否需要密碼驗證;

4)微信支付系統返回USERPAYING狀態,商家的後臺向收銀員的銷售點終端發送包含結果的響應;

5)微信支付系統提示付款人在微信上輸入付款密碼;

6)付款人確認付款並輸入付款密碼;

7)付款人在輸入密碼後提交驗證;

8)付款人在微信完成交易後,微信支付後臺返回付款結果,並通過短信和微信消息通知付款人結果;

9)商家的後臺從微信支付系統接收USERPAYING狀態,並通過【Query Order API】查詢實際支付結果(有關詳細信息,請參閱公共API);

10)如果微信支付系統回复支付狀態為USERPAYING,則商家後臺每5秒調用【Query Order API】以確定最終的實際支付狀態。如果付款人取消付款或延遲付款超過30秒,商家後臺將停止輪詢,並調用【Revoke Order API】撤銷交易。

E. 異常處理

請按照以下說明對任何付款例外進行問題排查:

1)如果付款人在微信提示付款錯誤時無法在交易記錄中找到訂單,他們將要求賣家再次發起訂單; 如果訂單成功支付,商家後臺會調用【Query Order API】來再次查詢實際的付款狀態;

2)如果由於餘額不足,卡片無效或其他原因導致付款錯誤,付款人將需要重複付款流程;

3)當交易超時或付款失敗時,商家後臺應調用【Revoke Order API】(有關詳細信息,請參閱公共API)以取消交易;

4)由於銀行系統出現異常錯誤,餘額不足,銀行不受支持或任何其他原因導致商家後臺應向收銀員的銷售點終端發送付款錯誤消息;

5)根據返回的錯誤代碼的類型,可能會取消轉賬。有關詳細信息,請參閱API返回錯誤代碼列表。

5. 提交快速微信支付API

A. 使用案例

收銀員掃描付款人顯示的快速付款頁面上的條形碼或QR碼後,付款參數將轉移到商家的後臺。商家的後臺調用Submit Quick Pay API來啟動付款。

注意:a. 交易結果將同步返回。如果返回“System error”,則應在5秒後調用查詢順序API。一旦返回“USERPAYING”,也需要此API,它應該是持續請求直到付款成功或超時(建議超時時間為30秒,建議請求頻率為10秒一次)。

b. 如果在調用Query Order API時返回不確定的交易狀態,請撤銷該訂單。撤銷後,成功的訂單將被退還,而失敗的訂單將被關閉。如果在調用Revoke Order API時返回失敗,請再次請求。請注意,撤銷訂單API應在創建訂單後至少15秒後調用,並且需要傳遞證書。

B. 網址

https://api.mch.weixin.qq.com/pay/micropay

C. 證書要求

無需證書。

D. 參數設置

Name

ID

Type

類型

Required

必要

Example

Description

描述

Official

Account ID

官方帳號

appid

String(32)

wx8888888888888888

Specifies an Official Account ID assigned by WeChat
微信分配的官方賬號ID

Vendor ID

商家ID

mch_id

String(32)

1900000109

Specifies vendor ID assigned by WeChat Payment
微信支付分配的商家ID

Device ID

設備ID

device_info

String(32)

013467007045764

Specifies a Terminal device ID (such as store number as defined by the vendor)
指定終端設備ID(例如商家定義的商店編號)

Random

string

隨機字符串

nonce_str

String(32)

5K8264ILTKCH16CQ25

02SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random
String Algorithm .
不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法” 。

Signature

簽名

sign

String(32)

C380BEC2BFD727A4B

6845133519F3AD6

Signature. For more information, see Section 4.3.1 Signature Algorithm
簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign type

簽名類型

sign_type

String(32)

HMAC-SHA256 / MD5

Currently support HMAC-SHA256 and MD5, default is
MD5. If you choose HMAC-SHA256, sign_type must be pass
目前支持HMAC-SHA256和MD5,默認為MD5。如果選擇HMAC-SHA256,則必須傳遞sign_type

Item

Description

商品描述

body

String(32)

Pay for QQ Coins

Short description of item(s) to be purchased for the
Payer, Please refer to Section 4.2, item 6
有關付款人購買商品的簡短說明,請參閱 第4.2節第6項

Item Details

項目細節

detail

String(6000)

{
“goods_detail”:[
{
“goods_id”:”iphone6s_16G”,
“wxpay_goods_id”:”1001″,
“goods_name”:”iPhone6s 16G”,
“goods_num”:1,”price”:528800,
“goods_category”:”123456″,
“body”:”苹果手机”
},
{
“goods_id”:”iphone6s_32G”,
“wxpay_goods_id”:”1002″,
“goods_name”:”iPhone6s 32G”,
“quantity”:1,”price”:608800,
“goods_category”:”123789″,
“body”:”苹果手机”
}
]
}

Detailed product list described in JSON format.
Please use CDATA tag to protect the JSON string when generating signature.
goods_detail []:
└goods_id String Required 32
Goods ID
└wxpay_goods_id StringOptional 32 The unified goods ID
defined by WeChat
└goods_name String Required
256 Goods name
└ quantity Int Required Goods
amount
└price Int Required Goods
price, unit as cent
Note: The goods price should be
less than total_fee and it should
be the favorable price.

以JSON格式描述的詳細產品列表。生成簽名時,請使用CDATA標記來保護JSON字符串。

goods_detail [] :
└goods_id串所需32商品編號:
wxpay_goods_id字符串:
可選32微信定義的統一商品ID:
└goods_name串所需
256商品名稱
└數量Int所需商品數量
└價格Int所需商品
價格,單位為分

注意:商品價格應低於total_fee,應該是優惠價格。

Additional Data

其他數據

attach

String(128)

User-Defined Data

Allow vendors an additional field to be returned in
the payment notification after submitting a payment or in the Query Order API
允許商家在提交付款後或在查詢訂單API中在付款通知中返回其他字段

Vendor Order Number

商家訂單號

out_trade_no

String(32)

12177525012014
07033233368018

32 alphanumeric characters or less. For more information, see Section 4.2 Vendor’s Order Number.
不超過32個字母數字字符。有關更多信息,請參見第4.2節“商家的訂單號”。

Bid price

競價

total_fee

Int

888

Specifies the total order amount. The units are expressed in cents as integers. For more details, see Section 4.2 Payment Amount.
指定總訂單金額。單位以美分錶示為整數。有關更多詳細信息,請參見第4.2節“付款金額”。

Currency Type

貨幣類型

fee_type

String(8)

GBP

ISO-4217 standard compliant and be described by three characters based code. For more information, see Section 4.2 Currency Type.
符合ISO-4217標準,可由三個基於字符的代碼描述。有關更多信息,請參見第4.2節“ 貨幣類型”。

Terminal IP

終端IP

spbill_create_ip

String(16)

8.8.8.8

Specifies the machine IP that calls the WeChat Payment API
指定調用微信支付API的機器IP

Item Label

物品標籤

goods_tag

String(32)

Specifies the label of goods, which is a parameter in the coupon feature for businesses. For more information, see Section 10 Mobile coupons.
指定商品標籤,這是商家優惠券功能中的參數。有關更多信息,請參閱第10節移動優惠券。

Authorization Code

授權碼

auth_code

String(128)

12006109882800
9406

Specifies the authorization code by scanning a barcode/QR Code on Quick Pay
Note: The WeChat barcodes are constructed with 18 numbers, with the start value of 10, 11, 12, 13, 14 or 15.

通過掃描快速支付上的條形碼/ QR碼來指定授權代碼
注意:微信條形碼由18個數字構成,起始值為10,11,12, 13,1415

Scenarios Information

場景信息

scene_info

String(256)

{
“store_id”:
“SZT10000”,
“store_name”:”Di
ning Hall of
Tencent
Mansion”
}

Specify the payment scenarios, such as the store or mall information.

指定付款方案,例如商店或商城信息。

{ “
store_id”:””, //Unique ID of store,
Optional, String(32)
“store_name”:””//Store name,
Optional, String(64)
}

示例如:

<xml>
<appid>
wx2421b1c4370ec43b</appid>
<attach>
Additional Order Descriptionr</attach>
<auth_code>
120269300684844649</auth_code>
<body>
Quick Pay Testing</body>
<device_info>
1000</device_info>
<goods_tag></goods_tag>
<mch_id>
10000100</mch_id>
<
nonce_str>8aaee146b1dee7cec9100add9b96cbe2</nonce_str>
<out_trade_no>
1415757673</out_trade_no>
<spbill_create_ip>
14.17.22.52</spbill_create_ip>
<total_fee>
1</total_fee>
<sign>
C29DB7DB1FD4136B84AE35604756362C</sign>
</xml>

注意:參數在XML文件中進行轉義,CDATA標記用於說明XML解析器不會解析數據。

E. 返回數據

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return

Status

Code

返回狀態代碼

return_code

String(16)

SUCCESS

Set to SUCCESS or FAIL
Specifies communicating label but not transaction label. The status of the
transaction is determined by the value of the result_code field.

設置為SUCCESS或FAIL

指定通信標籤但不指定轉賬標籤。轉賬的狀態由result_code字段的值確定。

Return Data

返回數據

return_msg

String(128)

Signature Failure

If not empty, this is the error description. If not empty,
this is the error description
Signature Failure
Parameter format checking error

如果不為空,則為錯誤描述。如果不為空,則為錯誤描述

簽名失敗

參數格式檢查錯誤

當return_code為SUCCESS時,返回數據還將包括以下字段:

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

String(32)

wx8888888888888888

The Official Account ID submitted when calling the
interface

調用界面時提交的官方賬號ID

Vendor ID

商家ID

mch_id

String(32)

1900000109

The vendor ID submitted when calling the interface

調用接口時提交的商家ID

Device ID

設備ID

device_info

沒有

String(32)

013467007045764

The device ID submitted when calling the interface

調用接口時提交的設備ID

Random String

隨機字符串

nonce_str

String(32)

Fsdfds1235df231asd

fg32145gfdse

32 characters or fewer, returned from Wechat payment

從微信支付返回的不超過32個字符

Signature

簽名

sign

String(32)

C380BEC2BFD727A4B

6845133519F3AD6

Signature returned from Wechat payment. For more information, see Section
4.3.1 Signature Algorithm

簽名從微信支付返回。有關更多信息,請參見第4.3.1節“簽名算法”

Service Result

服務結果

result_code

String(16)

SUCCESS

Set to SUCCESS or FAIL

設置為SUCCESS或FAIL

Error Code

錯誤代碼

err_code

沒有

String(32)

SYSTEMERROR

For more information, please refer toSection 5.5.6 Error Codes

有關更多信息,請參見 第5.5.6節“錯誤代碼”

Error Code

Description

錯誤代碼說明

err_code_des

沒有

String(128)

System error

The detailed description of errorreturned

返回錯誤的詳細描述

當return_code和result_code都是SUCCESS時,返回數據還將包括以下字段:

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

User Tag

用戶標籤

openid

String(128)

oUpF8uMuAJO_M2px

b1Q9zNjWeS6o

The only identification under the current appid

當前appid下的唯一標識

Follows Official Account or not

是否關注官方賬號

is_subscribe

String(1)

Y

For users who pay for transactions related to an official account, the value in this field states whether the user is current following the official account
Y: Follows
N: Doesn’t follow

對於支付與官方賬號相關的交易的用戶,此字段中的值表明用戶是否是當前跟隨官方賬號的用戶

Y:關注

N:未關注

Transaction Type

交易類型

trade_type

String(16)

MICROPAY

The transaction type is MICROPAY(quick pay)

交易類型是MICROPAY(快速支付)

Payment Bank

付款銀行

bank_type

String (32)

CMC

Strings states bank type

字符串表示銀行類型

Currency Type

貨幣類型

fee_type

String (8)

GBP

Complies with ISO 4217 standards and uses 3

characters based code. For more information,

see Section 4.2 Currency Type

符合ISO
4217標準,使用3個字符的代碼。有關更多信息,請參見第4.2節“貨幣類型”。

Total Amount

總金額

total_fee

Int

100

Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Section 4.2. Payment Amount.

指定轉賬的總金額。單位為分,值必須為整數。有關更多信息,請參見第4.2節。

支付金額。

Cash Type

現金類型

cash_fee_type

String (8)

CNY

Payer’s currency type. Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Section 4.2 Currency Type.

付款人的貨幣類型。符合ISO
4217標準,默認使用CNY(人民幣)。有關更多信息,請參見第4.2節“貨幣類型”。

Cash Payment Amount

現金支付金額

cash_fee

Int

100

Specifies the total cash payment amount of a transaction. For more information, see Section 4.2 Payment Amount.

指定交易的現金支付總額。有關更多信息,請參見第4.2節“付款金額”。

WeChat Payment Order Number

微信支付訂單號

transaction_id

String (32)

1217752501201407

033233368018

The WeChat payment order id

微信支付訂單ID

Vendor Order Number

商家訂單號

out_trade_no

String (32)

1217752501201407

033233368018

Specifies the order number created within the Vendors’ system, which is consistent with request.

指定在商家系統中創建的訂單號,該訂單號與請求一致。

Vendor’s

Data

Package

商家的數據包

attach

沒有

String(128)

123456

Specifies vendor’s data package, which is returned as it is.

指定商家的數據包,按原樣返回。

Payment

End Time

付款結束時間

time_end

String(14)

20141030133525

Specifies transaction creation time in the format of yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10. For more information, see Section 4.2 Time Protocol.

以yyyyMMddHHmmss格式指定轉賬創建時間,例如2009年12月25日09:10:10的20091225091010。

有關更多信息,請參見第4.2節“時間協議”。

Exchange

Rate

匯率

rate

String(16)

650000000

The value is 10 to the 8th power times of the

exchange rate from foreign currency to RMB.

For example, the exchange rate from foreign

currency to RMB is 6.5, the value will be

650000000

該值是從外幣到人民幣的匯率的10的8次冪。例如,從外幣到人民幣的匯率為6.5,值將為650000000

示例如:

<xml>
<return_code>
<![CDATA[SUCCESS]]></return_code>
<return_msg>
<![CDATA[OK]]></return_msg>
<appid>
<![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id>
<![CDATA[10000100]]></mch_id>
<device_info>
<![CDATA[1000]]></device_info>
<nonce_str>
<![CDATA[GOp3TRyMXzbMlkun]]></nonce_str>
<sign>
<![CDATA[D6C76CB785F07992CDE05494BB7DF7FD]]></sign>
<result_code>
<![CDATA[SUCCESS]]></result_code>
<openid>
<![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<is_subscribe>
<![CDATA[Y]]></is_subscribe>
<trade_type>
<![CDATA[MICROPAY]]></trade_type>
<bank_type>
<![CDATA[CCB_DEBIT]]></bank_type>
<total_fee>
1</total_fee>
<coupon_fee>
0</coupon_fee>
<fee_type>
<![CDATA[CNY]]></fee_type>
<transaction_id>
<![CDATA[1008450740201411110005820873]]></transaction_id>
<out_trade_no>
<![CDATA[1415757673]]></out_trade_no>
<attach>
<![CDATA[Additional Order Description]]></attach>
<time_end
><![CDATA[20141111170043]]></time_end>
</xml>

F. 錯誤代碼

Name

描述

Description

支付狀態

Payment Status

原因

Reason

Solution

SYSTEMERROR

API返回錯誤

API return error

Unknown

系統超時

System timed out

立即調用查詢訂單API以檢查當前狀態,並使用返回的狀態來決定處理訂單的後續步驟。

Call the Query Order API immediately to check the
current status, and use the returned status to decide the next steps for
processing the order.

PARAM_ERROR

參數錯誤

Parameter error

Failure

請求的參數不正確

Requested parameters are not correct

根據API返回的數據調試程序

Debug your program based on data returned by the API

ORDERPAID

訂單已付清

Order is paid

Failure

重複的訂單號

Duplicate order number

確認此訂單是否已處理完畢。如果沒有,請將其作為新訂單提交。

Confirm whether this order has already been processed.
If not, submit it as a new order.

NOAUTH

沒有商家的權限

No permissions for vendors

Failure

商家尚未啟用快速付款

Vendors hasn’t enabled Quick Pay

申請並獲得使用快速付款的權限。如需申請此付款方式,請聯繫客戶服務。

Apply and receive permission to use Quick Pay first.
For applying for this payment method, contact customer service.

AUTHCODEEXPIRE

QR碼已過期。刷新然後再試一次。

QR Code expired. Refresh and try again.

Failure

付款人的條形碼已過期

Payer’s bar code has expired

收銀員應要求付款人刷新微信上的條形碼/二維碼並再次掃描碼。此錯誤直接顯示給收銀員。

Cashier should ask payer to refresh the bar code/QR
code on WeChat and scan the code again. This error is displayed directly to
the cashier.

NOTENOUGH

餘額不足

Insufficient balance

Failure

付款人的付款帳戶餘額不足

Payer has insufficient balance in their payment
account

收銀員應通知付款人更改其付款銀行卡並再次掃描。

注意:在這種情況下,收銀員的銷售點終端應收到來自商家後臺的消息“此卡中的餘額不足。請嘗試另一個”。

Cashiers should inform the payer to change their
payment bank card and scan it again. Note: In this scenario, the Cashier’s
point of sale terminal should receive a message saying “Insufficient
balance in this card. Try another one” from the Vendor’s backend.

NOTSUPORTCARD

不支持的卡類型

Unsupported card type

Failure

付款人用於付款的卡類型目前不支持

The type of card used by the payer for their payment
is not supported at the moment

付款人將在微信中收到一條消息,告訴他們選擇另一種卡類型

注意:在這種情況下,收銀員的銷售點終端應該收到一條來自商家後臺消息“不支持的卡類型。請嘗試另一個卡或鏈接新卡進行付款”。

Payer will receive a message in WeChat telling them
to select another card type

Note: In this scenario, the
cashier’s point of sale terminal should receive a message saying
“Unsupported card type. Try another one or link a new card for payment” from the vendor’s
backend.

ORDERCLOSED

訂單已結束

Order is closed

Failure

訂單已關閉

The order is closed

此轉賬發生異常。創建新訂單並重做付款流程。

An exception has occurred with this transaction.
Create a new order and redo the payment process.

ORDERREVERSED

訂單被取消

Order is cancelled

Failure

訂單已取消

The order is cancelled

當前訂單已取消。創建新訂單並重做付款流程。

The current order is cancelled. Create a new order
and redo the payment process.

BANKERROR

銀行系統例外

Bank system exceptions

Unknown

銀行系統超時

立即調用Query
Order API並檢查當前的轉賬狀態。根據此狀態處理後續步驟。

Bank system timed out

Call the Query Order API immediately and check the
current transaction status. Process the next steps based on this status.

USERPAYING

付款人正在執行付款時需要密碼

Password is required as payers are performing their
payment

Unknown

此交易需要付款密碼

等待5秒鐘,然後再次調用Query
Order API以檢查當前的轉賬狀態。根據此狀態處理後續步驟。

This transaction requires payment password

Wait for 5 seconds and then call the Query Order API
again to check current transaction status. Process the next steps based on
this status.

AUTH_CODE_ERROR

授權參數錯誤

Authorization parameter error

Failure

請求的參數不正確

每個QR碼只能使用一次。付款人應刷新二維碼,然後重試。

Requested parameters are not correct

Each QR code can only be used once. Payer should
refresh the QR code and try again.

AUTH_CODE_INVALID

授權代碼檢查錯誤

Authorization code checking error

Failure

收銀員掃描的條形碼或QR碼不是快速支付頁面上的條形碼或QR碼

快速支付頁面上的掃描條或QR碼

The bar or QR code scanned by cashiers is not the
one on the Quick Pay page

Scan bar or QR code on the Quick Pay page

XML_FORMAT_ERROR

XML格式無效

Invalid XML format

Failure

XML格式無效

檢查XML參數是否格式正確

Invalid XML format

Check whether XML parameters are in the correct
format

REQUIRE_POST

_METHOD

使用post方法

Use post method

Failure

數據不通過POST方法傳輸

檢查數據是否通過POST方法提交

Data not transferred via POST method

Check whether data is submitted via POST method

SIGN ERROR

簽名錯誤

Signature error

Failure

簽名結果不正確

檢查簽名參數和方法是否符合簽名算法要求

Incorrect signature result

Check whether the signature parameter and method
comply with signature algorithm requirements

LACK_PARAMS

缺少參數

Failure

缺少必需參數

檢查所有必需參數是否完整

Missing parameter

Required parameter is missing

Check whether all required parameters are complete

NOT_UTF8

編碼格式無效

Failure

不使用指定的編碼格式

使用NOT_UTF8編碼格式

Invalid coding format

Specified coding format is not used

Use NOT_UTF8 encoding format

BUYER_MISMATCH

付款帳戶不正確

Failure

只允許一個付款人為一筆交易付款。

檢查付款人是否是同一個人

Incorrect payment account

Only one payer is allowed to pay for one
transaction.

Check whether the payer is the same person

APPID_NOT_EXIST

APPID不存在

Failure

此參數中沒有APPID

檢查提供的APPID是否正確

APPID does not exist

No APPID in this parameter

Check whether provided APPID is correct

MCHID_NOT_EXIST

MCHID不存在

Failure

此參數中沒有MCHID

檢查提供的MCHID是否正確

MCHID does not exist

No MCHID in this parameter

Check whether provided MCHID is correct

OUT_TRADE_NO_USED

商家訂單號重複

Failure

同一交易無法重複提交

檢查商家的訂單號是否已經提交或先前使用過

Duplicate vendor order number

The same transaction can’t be submitted repeatedly

Check whether the Vendor’s order number has already
been submitted or used previously

APPID_MCHID_NOT_MATCH

appid與mch_id不匹配

Failure

appid與mch_id不匹配

檢查appid是否屬於關聯的mch_id

appid does not match mch_id

appid does not match mch_id

Check whether appid belongs to the associated mch_id

6.查詢訂單API

有關更多信息,請參閱【9.2查詢順序】。

7.提交退款API

有關詳細信息,請參閱【9.4節提交退款】。

8.查詢退款API

有關更多信息,請參閱【9.5節查詢退款】。

9.撤銷訂單API

A. 使用案例

如果未成功退回支付交易或支付系統超時,則會調用此API以取消交易。撤銷後,成功的訂單將被退還,而失敗的訂單將被關閉。

注意:可以調用此API以在創建訂單後的7天內取消交易,而提交退款API應用於成功支付的交易。儅轉賬提交後,需要調用【查詢訂單API 】。當沒有明確的查詢結果時,需要調用【撤銷訂單API】。

注意:請注意,撤銷訂單API應在創建訂單後至少15秒後調用。

B. 網址

https://api.mch.weixin.qq.com/secapi/pay/reverse

C. 證書要求

此API需要雙向證書。有關更多信息,請參見第4.3.3節“ 商家證書”。

D. 請求參數

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

官方帳號

Official Account ID

appid

String(32)

wx888888888888

8888

指定微信指定的官方帳號

Specifies Official Account ID assigned by WeChat

商家ID

Vendor ID

mch_id

String(32)

1900000109

指定微信支付分配的商家ID

Specifies vendor ID assigned by WeChat Payment

微信訂單號

WeChat Order Number

transaction_id

String(32)

12177525012014

07033233368018

微信訂單號是首選

WeChat order number is preferred

商家訂單號

Vendor Order Number

out_trade_no

String(32)

12177525012014

07033233368018

out_trade_no是商家系統內的內部訂單號。

如果商家提供了transaction_id,則它們將在out_trade_no上使用。

out_trade_no is an internal order number within the Vendor’s system. transaction_id will be used over out_trade_no if they are both provided by the vendor.

隨機字符串

Random String

nonce_str

String(32)

5K8264ILTKCH16

CQ2502SI8ZNMT

M67VS

不超過32個字符或更少。有關更多信息,請參見 第4.3.2節“隨機字符串算法”

32 characters or fewer or fewer. For more information, see Section 4.3.2 Random String Algorithm

簽名

Signature

sign

String(32)

C380BEC2BFD727

A4B6845133519F

3AD6

有關更多信息,請參見第4.3.1節“簽名算法”。

For more information, see Section 4.3.1 Signature Algorithm.

簽名類型

Sign type

sign_type

String(32)

HMACSHA256/MD5

目前支持HMAC-SHA256和MD5,默認為MD5。如果選擇HMAC-SHA256,則必須提交此參數

Currently HMAC-SHA256 and MD5 are supported, default is MD5. This parameter must be submitted if HMAC-SHA256 is chosen

示例如:

<xml>
<appid>
wx2421b1c4370ec43b</appid>
<mch_id>
10000100</mch_id>
<nonce_str>
b7ffb16a7150cf08639db472c5f5bdae</nonce_str>
<out_trade_no>
1415717424</out_trade_no>
<sign>
9B2EA16C05A5CEF8E53B14D53932D012</sign>
</xml>

E. 返回數據

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

返回狀態代碼

Return Status Code

return_code

String (16)

SUCCESS

成功或失敗。指定通信標籤但不指定轉賬標籤。轉賬的狀態由result_code字段的值確定

SUCCESS or FAIL. Specifies communicating label but not transaction label. The status of the transaction is determined by the value of the result_code field

返回數據

Return Data

return_msg

沒有

String(128)

Signature Failure

如果不為空,則返回的信息是錯誤描述

簽名失敗

參數格式檢查錯誤

If not empty, the returned info is the error description
Signature Failure
Parameter format checking error

如果return_code是SUCCESS,則返回數據還將包括以下字段:

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

String(32)

wx88888888

88888888

The Official Account ID submitted when calling the interface

調用界面時提交的官方賬號ID

Vendor ID

商家ID

mch_id

String(32)

1900000109

The vendor ID submitted when calling the interface

調用接口時提交的商家ID

Random String

隨機字符串

nonce_str

String(32)

5K8264ILTK

CH16CQ250

2SI8ZNMTM67VS

32 characters or fewer

不超過32個字符

Signature

簽名

sign

String(32)

C380BEC2BFD

727A4B684513

3519F3AD6

For more information, see Section 4.3.1 Signature

有關更多信息,請參見第4.3.1節“簽名”

Service Result

服務結果

result_code

String(16)

SUCCESS

SUCCESS or FAIL SUCCESS indicates the order was paid for successfully and cannot be paid for again. If the payment is completed, a refund is initiated. FAIL refers to exceptions that occur in the interface.
The recall function should be used to determine whether the order has been canceled or not;

成功或失敗

SUCCESS表示訂單已成功付款且無法再次付款。如果付款完成,則會啟動退款。

FAIL是指接口中發生的異常。召回功能應用於確定訂單是否已被取消;

Error Code

錯誤代碼

err_code

沒有

String(32)

SYSTEMERROR

For more information, please refer to Section 5.9.5 Error Code

有關更多信息,請參見 第5.9.5節“錯誤代碼”

Error Code Description

錯誤代碼說明

err_code_des

沒有

String(128)

System error

The detailed description of error returned.

返回錯誤的詳細描述。

Recall Requirement

召回要求

recall

String(1)

Y

Specifies whether recalling the Cancel Order API is required or not, Y means yes while N means no.

指定是否需要調用取消訂單API,Y表示是,而N表示否。

Exchange Rate

匯率

rate

String(16)

650000000

The value is 10 to the 8th power times of the
exchange rate from foreign currency to RMB. For example, the exchange rate from foreign currency to RMB is 6.5, the value will be 650000000

該值是從外幣到人民幣的匯率的10的8 次冪。例如,從外幣到人民幣的匯率為6.5,值將為650000000

例如:

<xml>
<
return_code><![CDATA[SUCCESS]]></return_code>
<
return_msg><![CDATA[OK]]></return_msg>
<
appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<
mch_id><![CDATA[10000100]]></mch_id>
<
nonce_str><![CDATA[o5bAKF3o2ypC8hwa]]></nonce_str>
<
sign><![CDATA[6F5080EDDD196FFCDE53F786BBB93899]]></sign>
<
result_code><![CDATA[SUCCESS]]></result_code>
<
recall><![CDATA[N]]></recall>
<
/xml>

F. 錯誤代碼

Name

描述

Description

原因

Reason

Solution

系統錯誤

SYSTEMERROR

API返回錯誤

API return error

系統超時

System timed out

立即調用查詢訂單API以檢查當前狀態,並使用返回的狀態來決定處理訂單的後續步驟

Call the Query Order API immediately to check the current status, and use the returned status to decide the next steps for processing the order

INVALID_TRANSACTIONID

無效的transaction_id

Invalid transaction_id

請求的參數不正確

Requested parameters are not correct

參數錯誤。再次檢查transaction_id。

Parameter error. Check transaction_id again.

PARAM_ERROR

參數錯誤

Parameter error

請求的參數不正確

Requested parameters are not correct

參數錯誤。再次檢查參數。

Parameter error. Check parameters again.

REQUIRE_POST_METHOD

使用POST方法

Use POST method

POST方法不傳輸數據

Data is not transferred by POST method

檢查數據是否通過POST方法提交

Check whether data is submitted via POST method

SIGNERROR

簽名錯誤

Signature error

簽名結果不正確

Incorrect signature result

檢查簽名參數和方法是否符合簽名算法要求

Check whether signature parameter and method comply with signature algorithm requirements

10.下載調節文件API

有關詳細信息,請參閱【9.6節下載對帳文件】

11.報告速度測試

為了改善我們的支付服務,我們建議商家通過報告速度測試API向微信支付後臺報告支付接口延遲。有關更多信息,請參閱【9.8報告速度測試API】。

六、本地快速支付計劃指南

1.使用案例

付款人在以下過程中掃描商家顯示的QR碼。

步驟1 :商家根據微信支付規則相應地為其產品創建QR碼,如圖6.1所示。

步驟2 :付款人用他們的微信掃描QR碼以訪問商家的產品數據並繼續進行交易,如圖6.2所示。付款人然後按照指示付款,如圖6.3所示。

圖6.1支付QR碼

圖6.1支付QR碼

圖6.2在微信上掃描二維碼

圖6.3確認付款

第3步:付款人確認他們的交易並輸入他們的付款密碼,如圖6.4所示。

第4步:付款人在完成付款後會收到成功付款的提示,如圖6.5所示。賣家在收到有關成功付款的通知後,將付款產品交付給付款人。

圖6.4:輸入付款密碼 圖6.5成功後的提示付款

圖6.4:輸入付款密碼

圖6.5成功後的提示付款

2.參與的商家

用戶可以在支持微信支付的商店和商店中體驗這種付款方式。

離線:Shopin實體店

在線:京東,攜程等

3.商家流程

A. 啟用付款授權

在微信官方賬戶管理平台的左側導航欄中,選擇“WeChat Payment(微信支付)”→“Developer Settings (開發配置)” ,單擊 “Edit (修改)”, 如圖6.6所示。

圖6.6本地支付的參數設置

圖6.6本地支付的參數設置

選中複選框“Native Payment (Native 原生支付)”下的官方賬號付款,並在輸入商家的支付後臺URL“Payment Callback URL (支付回调URL)”字段。

圖6.7本機支付的授權設置和支付回調URL圖6.7本機支付的授權設置和支付回調URL

B. 選擇一個必要的模式

快速支付有兩種模式供商家選擇。

模式1:商家的後臺根據包含固定參數“productid”(指定產品標籤或訂單號)的微信支付規則URL創建QR碼。在付款人掃描QR碼後,微信支付系統將產品和OpenID(付款人的身份)發送給商家後臺。商家後臺根據productid發起交易。微信支付系統啟動付款人微信的支付流程。

模式2:商家的後臺調用微信支付系統【Unified Order API】以生成預付款交易,並根據API返回的URL創建QR碼。付款人輸入密碼以完成交易。

注意:預付款交易有效期為2小時,一旦到期,則無法支付。

4.模式1

在繼續此模式之前,商家需要在微信官方賬號管理平台上設置其付款回調URL。在付款人掃描QR碼後,此URL用於通過微信支付系統的回調接收productid和付款人的OpenID。有關更多信息,請參見第6.3.1節“啟用付款授權”。

A. 序列圖

圖6.8模式1的本地微信支付API

圖6.8模式1的本地微信支付API

服務步驟:

1)商家的後臺根據微信支付規則指定的格式創建QR碼(有關詳細信息,請參閱第6.4.2節QR碼生成規則)並將其顯示給要掃描的付款人。

2)付款人在微信中打開“掃描二維碼”掃描二維碼。掃描的數據從付款人的微信發送到微信支付系統。

3)微信支付系統收到付款方微信的請求後,會在商家的後臺調用支付回調網址,其中包含productid和用戶的OpenID。在付款人可以付款之前,賣家的系統需要返回prepay_id(【Unified Order API】返回交易會話標籤有效期最長為2小時)。

4)商家的後臺接收來自微信支付系統的回叫請求,並根據productid在商家的後臺創建訂單。

5)商家的後臺調用微信支付系統【Unified Order API】並請求交易會話標籤。

6)微信支付系統根據上述請求創建預付款交易,並返回交易會話代碼prepay_id。

7)商家的後臺接收轉賬會話標記prepay_id。

8)商家的後臺將prepay_id返回給微信支付系統。

9)微信支付系統根據prepay_id在Payer的微信上啟動付款授權。

10)付款人輸入付款密碼並確認微信付款。支付授權從微信提交到微信支付系統。

11)微信支付系統驗證並扣除以完成交易。

12)微信支付系統通過短信將交易結果返回給付款人的微信,並在付款完成後提示。付款人可以在微信中查看付款結果。

13)微信支付系統發送異步消息以通知商家後臺交易結果。商家後臺回复微信支付系統,表示付款已完成。

14)如果沒有收到付款消息,商家後臺將輪詢【Query Order API】。

15)賣家確認訂單並將產品交付給付款人。

B. QR碼生成規則

QR碼的內容是以下格式的URL:

weixin://wxpay/bizpayurl?sign=XXXXX&appid=XXXXX&mch_id=XXXXX&product_id=XXXXXX&timestamp=XXXXXX&nonce_str=XXXXX

其中XXXXX是商家的必填字段。商家應根據這些規則創建QR碼。如果要正確顯示QR碼,則需要此格式。商家可以調用第三個插件來創建QR代碼。以下是參數規範。

表6.1生成QR碼的參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx888888888888 8888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat Payment

微信支付分配的商家ID

Timestamp

時間戳

time_stamp

Yes

String(10)

1414488825

Specifies the current system time. For more information, see Time Protocol in Section 4.2 Parameter Specifications.

指定當前系統時間。有關更多信息,請參見第4.2節“參數規範 ”中的時間協議。

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16 CQ2502SI8ZNMT M67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Product ID

產品編號

product_id

Yes

String(32)

88888

Specifies product ID or order ID defined by the Vendor

指定商家定義的產品ID或訂單ID

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD72 7A4B6845133519 F3AD6

Specifies a signature. For more information, see Section 4.3.1 Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

示例如:

weixin://wxpay/bizpayurl?appid=wx2421b1c4370ec43b&mch_id=10000100&nonce_str=f6808210402125e30663234f94c87a8c&product_id=1&timestamp=1415949957&sign=512F68131DD251DA4A45DA79CC7EFE9D

C. 付款回調網址

商家應提供付款回調URL(有關更多信息,請參見第6.3.1節“啟用付款授權”)。在付款人掃描QR碼後,該URL用於接收微信支付系統發送的數據。然後,商家的後臺根據數據創建付款訂單,並且調用【Unified Order API】來提交支付交易。

1)輸入參數

表6.2輸入參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx888888888888 8888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

User Tag

用戶標簽

openid

Yes

String(128)

o8GeHuLAsgefS_80e xEr1cTqekUs

Specifies
the user id of the Payer provided by the WeChat system in OpenID format and
is a unique tag unique to each appid instance

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies
vendor ID assigned by WeChat Payment

微信支付分配的商家ID

Follows Official Account or not

是否關注官方賬號

is_subscribe

Yes

String(1)

Y

Specifies whether the Payer follows the
associated official account or not, with Y meaning ‘follows’ and N meaning
’not follows’.

指定付款人是否遵循相關的官方賬號,Y表示”關注”,N表示”未關注”

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16 CQ2502SI8ZNMT M67VS

32 characters or fewer. For more
information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Product ID

產品編號

product_id

Yes

String(32)

88888

Specifies product ID or order ID defined by
the Vendor

指定商家定義的產品ID或訂單ID

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD72 7A4B6845133519 F3AD6

Specifies a signature. For more information,
see Section 4.3.1 Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

2)輸出參數

表6.3輸出參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return Status Code

返回狀態代碼

return_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL. Specifies communicating
label but not transaction label. The status of the transaction is determined
by the value of the result_code field

成功或失敗。指定通信標籤但不指定轉賬標籤。轉賬的狀態由result_code字段的值確定

Return Data

返回數據

return_msg

No

String(128)

Signature failure

If not empty, this is the error description

Signature failure

Parameter format checking error

如果不為空,則為錯誤描述

簽名失敗

參數格式檢查錯誤

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by
WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat
Payment

微信支付分配的商家ID

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16 CQ2502SI8ZNMT M67VS

32 characters or fewer. For more
information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Advance Transaction ID

預付交易ID

prepay_id

Yes

String(64)

wx2014102720093955 22657a690389285100

Specifies the advance transaction ID created
by calling the Unified Order API.

指定通過調用Unified
Order API創建的高級轉賬ID。

Service Result

服務結果

result_code

Yes

String(16)

SUCCESS

Set to SUCCESS or FAIL

設置為SUCCESS或FAIL

Error Description

錯誤說明

err_code_des

No

String(128)

When result_code is FAIL, the Vendor should
display the error information to the Payer

當result_code為FAIL時,商家應將錯誤信息顯示給付款人

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD72 7A4B6845133519 F3AD6

Specifies a signature. For more information,
see Section 4.3.1 Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

5.模式2

與模式1相比,模式2是一個更簡單的過程。它不需要使用回調支付URL。在模式2中,商家的後臺調用統一訂單API,微信支付系統將code_url返回到商家的後臺以創建QR碼。付款人掃描微信中的QR碼以開始付款。

注意:code_url最長有效期為2小時。在過期後,付款人無法掃描QR碼再次付款。

A. 序列圖

圖6.9模式2的本地微信支付API

圖6.9模式2的本地微信支付API

服務步驟:

1)商家的後臺根據付款人選擇的產品創建訂單。

2)付款人確認付款並且賣家請求微信支付系統【Unified Order API】以創建預付款交易。

3)微信支付系統在收到此請求後創建預付交易賬單,並返回code_url。

4)商家的後臺根據code_url創建QR碼。

5)付款人在微信中打開“掃描二維碼”並掃描二維碼。掃描的數據從付款人的微信發送到微信支付系統。

6)微信支付系統接收微信的請求並驗證URL。如果驗證網址有效,則會啟動付款並需要付款人的授權。

7)付款人輸入付款密碼並在微信中確認付款。付款授權書由微信提交給微信支付系統。

8)微信支付系統根據付款人的授權完成交易。

9)微信支付系統在付款完成後通過短信將交易結果返回給付款人的微信。付款人可以在他們的微信中查看付款結果。

10)微信支付系統發送異步消息以通知商家後臺的支付結果。然後商家的後臺回复通知微信支付系統付款完成。

11)如果沒有收到付款消息,則商家的後臺輪詢【Query Order API】。

12)賣家確認訂單並將產品交付給付款人。

B. QR碼生成規則

網址應遵循weixin://wxpay/bizpayurl?sr=XXXXX的格式。商家可以使用第三個插件從code_url創建QR碼。如果打印在結賬單上,則此QR碼更易讀,因為URL更短。

以weixin://wxpay/s/An4baqw創建的QR碼為例。我們可以在圖6.10中看到更清晰的模式。

圖6.10使用模式2的本地微信支付API中的QR代碼示例

圖6.10使用模式2的本地微信支付API中的QR代碼示例

6.統一訂單API

交易類型(trade_type)字段需要NATIVE。更多信息,請參見【9.1節統一訂單】。

7.查詢訂單API

有關更多信息,請參閱【9.2查詢順序】。

8.關閉訂單API

有關更多信息,請參閱【9.3節關閉順序】。

9.提交退款API

有關詳細信息,請參閱【9.4節提交退款】。

10.查詢退款API

有關更多信息,請參閱【9.5節查詢退款】。

11.下載調節文件API

有關詳細信息,請參閱【9.6節下載對帳文件】

12.報告速度測試

為了改善我們的支付服務,我們建議商家通過報告速度測試API向微信支付後臺報告支付接口延遲。有關詳細信息,請參閱【9.8速度測試API報告】。

13.了解有關QR碼的更多信息

相關鏈接:

http://www.thonky.com/qr-code-tutorial/

http://coolshell.cn/articles/10590.html

七、官方賬戶支付

1. 案例

付款人通過點擊消息或掃描相關的二維碼在微信中打開商家的HTML5頁面,並輸入微信支付以完成交易。

步驟1:商家向付款人發送富媒體消息或自定義菜單,如圖7.1所示。

步驟2:付款人單擊消息或選擇菜單選項以進入商家頁面並選擇產品。

圖7.1商家的Rich Media消息和自定義菜單 圖7.2商家的產品頁面

圖7.1商家的Rich Media消息和自定義菜單

圖7.2商家的產品頁面

步驟3:付款人撥打微信支付並按提示輸入付款密碼,如圖7.3所示。

步驟4:驗證密碼成功後付款完成。商家的後臺收到付款結果通知,如圖7.4所示。

圖7.3:輸入付款密碼 圖7.4成功後的提示付款

圖7.3:輸入付款密碼

圖7.4成功後的提示付款

步驟5:商家返回顯示付款成功的頁面。此頁面由商家設計,如圖7.5所示。

步驟6:商家的官方賬戶發送消息通知微信中的付款人,如圖7.6所示。此步驟是可選的。

圖7.5返回商家頁面 圖7.6通知付款人

圖7.5返回商家頁面

圖7.6通知付款人

注意:商家可以將其產品URL轉換為QR碼,以便付款人可以掃描它們以便快速購買和支付。

詳細步驟如下:

在設計產品頁面之前,請仔細閱讀以下說明:

(1)付款人打開商家的產品頁面並確認交易。該API是通過JavaScript調用頁面上發起微信支付請求。這啟動了付款人的付款流程。

(2)在付款人點擊成功支付並完成交易後,商家的前端會收到JavaScript中返回的值。然後,商家可以直接重定向到指示成功付款的靜態頁面。

(3)商家後臺收到微信開放平台的回調請求,表示報告交易成功支付的結果。

注意:步驟(2)和(3)的觸發時間不嚴格按順序排列。JSAPI的返回值是應該觸發商家頁面重定向的事件。但是,只有在收到微信支付系統的成功付款電話後,商家後臺才能處理付款結果數據。

2.參與的商家

用戶可以在支持微信支付的商店和商店中體驗這種付款方式。

離線:新版Ubox自動售貨機等

在線:京東,義訊官方賬號等

3.編程說明

A. 設置測試目錄

您可以在微信官方賬號管理平台上配置測試目錄,如圖7.7所示。在“付款測試”部分中,您可以在“測試目錄(測試目錄)”字段中配置測試目錄,並將測試人員的微信ID添加到白名單中。確保測試目錄匹配啟動付款的目錄,否則以後不能執行付款。此外,該支付URL應發送到相應的官方賬號會話,以便正確開始支付測試。

圖7.7官方賬號付款設置

圖7.7官方賬號付款設置

B. 設置正式付款目錄

您可以在配置後編輯上述設置,如圖7.8所示。您可以通過選中復選框並設置付款授權目錄來啟用JSAPI。確保目錄與啟動付款的目錄匹配,因為無法從子目錄啟動付款。

圖7.8正式帳戶支付授權目錄設置圖7.8正式帳戶支付授權目錄設置

4. 序列圖

圖7.9官方賬戶微信支付順序圖

圖7.9官方賬戶支付順序圖

商家的系統如何與微信支付系統交互:

1)商家的服務器調用Unified Order API來創建訂單。有關更多信息,請參閱【第9.1節統一訂單】。

2)商家的服務器接收付款通知。有關詳細信息,請參閱【第9.7節一般付款結果通知】。

3)商家的服務器查詢付款結果。有關更多信息,請參閱【9.2查詢順序】。

5.微信版本要求

微信支持5.0及更高版本的支付功能,因此使用5.0之前版本的付款人無法訪問微信支付。因此,我們建議商家在使用微信支付功能之前通過用戶代理字符串確認付款人的版本。以iPhone WeChat客戶端為例,商家可以通過以下用戶代理查看付款人的微信版本:

“Mozilla/5.0(iphone;CPU iphone OS 5_1_1 like Mac OS X) AppleWebKit/534.46(KHTML,like Geocko)Mobile/9B206 MicroMessenger/5.0”

其中5.0表示付款人的微信版本。商家可以解析上面的 HTTP標題來檢查微信版本是否大於或等於5.0。

6.頁面標題中的微信安全支付副標題

出於交易安全原因,付款人可以在微信支付頁面的頁面標題中看到微信安全支付副標題。我們建議商家使用此副標題進行微信支付交易。

圖7.10微信安全支付副標題

圖7.10微信安全支付副標題

要顯示副標題,商家應在原始URL的末尾添加“showwxpaytitle = 1”。完成後,他們的頁面將顯示“微信安全支付”副標題。例如,對於原始URL(http://weixin.qq.com ),商家可以將其更改為帶有副標題的URL(http://weixin.qq.com?showwxpaytitle=1 )。

因此,當付款人在微信中打開 http://weixin.qq.com 時,他們將看不到副標題。但是,如果他們使用 http://weixin.qq.com?showwxpaytitle=1 ,則副標題將顯示在其打開頁面的標題中。

7.從HTML5網站請求微信支付API

當Payer打開一個支持微信的瀏覽器的HTML5網站時,就會調用JSAPI。輸入和輸出API數據採用JSON格式。

注意:WeixinJSBridge內置對像在其他瀏覽器中無效,列表中的參數名稱區分大小寫。

有關“getBrandWCPayRequest”參數和返回值定義,請參見表7.1。有關返回值描述,請參見表7.2。

表7.1基於HTML5的API參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

Timestamp

時間戳

time_stamp

Yes

String(10)

1414488825

Specifies the current system time. For more information, see Time Protocol in Section 4.2 Parameter Specifications.

指定當前系統時間。有關更多信息,請參見第4.2節“參數規範 ”中的時間協議。

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16 CQ2502SI8ZNMT M67VS

32 characters or fewer. For
more information, see Section
4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Order Extension String

訂單擴展字符串

package

Yes

String(128)

prepay_id=123 456789

Specifies the parameter value (prepay_id) returned by the Unified Order API. The submission format is “prepay_id=***”.

指定Unified Order API返回的參數值(prepay_id)。提交格式為“prepay_id = ***”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD72 7A4B6845133519 F3AD6

Specifies a signature. For more information, see Section 4.3.1 Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign type

簽名類型

signType

Yes

String(32)

MD5

Currently HMAC-SHA256 and MD5 are supported

目前支持HMAC-SHA256和MD5

表7.2基於Web的微信支付API返回數據描述

Return
Value

返回值

Description

描述

get_brand_wcpay_request:ok

Payment
successful

付款成功

get_brand_wcpay_request:cancel

Payment
canceled

付款取消

get_brand_wcpay_request:fail

Payment
failed

付款失敗

僅當付款人完成付款時,JSAPI才會返回“get_brand_wcpay_request:ok”。對於前端邏輯,“get_brand_wcpay_request:cancel”或“get_brand_wcpay_request:fail”可以作為支付例外處理。

例如:

function onBridgeReady(){
WeixinJSBridge.invoke(

‘getBrandWCPayRequest’,
{

“appId” : “wx2421b1c4370ec43b”, //Official Account
name transferred by vendors

“timeStamp”:” 1395712654″, //Timestamp
since 1.1.1970 UTC

“nonceStr” : “e61463f8efa94090b1f366cccfbbb444”, //Random string

“package” :
“prepay_id=u802345jgfjsdfgsdg888”,

“signType” : “MD5”, //WeChat signature type:

“paySign”
:
“70EA570631E4BB79628FBCA90534C63FF7FADD89” //WeChat
signature

},

<b’>function(res){

if(res.err_msg == “get_brand_wcpay_request:ok” )
{} // Use the above
method to determine
values returned to the front-end. Please note that
“res.err_msg” returns”ok” after a successful payment. However, WeChat doesn’t guarantee its reliability.

}

);

}

<b’>if (typeof WeixinJSBridge == “undefined”){

if(
document.addEventListener ){ document.addEventListener(‘WeixinJSBridgeReady’,
onBridgeReady, false);

}else if (document.attachEvent){
document.attachEvent(‘WeixinJSBridgeReady’,
onBridgeReady); document.attachEvent(‘onWeixinJSBridgeReady’,
onBridgeReady);

}

}<b’>else{

onBridgeReady();

}

8.統一訂單API

交易類型字段(trade_type)需要JSAPI。有關詳細信息,請參閱【9.1節統一訂單】。

9.查詢訂單API

有關更多信息,請參閱【9.2查詢順序】。

10.關閉訂單API

有關更多信息,請參閱【9.3節關閉順序】。

11.提交退款API

有關詳細信息,請參閱【9.4節提交退款】。

12.查詢退款API

有關更多信息,請參閱【9.5節查詢退款】。

13.下載調節文件API

有關更多信息,請參閱【9.6節下載對帳文件】。

八、應用內付款

1. 使用案例

此方法適用於商家集成到移動應用中的微信支付。

商家的應用程序調用微信提供的SDK使用微信支付模塊,並重定向到微信支付交易。完成交易後,微信重新打開商家的應用程序,並顯示包含付款結果的頁面。

目前,微信支持iOS,Android和Windows Phone。

詳細步驟如下:

第1步:付款人進入商家的應用程序,選擇產品並確認交易以繼續付款。商家的服務後臺創建付款訂單並對其進行簽名,相關數據將傳輸到商家的應用程序,如圖8.1所示。

第2步:付款人點擊確認付款,並在微信中打開付款頁面以支付訂單,如圖8.2所示。

第3步:付款人確認收款人和金額,然後點擊付款。然後會顯示一個頁面,提示付款人輸入他們的付款密碼。付款人可以選擇使用銀行卡或Balance付款,如圖8.3所示。

圖8.1商家應用程序示例屏幕 圖8.2重定向到付款微信中的頁面 圖8.3:付款人進入他們的付款密碼

圖8.1商家應用程序示例屏幕

圖8.2重定向到付款微信中的頁面

圖8.3:付款人進入他們的付款密碼

第4步:付款人輸入付款密碼以完成交易。如果付款成功,付款人的微信就會顯示包含付款結果的頁面,如圖8.4所示。

第5步:頁面重新打開商家的應用程序,該應用程序將根據付款結果顯示訂單處理結果。

圖8.4成功後提示付款 圖8.5重新打開的提示商家的應用程序

圖8.4成功後提示付款

圖8.5重新打開的提示商家的應用程序

2.參與的商家

JD和Yixun應用程序現在支持此付款方式。

3.服務流程

這種付款方式解釋如下。統一訂單API,查詢訂單API和接受訂單通知需要簽名,簽名是在商家的服務後臺創建的,如圖8.6所示。

圖8.6應用程序內支付順序圖

圖8.6應用程序內支付順序圖

下面顯示了商家的後臺如何與微信支付系統進行交互:

第1步:付款人在商家的應用程序中選擇產品,提交訂單,並選擇微信支付。

第2步:商家接收付款人的付款交易並調用Unified Order API。有關更多信息,請參見第9.1節【統一訂單】。

第3步:Unified Order API返回正常的prepay_id,並根據該值創建簽名簽名規則。相關數據將傳輸到商家的應用程序。簽名中包含的字段包括cappId,partnerId,prepayId,nonceStr,timeStamp和package。

注意:包的值格式為Sign = WXPay

第4步:商家的應用程序使用SDK在微信中打開微信支付。有關更多信息,請參見第8.5節【基於應用程序的開髮指南】。

第5步:商家的後臺收到付款通知。有關更多信息,請參見第9.7節【一般付款結果通知】。

第6步:商家的後臺查詢付款結果。有關更多信息,請參見第9.2節【查詢訂單】。

4.了解有關此API的更多信息

https://open.weixin.qq.com/zh_CN/htmledition/res/dev/document/sdk/ios/index.html

5.從APP請求微信支付API

關於詳細的基於應用程序的開發過程,請參閱第8.6章,從APP請求微信支付API。

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

APP Application ID

APP應用程序ID

appid

Yes

String(32)

wx888888888 8888888

This ID is issued after vendors have register their APP on WeChat open platform.

商家在微信開放平台上註冊APP後發出此ID。

Vendor ID

商家ID

partnerid

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat
Payment

指定微信支付分配的商家ID

Prepaid Trading ID

預付交易ID

prepayid

Yes

String(32)

WX121775250 120140703323

3368018

Specifies the parameter value (prepay_id) returned by the Unified Order API.

指定Unified Order API返回的參數值(prepay_id)。

Order Extension String

訂單擴展字符串

package

Yes

String(128)

Sign=WXPay

Specify as the static value “Sign=WXPay”

指定為靜態值“Sign=WXPay”

Random String

隨機字符串

noncestr

Yes

String(32)

5K8264ILTKC H16CQ2502SI 8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Time stamp

時間戳

timestamp

Yes

String(10)

1414561699

Specifies the current time. For more information, see Timestamp in Section 4.2 Parameter Specifications.

指定當前時間。有關更多信息,請參見第4.2節“參數”中的時間戳規格。

Signature

簽名

sign

Yes

String(32)

C380BEC2BF D727A4B6845 133519F3AD6

Specifies a signature. For more information, see Section 4.3.1
Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

返回的數據:

Return Value

返回值

Description

描述

Solution

0

Payment successful

支付成功

Show the payment successful page

顯示付款成功頁面

-1

Payment error

付款錯誤

Possible reasons: sign error, unregistered appid, incorrect project appid, registered appid not match to the set one, etc.

可能的原因:簽名錯誤,未註冊的appid,錯誤的項目appid,註冊的appid與設置的appid不匹配等。

-2

Payment cancelled

付款已取消

No need to settle. User gives up the payment, etc.

無需解決。用戶放棄付款等。

6.基於應用程序的開髮指南

A. iOS說明

我們將使用運行iOS 7.0環境的Xcode10.0作為示例來說明該過程。

1) 項目設置的APPID

在商家成功在微信開放平台上申請應用程序後,平台將向商家提供唯一的APPID。在Xcode中創建項目時,開發人員應在“URL Schemes”字段中輸入APPID值,如圖8.7中的紅色標記。

圖8.7 微信支付境外商戶AApay

圖8.7

2) 註冊APPID 應將WeChat SDK“lib”和“head”文件導入Xcode項目。在調用API之前,您應該使用微信註冊您的APPID,如下所示:

[WXApiregisterApp:@”wxd930ea5d5a258f4f” withDescription:@”demo 2.0″];

3) 請求付款

商家的服務器調用Unified Order API(有關更多信息,請參見第9.1節“統一訂單”)以創建高級轉賬。在獲得prepay_id並簽署相關參數之後,將預先交易數據傳送到App以開始付款。有關如何執行此操作的示例,請參見下文:

PayReq *request = [[[PayReq alloc] init] autorelease];
request.partnerId = @”10000100″;
request.prepayId= @”1101000000140415649af9fc314aa427″;
request.package = @”Sign=WXPay”;
request.nonceStr= @”a462b76e7436e98e0ed6e13c64b4fd1c”;
request.timeStamp= @”1397527777″;
request.sign= @”582282d72dd2b03ad892830965f428cb16e7a256″;
[WXApi safeSendReq:request];

4) 付款結果回調

如SDK中包含的示例所示,onResp()可以添加到WXPayEntryActivity中。完成付款後,微信將被重定向到商家的應用程序並使用onResp()進行回調。開發人員在此函數中接收通知,並在必要時確定返回的錯誤代碼。如果付款成功,將從微信支付系統查詢付款結果並顯示給

付款人。付款結果取決於微信支付系統的付款通知,並在查詢API後將結果返回給付款人。有關如何執行此操作的示例,請參見下文:


(void)onResp:(BaseResp
*)resp {

if ([resp isKindOfClass:[PayResp class]]) { PayResp *response
= (PayResp *)resp; switch
(response.errCode) {

case
WXSuccess:

//Prompt of successful payment according to
server-based query result or API returned data NSlog(@”Payment
Successful”);

break; default:

NSlog(@”Payment
Failed

retcode=%d”,resp.errCode);

break;

}

}

}

errCode值列表:

Name

Description

描述

Solution

0

Success

成功

Displays the success page

顯示成功頁面

-1

Error

錯誤

This may be caused by signature error, unregistered APPID, incorrect APPID in project settings, unmatched APPID in the registration and project settings, or other exceptions.

這可能是由簽名錯誤,未註冊的APPID,項目設置中的APPID不正確,註冊和項目設置中不匹配的APPID或其他異常引起的。

-2

Canceled by user

由用戶取消

This occurs when the Payer cancels payment and returns to the App. In this case, no
further steps are required.

付款人取消付款並返回應用程序時會發生這種情況。在這種情況下,不需要進一步的步驟。

B. Android說明

1)後臺設置

在商家成功在微信開放平台上申請應用程序後,平台將向商家提供唯一的APPID。出於支付安全原因,商家的應用程序包名稱和簽名必須在平台中匹配。只有正確配置才能付款。這可以通過微信開放平臺中的 “App Platform ( 應用平台) ” → “Android App ( Android應用) ” 完成。如圖8.8中的紅色標記。

微信支付境外商戶AApay

圖8.8

應用程序包名稱與應用程序項目設置的配置文件“AndroidManifest.xml”中設置的名稱相同。例如,查看圖8.9中的包名“net.sourceforge.simcpux”。

App簽名是用於根據項目的應用程序包名稱進行編譯的密鑰庫,該名稱應該是由簽名工俱生成的32位md5字符串。如果開發人員在測試手機上安裝簽名工具,他們可以運行它來生成應用程序的簽名字符串,如圖8.9中的綠色字符串所示。從以下URL下載簽名工具:

微信支付境外商戶AApay

圖8.9

2) 註冊APPID

應將WeChat JAR包導入App項目。在調用API之前,您需要在微信中註冊您的APPID,如下所示:

在調用API之前,您應該使用微信註冊您的APPID,如下所示:

final IWXAPI
msgApi = WXAPIFactory.createWXAPI(context, null);

//用微信註冊這個應用程序

msgApi.registerApp(“wxd930ea5d5a258f4f”);

3) 請求付款

商家的服務器調用Unified
Order API(有關更多信息,請參見第9.1節“統一訂單”)以創建高級轉賬。在獲得prepay_id並簽署相關參數之後,將預先交易數據傳送到App以開始付款。請參閱下面的示例,了解如何執行此操作:

IWXAPI api;
PayReq request =
new PayReq();
request. appId = “wxd930ea5d5a258f4f”;
request. partnerId = “1900000109”;
request.prepayId= “1101000000140415649af9fc314aa427”,;
request. packageValue = “Sign=WXPay”;
request.nonceStr= “1101000000140429eb40476f8896f4c9”;
request.timeStamp= “1398746574”;
request.sign= “7ffecb600d7157c5aa49810d2d8f28bc2811827b”;
api.sendReq(req);

4)付款結果回調

如SDK中包含的示例所示,onResp()可以添加到WXPayEntryActivity中。完成付款後,微信將被重定向到商家的應用程序並使用onResp()進行回調。開發人員在此函數中接收通知,並在必要時確定返回的錯誤代碼。如果

付款成功後,付款結果將從微信支付系統查詢並顯示給付款人。付款結果取決於微信支付系統的付款通知,並在查詢API後將結果返回給付款人。請參閱下面的示例,了解如何執行此操作:

public void onResp(BaseResp
resp) {

<b’>if (resp.getType() == ConstantsAPI.COMMAND_PAY_BY_WX) { Log.d(TAG, “onPayFinish, errCode = ” + resp.errCode); AlertDialog.Builder builder = new AlertDialog.Builder(this);
builder.setTitle(R.string.app_tip);

}

}

errCode值列表:

Name

Description

描述

Solution

0

Success

成功

Displays the success page

顯示成功頁面

-1

Error

錯誤

This may be caused by signature error, unregistered APPID, incorrect APPID in project settings, unmatched APPID in the registration and project settings, or other exceptions.

這可能是由簽名錯誤,未註冊的APPID,項目設置中的APPID不正確,註冊和項目設置中不匹配的APPID或其他異常引起的。

-2

Canceled by user

由用戶取消

This occurs when the Payer cancels payment and returns to the App. In this case, no
further steps are required.

付款人取消付款並返回應用程序時會發生這種情況。在這種情況下,不需要進一步的步驟。

7.統一訂單API

交易類型(trade_type)字段需要APP。有關詳細信息,請參閱【9.1節未完成訂單】。

8.查詢訂單API

有關更多信息,請參閱【9.2查詢順序】。

9.關閉訂單API

有關更多信息,請參閱【9.3節關閉順序】。

10.提交退款API

有關詳細信息,請參閱【9.4節提交退款】。

11.查詢退款API

有關更多信息,請參閱【9.5節查詢退款】。

12.下載調節文件API

有關更多信息,請參閱【9.6節下載對帳文件】。

九、Public API

Public API充當要調用以訪問各種補充功能的公共API接口。商家可以根據需要選擇集成這些功能。公共API包括統一訂單,常規通知,查詢訂單,關閉訂單,提交退款,退款查詢,下載調節文件和短URL轉換功能,這些功能在以下小節中詳細說明。

1.統一訂單

A. 使用案例

對於Quick Pay方法以外的場景,Vendor的後臺調用此API在WeChat支付服務後臺創建預付款交易,並通過QR碼支付啟動支付流程。訂單成功提交後,JSAPI,App和其他付款方式。

B. 網址

網址:https://api.mch.weixin.qq.com/pay/unifiedorder

C. 證書要求

無需證書。

D. 請求參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by
WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat
Payment

微信支付分配的商家ID

Device
ID

設備ID

device_info

No

String(32)

013467007045764

Specifies a Terminal device ID (such as store number as defined by the vendor)

指定終端設備ID(例如商家定義的商店編號)

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD727A4B

6845133519F3AD6

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign
type

簽名類型

sign_type

NO

String(32)

HMAC-SHA256 / MD5

Currently support HMAC-SHA256 and MD5, default is MD5. If you choose HMAC-SHA256, sign_type must be pass

目前支持HMAC-SHA256和MD5,默認為MD5。如果選擇HMAC-SHA256,則必須傳遞sign_type

Item

Description

商品描述

body

Yes

String(128)

iPad Mini in white with 16G memory

Short description of item(s) to be purchased for the Payer, Please refer to Section 4.2, item 6

有關付款人購買商品的簡短說明,請參閱 第4.2節第6項

Item Details

項目細節

detail

No

String(600 0)

{
“goods_detail”:[
{
“goods_id”:”iphone6s_16G”,
“wxpay_goods_id”:”1001″,
“goods_name”:”iPhone6s 16G”,
“goods_num”:1,”price”:528800,
“goods_category”:”123456″,
“body”:”苹果手机”
},
{
“goods_id”:”iphone6s_32G”,
“wxpay_goods_id”:”1002″,
“goods_name”:”iPhone6s 32G”,
“quantity”:1,”price”:608800,
“goods_category”:”123789″,
“body”:”苹果手机”

}

]

}

Detailed product list described in JSON format. Please use CDATA
tag to protect the JSON string when generating signature.
goods_detail []:
└goods_id String Required 32
Goods ID
└wxpay_goods_id StringOptional 32 The unified goods ID
defined by WeChat
└goods_name String Required
256 Goods name
└ quantity Int Required Goods
amount
└price Int Required Goods price, unit as cent
Note: The goods price should be less than total_fee and it should be the favorable price.

以JSON格式描述的詳細產品列表。生成簽名時,請使用CDATA標記來保護JSON字符串。

goods_detail [] :

└ goods_id串所需32商品編號

└ wxpay_goods_id字符串

可選32微信定義的統一商品ID

└ goods_name串所需

256商品名稱

└ 數量Int所需商品數量

└ 價格Int所需商品

價格,單位為分

注意:商品價格應低於total_fee,應該是優惠價格。

Additional Data

其他數據

attach

No

String(128)

User-Defined Data

Allow vendors an additional field to be returned in the payment notification after submitting a payment or in the Query Order API

允許商家在提交付款後或在查詢訂單API中在付款通知中返回其他字段

Vendor Order Number

商家

訂單號

out_trade_no

Yes

String(32)

12177525012014
07033233368018

32 alphanumeric characters or less. For more information, see Section 4.2 Vendor’s Order Number.

不超過32個字母數字字符。有關更多信息,請參見第4.2節“商家的訂單號”。

Currency Type

貨幣類型

fee_type

Yes

String(16)

GBP

ISO-4217 standard compliant and be described by three characters based code. For more information, see Section 4.2 Currency Type.

符合ISO-4217標準,可由三個基於字符的代碼描述。有關更多信息,請參見第4.2節“ 貨幣類型”。

Total Amount

總金額

total_fee

Yes

Int

888

Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Section 4.2. Payment Amount.

指定轉賬的總金額。單位為分,值必須為整數。有關更多信息,請參見第4.2節。

支付金額。

Terminal IP

終端IP

spbill_create_ip

Yes

String(16)

8.8.8.8

For Native Quick Pay, specifies the machine
IP that calls WeChat Payment API. While for Official Account Payment or In-App Payment, specifies the client terminal IP

對於Native Quick Pay,指定調用WeChat
Payment API的計算機IP。對於正式帳戶付款或應用程序內付款,指定客戶終端IP

Transaction Start Time

交易開始時間

time_start

No

String(14)

20091225091010

Specifies transaction creation time in the format of yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10. For more information, see Section 4.2 Time Protocol.

以yyyyMMddHHmmss格式指定轉賬創建時間,例如2009年12月25日09:10:10的20091225091010。

有關更多信息,請參見第4.2節“時間協議”。

Transaction End Time

交易結束時間

time_expire

No

String(14)

20091227091010

Specifies transaction creation time in the format of yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10. For more information, see Section 4.2 Time Protocol.

以yyyyMMddHHmmss格式指定轉賬創建時間,例如2009年12月25日09:10:10的20091225091010。

有關更多信息,請參見第4.2節“時間協議”。

Item Label

商品標簽

goods_tag

No

String(32)

WXG

Specifies the label of goods, which is a parameter in the coupon feature for businesses. For more information, see Section 10 Mobile Coupon.

指定商品標籤,這是商家優惠券功能中的參數。有關更多信息,請參閱第10節移動優惠券。

Notification URL

通知URL

notify_url

Yes

String(256)

http://www.baidu.com

Specifies the callback address for receiving WeChat payment notifications

指定接收微信支付通知的回調地址

Transaction Type

交易類型

trade_type

Yes

String(16)

JSAPI

Set to JSAPI, NATIVE, or APP

設置為JSAPI,NATIVE或APP

Product ID

產品ID

product_id

No

String(32)

12235413214070

356458058

This field is only required when trade_type is NATIVE. This ID contains the product ID as set by the Vendor.

僅當trade_type為NATIVE時才需要此字段。此ID包含商家設置的產品ID。

Specified Payment Method

特殊付款方式

limit_pay

No

String(32)

no_credit

no_credit: Using credit card for payment is not allowed

no_credit:不允許使用信用卡付款

User Tag

用戶標簽

openid

No

String(128)

oUpF8uMuAJO_M2pxb1Q9zNjWe S6o

This field is only required when trade_type is JSAPI. It is the only user identification under the current appid. About how to get the openid, please refer to http://admin.wechat.com/wiki/index.ph
p?title=User_Profile_via_Web

僅當trade_type為JSAPI時才需要此字段。它是當前appid下唯一的用戶標識。關於如何獲取openid,請參閱上面的連接。

示例如:

<xml>

<appid>wx2421b1c4370ec43b</appid>

<attach>Payment Testing</attach>

<body>JSAPI Payment Testing</body>

<mch_id>10000100</mch_id>

<nonce_str>1add1a30ac87aa2db72f57a2375d8fec</nonce_str>

<notify_url>http://wxpay.weixin.qq.com/pub_v2/pay/notify.v2.php</notify_url>

<openid>oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</openid>

<out_trade_no>1415659990</out_trade_no>

<spbill_create_ip>14.23.150.211</spbill_create_ip>

<total_fee>1</total_fee>

<trade_type>JSAPI</trade_type>

<sign>0CB01533B8C1EF103065174F50BCA001</sign>

</xml>

注意:參數在XML文件中進行轉義,CDATA標記用於說明XML解析器不會解析數據。

E. 返回數據

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return Status Code

返回狀態代碼

return_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field.

成功或失敗

指定通信標籤而不是轉賬標籤。轉賬的狀態由result_code字段的值確定。

Return Data

返回數據

return_msg

No

String(128)

Signature failure

If not empty, the returned info is the error description.

Signature failure

Parameter format checking error

如果不為空,則返回的信息是錯誤描述。

簽名失敗

參數格式檢查錯誤

如果return_code是SUCCESS,則返回數據還將包括以下字段:

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

The Official Account ID submitted when calling the interface

調用界面時提交的官方賬號ID

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

The Vendor ID submitted when calling the interface

調用接口時提交的商家ID

Device
ID

設備ID

device_info

No

String(32)

013467007045764

Specifies a Terminal device ID (such as store number as defined by the vendor)

指定終端設備ID(例如商家定義的商店編號)

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD727A4B6

845133519F3AD6

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Service Result

服務結果

result_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

成功或失敗

Error Code

錯誤代碼

err_code

No

String(32)

SYSTEMERROR

For more information, see Section 5.5.6 Error Code

有關更多信息,請參見第5.5.6節“錯誤代碼”

Error Code Description

錯誤代碼說明

err_code_des

No

String(128)

System error

Describes result data

描述結果數據

如果return_code和result_code都是SUCCESS,則返回數據還將包括以下字段:

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Transaction Type

交易類型

trade_type

Yes

String(16)

JSAPI

The transaction type submitted. The value could be JSAPI, NATIVE, or APP

提交的交易類型。值可以是JSAPI,NATIVE或APP

Advance Transaction ID

預付交易ID

prepay_id

Yes

String(64)

wx2014102720 09395522657a

690389285100

Specifies the advance transaction ID created by WeChat. It is used to call the Query Order API later. Validity is 2 hours.

指定微信創建的高級轉賬ID。它用於稍後調用查詢訂單API。有效期為2小時。

QR Code URL

QR碼網址

code_url

No

String(64)

URl:

weixin://wxpay/ s/An4baqw

This field is returned when trade_type is NATIVE. This parameter should be used to create a QR Code that is displayed to the Payer later.

trade_type為NATIVE時返回此字段。此參數應用於創建稍後顯示給付款人的QR碼。

示例如:

<xml>

<return_code><![CDATA[SUCCESS]]></return_code>

<return_msg><![CDATA[OK]]></return_msg>

<appid><![CDATA[wx2421b1c4370ec43b]]></appid>

<mch_id><![CDATA[10000100]]></mch_id>

<nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>

<sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>

<result_code><![CDATA[SUCCESS]]></result_code>

<prepay_id><![CDATA[wx201411101639507cbf6ffd8b0779950874]]></prepay_id>

<trade_type><![CDATA[JSAPI]]></trade_type>

</xml>

F. 錯誤代碼

Name

Description

描述

Reason

原因

Solution

NOAUTH

Vendor doesn’t have permission to use this
API

Vendors hasn’t enabled authorization for this API

The Vendor should apply for permission to use this API

商家無權使用此API

商家尚未啟用此API的授權

商家應申請使用此API的許可

NOTENOUGH

Insufficient balance

The Payer has an insufficient balance in their payment card

Inform the Payer to add funds to their account or to try another payment card

餘額不足

付款人的支付卡餘額不足

通知付款人將資金添加到他們的帳戶或嘗試其他支付卡

ORDERPAID

Order is paid

Order is already paid and cannot be paid for again

The order has already been paid and no further action is required

訂單已付清

訂單已付款且無法再次付款

訂單已經支付,無需進一步操作

ORDERCLOSED

Order is closed

The current order is closed and cannot be paid for again

The current order has already been closed.
The Payer should be told to create a new order.

訂單已結束

當前訂單已關閉,無法再次付款

目前的訂單已經關閉。應告知付款人創建新訂單。

SYSTEMERROR

System error

System has timed out

A system exception has occurred. Call the API again using the same parameters.

系統錯誤

系統已超時

發生了系統異常。使用相同的參數再次調用API。

APPID_NOT_EXIST

APPID DOES NOT EXIST

Provided APPID in this parameter does not exist

Check whether provided APPID is correct

APPID不存在

提供此參數中的APPID不存在

檢查提供的APPID是否正確

MCHID_NOT_EXIST

MCHID DOES NOT EXIST

Provided MCHID in this parameter does not exist

Check whether provided MCHID is correct

MCHID不存在

提供此參數中的MCHID不存在

檢查提供的MCHID是否正確

APPID_MCHID_ NOT_MATCH

appid does not match mch_id

appid does not match mch_id

Check whether appid belongs to the associated mch_id

appid與mch_id不匹配

appid與mch_id不匹配

檢查appid是否屬於關聯的mch_id

LACK_PARAMS

Missing parameter

Required parameter is missing

Check whether parameter is provided

缺少參數

缺少必需參數

檢查是否提供了參數

OUT_TRADE_N O_USED

Duplicate vendor order number

The same transaction can’t be submitted
repeatedly

Check whether vendor’s order number has
already been submitted or used previously

商家訂單號重複

同一交易無法重複提交

檢查商家的訂單號是否已經提交或先前使用過

SIGNERROR

Signature error

Incorrect signature result

Check whether signature parameter and method comply with signature algorithm requirements

簽名錯誤

簽名結果不正確

檢查簽名參數和方法是否符合簽名算法要求

XML_FORMAT_E RROR

INVALID XML FORMAT

INVALID XML FORMAT

Check whether XML parameters are in correct format

無效的XML格式

無效的XML格式

檢查XML參數的格式是否正確

REQUIRE_POST

_METHOD

Use post method

Data is not transferred by post

Check whether data is submitted via POST
method

使用post方法

數據不會通過郵寄方式傳輸

檢查數據是否通過POST方法提交

POST_DATA_EM PTY

post data is empty

post data can’t be empty

Check whether post data is empty

發布數據為空

發布數據不能為空

檢查發布數據是否為空

NOT_UTF8

Invalid coding format

Specified coding format is not used

Use NOT_UTF8 coding format

編碼格式無效

不使用指定的編碼格式

使用NOT_UTF8編碼格式

2.查詢訂單

A. 使用案例

此API允許查詢從微信發出的所有付款訂單。在使用此API接收狀態代碼後,商家可以繼續執行服務邏輯的下一步。以下是何時使用查詢訂單API的情況:

1)由於商家的後臺,網絡或服務器中的例外,賣家未收到任何付款;

2)調用支付界面後返回系統錯誤或未知轉賬狀態;

3)調用Quick Pay API後返回USERPAYING狀態;

4)在請求Close Order API或撤銷訂單API之前確認付款狀態;

B. 網址

https://api.mch.weixin.qq.com/pay/orderquery

C. 證書要求

無需證書。

D. 請求參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat Payment

微信支付分配的商家ID

WeChat
Order

Number

微信訂單號

transaction_id

Choose

one to

submit

選擇其中一個提交

String(32)

013467007045764

WeChat order umber is preferred

微信訂單號是首選

Vendor Order Number

商家訂單號

out_trade_no

String(32)

121775250120140

7033233368018

32 alphanumeric characters or less. For more information, see Section 4.2 Vendor’s Order Number.

不超過32個字母數字字符。有關更多信息,請參見第4.2節“商家的訂單號”。

Random String

隨機字符串

nonce_str

Yes

String(32)

C380BEC2BFD727A

4B6845133519F3AD6

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

5K8264ILTKCH16CQ

250
2SI8ZNMTM67VS

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign
type

簽名類型

sign_type

NO

String(32)

HMAC-SHA256 / MD5

Currently support HMAC-SHA256 and MD5, default is MD5. If you choose HMAC-SHA256, sign_type must be pass

目前支持HMAC-SHA256和MD5,默認為MD5。如果選擇HMAC-SHA256,則必須傳遞sign_type

示例如:

<xml>

<appid>wx2421b1c4370ec43b</appid>

<mch_id>10000100<b’></mch_id>

<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>

<transaction_id>1008450740201411110005820873</transaction_id>

<sign>FDD167FAA73459FD921B144BAF4F4CA2</sign>

</xml>

E. 返回數據

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return Status Code

返回狀態代碼

return_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

Specifies communicating label instead of transaction label. The status of a transaction is determined by the value of trade_state.

成功或失敗

指定通信標籤而不是轉賬標籤。交易狀態由trade_state的值決定。

Return Data

返回數據

return_msg

No

String(128)

Signature failure

If not empty, the returned info is the error description.

Signature failure

Parameter format checking error

如果不為空,則返回的信息是錯誤描述。

簽名失敗

參數格式檢查錯誤

如果return_code是SUCCESS,則返回數據還將包括以下字段:

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

The Official Account ID submitted when calling the interface

調用界面時提交的官方賬號ID

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

The Vendor ID submitted when calling the interface

調用接口時提交的商家ID

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD727A4B6

845133519F3AD6

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Service Result

服務結果

result_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

成功或失敗

Error Code

錯誤代碼

err_code

No

String(32)

SYSTEMERROR

For more information, see Section 5.5.6 Error Code

有關更多信息,請參見第5.5.6節“錯誤代碼”

Error Code Description

錯誤代碼說明

err_code_des

No

String(128)

System error

Describes result data

描述結果數據

如果return_code和result_code都是SUCCESS,則返回數據還將包括以下字段:

注意:如果trade_state不是SUCCESS,則只返回out_trade_no和attach。

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Device ID

設備ID

device_info

No

String(32)

01346700704

5764

Specifies the terminal device ID assigned by WeChat Payment

指定微信支付分配的終端設備ID

User Tag

用戶標籤

openid

Yes

String(128)

wxd930ea5d5 a258f4f

Specifies the user id of the Payer provided by the WeChat system in OpenID format unique to each appid instance

指定微信系統以每個appid實例唯一的OpenID格式提供的付款人的用戶ID

Follows Official Account or not

是否關注公衆號

is_subscribe

No

String(1)

Y

Specifies whether the payer follows the associated official account or not, with Y meaning ‘follows’ and N meaning ‘not follows’.

指定付款人是否遵循相關的官方賬號,Y表示”關注”,N表示”未關注”。

Transaction Type

交易類型

trade_type

Yes

String(16)

JSAPI

Set to JSAPI, NATIVE, MICROPAY or APP

設置為JSAPI,NATIVE,MICROPAY或APP

Transaction Status

交易狀態

trade_state

Yes

String(32)

SUCCESS

SUCCESS: Payment successful

付款成功

REFUND: Order to be refunded

退款訂單

NOTPAY: Order not paid

未付款訂單

CLOSED: Order closed

訂單已關閉

REVOKED: Order revoked

訂單撤銷

USERPAYING: Awaiting user to pay

等待用戶付款

PAYERROR: Payment failed (payment status failed to be returned by bank or other reasons)

付款失敗(付款狀態未能由銀行或其他原因退回)

Payment Bank

付款銀行

bank_type

Yes

String(16)

CMC

String states bank_type

字符串狀態bank_type

Total Amount

總金額

total_fee

Yes

Int

100

Specifies the total amount for a transaction. For more information, see Section 4.2. Payment Amount.

指定轉賬的總金額。有關更多信息,請參見第4.2節,支付金額。

Currency Type

貨幣類型

fee_type

Yes

String(8)

GBP

ISO-4217 standard compliant and be described by three characters based code. For more information, see Section 4.2 Currency Type.

符合ISO-4217標準,可由三個基於字符的代碼描述。有關更多信息,請參見第4.2節“貨幣類型”。

Cash Payment Amount

現金支付金額

cash_fee

Yes

Int

100

Specifies the total cash payment amount of a transaction. For more information, see Section 4.2 Payment Amount.

指定交易的現金支付總額。有關更多信息,請參見第4.2節“付款金額”。

Cash Type

現金類型

cash_fee_type

No

String(16)

CNY

ISO-4217 standard compliant and be described by three characters based code. For more information, see Section 4.2 Currency Type.

符合ISO-4217標準,可由三個基於字符的代碼描述。有關更多信息,請參見第4.2節“貨幣類型”。

Specifies the number of a WeChat payment
order

指定微信支付訂單的編號

transaction_id

Yes

String(32)

12177525012

01407033233

368018

Specifies the WeChat payment order id number

指定微信支付訂單ID號

Vendor Order Number

商家訂單號

out_trade_no

Yes

String(32)

12177525012

01407033233

368018

Specifies an order number created by a Vendors’ system, which is consistent with request.

指定商家系統創建的訂單號,該訂單號與請求一致。

Vendor’s Data Package

商家的數據包

attach

No

String(128)

123456

Specifies vendor’s data package, which is returned as it is.

指定商家的數據包,按原樣返回。

Payment End Time

付款結束時間

time_end

Yes

String(14)

20141030133

525

Specifies the transaction payment time in the format of yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10.

For more information, see Section
4.2 Time Protocol.

以yyyyMMddHHmmss格式指定交易付款時間,例如2009年12月25日09:10:10的20091225091010。

有關更多信息,請參見第4.2節“時間協議”。

Exchange Rate

匯率

rate

Yes

String(16)

650000000

The value is 10 to the 8th power times of the exchange rate from foreign currency to RMB. For example, the exchange rate from foreign currency to RMB is 6.5, the value will be 650000000

該值是從外幣到人民幣的匯率的10的8次冪。例如,從外幣到人民幣的匯率為6.5,值將為650000000

例如:

<xml>

<return_code><![CDATA[SUCCESS]]></return_code>

<return_msg><![CDATA[OK]]></return_msg>

<appid><![CDATA[wx2421b1c4370ec43b]]></appid>

<mch_id><![CDATA[10000100]]></mch_id>

<device_info><![CDATA[1000]]></device_info>

<nonce_str><![CDATA[TN55wO9Pba5yENl8]]></nonce_str>

<sign><![CDATA[BDF0099C15FF7BC6B1585FBB110AB635]]></sign>

<result_code><![CDATA[SUCCESS]]></result_code>

<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>

<is_subscribe><![CDATA[Y]]></is_subscribe>

<trade_type><![CDATA[MICROPAY]]></trade_type>

<bank_type><![CDATA[CCB_DEBIT]]></bank_type>

<total_fee>1</total_fee>

<fee_type><![CDATA[CNY]]></fee_type>

<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>

<out_trade_no><![CDATA[1415757673]]></out_trade_no>

<attach><![CDATA[Additional Order description]]></attach>

<time_end><![CDATA[20141111170043]]></time_end>

<trade_state><![CDATA[SUCCESS]]></trade_state>

</xml>

F. 錯誤代碼

Name

Description

描述

Reason

原因

Solution

ORDERNOTEXIST

This order does not exist

此訂單不存在

This order number does not exist in the query system

查詢系統中不存在此訂單號

This API only helps query successfully paid transactions. The Vendor should check whether the provided transaction ID is correct.

此API僅幫助查詢成功付款的交易。商家應檢查提供的交易ID是否正確。

SYSTEMERROR

System error

系統錯誤

Exception occurs when data is returned from backend

從後臺返回數據時發生異常

This is caused by system error. Try to query again.

這是由系統錯誤引起的。嘗試再次查詢。

3.關閉訂單

A. 使用案例

由於付款人未能支付訂單費用,因此需要在商家想要創建新訂單之前調用此API。原始訂單將被關閉,以避免重複付款。在微信支付系統中創建訂單後,如果付款人未在規定時間內付款,則不能在系統中執行進一步操作。為防止付款人繼續處理訂單,系統會調用此API以關閉訂單。

注意:創建訂單後不得短於5分鐘使用Close Order API。

B. 網址

https://api.mch.weixin.qq.com/pay/closeorder

C. 證書要求

無需證書。

D. 請求參數

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat Payment

微信支付分配的商家ID

Vendor Order Number

商家訂單號

out_trade_no

Yes

String(32)

121775250120

140703323336

8018

Specifies an internal order number created by the Vendor’s system

指定商家系統創建的內部訂單號

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD727A4B

6845133519F3AD6

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign
type

簽名類型

sign_type

NO

String(32)

HMAC-SHA256

Currently support HMAC-SHA256 and MD5, default is MD5. This field is only required when sign_type is HMAC- SHA256

目前支持HMAC-SHA256和MD5,默認為MD5。僅當sign_type為HMAC-SHA256時才需要此字段

例如:

<xml>

<appid>wx2421b1c4370ec43b</appid>

<mch_id>10000100</mch_id>

<nonce_str>4ca93f17ddf3443ceabf72f26d64fe0e</nonce_str>

<out_trade_no>1415983244</out_trade_no>

<sign>59FF1DF214B2D279A0EA7077C54DD95D</sign>

</xml>

E. 返回數據

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return Status Code

返回狀態代碼

return_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

Specifies communicating label instead of transaction label. The status of a transaction is determined by the value of trade_state.

成功或失敗

指定通信標籤而不是轉賬標籤。交易狀態由trade_state的值決定。

Return Data

返回數據

return_msg

No

String(128)

Signature failure

If not empty, the returned info is the error description.

Signature failure

Parameter format checking error

如果不為空,則返回的信息是錯誤描述。

簽名失敗

參數格式檢查錯誤

如果return_code是SUCCESS,則返回數據還將包括以下字段:

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

The Official Account ID submitted when calling the interface

調用界面時提交的官方賬號ID

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

The Vendor ID submitted when calling the interface

調用接口時提交的商家ID

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD727A4B6

845133519F3AD6

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Error Code

錯誤代碼

err_code

No

String(32)

SYSTEMERROR

For more information, see Section 5.5.6 Error Code

有關更多信息,請參見第5.5.6節“錯誤代碼”

Error Code Description

錯誤代碼說明

err_code_des

No

String(128)

System error

Describes result data

描述結果數據

例如:

<xml>

<return_code><![CDATA[SUCCESS]]></return_code>

<return_msg><![CDATA[OK]]></return_msg>

<appid><![CDATA[wx2421b1c4370ec43b]]></appid>

<mch_id><![CDATA[10000100]]></mch_id>

<nonce_str><![CDATA[BFK89FC6rxKCOjLX]]></nonce_str>

<sign><![CDATA[72B321D92A7BFA0B2509F3D13C7B1631]]></sign>

<result_code><![CDATA[SUCCESS]]></result_code>

</xml>

F. 錯誤代碼

Name

Description

描述

Reason

原因

Solution

ORDERPAID

Order is paid

Order is already paid and cannot be paid for again

The order has already been paid and no further action is required

訂單已付清

訂單已付款且無法再次付款

訂單已經支付,無需進一步操作

ORDERCLOSED

Order is closed

The current order is closed and cannot be
paid for again

The current order has already been closed.
The Payer should be told to create a new order.

訂單已結束

當前訂單已關閉,無法再次付款

目前的訂單已經關閉。應告知付款人創建新訂單。

SYSTEMERROR

Order does not exist

This order does not exist in the system

Don’t attempt to close this order yet as it is still a pending transaction

訂單不存在

該訂單在系統中不存在

不要嘗試關閉此訂單,因為它仍然是待處理的交易

ORDERNOTEXIST

APPID DOES NOT EXIST

Provided APPID in this parameter does not exist

Check whether provided APPID is correct

APPID不存在

提供此參數中的APPID不存在

檢查提供的APPID是否正確

SIGNERROR

Signature error

Incorrect signature result

Check whether signature parameter and method comply with signature algorithm requirements

簽名錯誤

簽名結果不正確

檢查簽名參數和方法是否符合簽名算法要求

XML_FORMAT_E RROR

INVALID XML FORMAT

INVALID XML FORMAT

Check whether XML parameters are in correct format

無效的XML格式

無效的XML格式

檢查XML參數的格式是否正確

REQUIRE_POST

_METHOD

Use post method

Data is not transferred by post

Check whether data is submitted via POST
method

使用post方法

數據不會通過郵寄方式傳輸

檢查數據是否通過POST方法提交

4.提交退款

A. 使用案例

在付款交易完成並且付款人或商家要求退款後的一段時間內,賣家可以通過此API退還付款人。微信支付系統成功收到並驗證退款申請後,付款人將根據退款規則退還原始付款金額。

注意:

1)對於超過3個月前完成的任何交易,不支持退款;

2)交易退款可以多次部分退款的形式處理。在這種情況下,需要原始訂單號,並且必須設置多個退款號。退款總金額不能超過原始付款金額。

注意:如果退款申請失敗,請使用相同的out_refund_no進行重試。

請求頻率限制:150qps,這意味著正常的退款請求應少於每秒150次。

錯誤或無效的請求頻率限制:6 qps,這意味著錯誤或無效的退款請求應少於每秒6次

注意:一個訂單的部分退款應少於50次。

B. 網址

https://api.mch.weixin.qq.com/secapi/pay/refund

C. 證書要求

需要雙向證書

D. 請求參數

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat Payment

微信支付分配的商家ID

Device
ID

設備ID

device_info

No

String(32)

013467007045764

Specifies the terminal device ID assigned by WeChat Payment. This field should match the value of device_info when the order was created.

指定微信支付分配的終端設備ID。創建訂單時,此字段應與device_info的值匹配。

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16CQ2

502SI8ZNMTM67VS

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

C380BEC2BFD727A4B

6845133519F3AD6

Specifies a signature. For more information, see Section 4.3.1 Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign
type

簽名類型

sign_type

NO

String(32)

HMAC-SHA256 / MD5

Currently HMAC-SHA256 and MD5 are supported, default is MD5. This field is only required when sign_type is HMAC-SHA256

目前支持HMAC-SHA256和MD5,默認為MD5。僅當sign_type為HMAC-SHA256時才需要此字段。

WeChat
Order

Number

transaction_id

Choose

one to

submit

選擇其中一個提交

String(32)

013467007045764

Specifies the WeChat payment order id number

指定微信支付訂單ID號

Vendor Order Number

商家訂單號

out_trade_no

String(32)

121775250120140

7033233368018

out_trade_no is an internal order number within the vendor’s system.

transaction_id will be used over out_trade_no if they are both provided by the vendor.

out_trade_no是商家系統內的內部訂單號。

如果商家提供了transaction_id,則它們將在out_trade_no上使用。

Vendor Refund Number

商家退款號碼

out_refund_no

Yes

String(32)

12177525012

01407033233

368018

Specifies the internal refund number, which is unique in the system. A single transaction can be processed as multiple partial refunds, with the total sum of the partial refunds being equal to the original one.

指定內部退款編號,該編號在系統中是唯一的。單個交易可以作為多個部分退款處理,部分退款的總和等於原始部分退款。

Total Amount

總金額

total_fee

Yes

Int

100

Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Section 4.2. Payment Amount.

指定轉賬的總金額。單位為分,值必須為整數。有關更多信息,請參見第4.2節。

支付金額。

Refund Amount

退款金額

refund_fee

Yes

Int

100

Specifies the total refund amount for a transaction. The units are expressed in cents and shall be an integer.Section 4.2 Payment Amount.

指定交易的總退款金額。單位以美分錶示,並且應為整數。第4.2節付款金額。

Currency Type

貨幣類型

fee_type

Yes

String(16)

GBP

ISO-4217 standard compliant and be described by three characters based code. For more information, see Section 4.2 Currency Type.

符合ISO-4217標準,可由三個基於字符的代碼描述。有關更多信息,請參見第4.2節“ 貨幣類型”。

Refund Reason

退款原因

refund_des c

No

String(80)

Products sold out

It will inform the shoppers the refund reason once merchants submit this field value.

一旦商家提交此字段值,它將通知購物者退款原因。

例如:

<xml>

<appid>wx2421b1c4370ec43b</appid>

<mch_id>10000100</mch_id>

<nonce_str>6cefdb308e1e2e8aabd48cf79e546a02</nonce_str>

<op_user_id>10000100</op_user_id>

<out_refund_no>1415701182</out_refund_no>

<out_trade_no>1415757673</out_trade_no>

<refund_fee>1</refund_fee>

<total_fee>1</total_fee>

<transaction_id></transaction_id>

<sign>FE56DD4AA85C0EECA82C35595A69E153</sign>

</xml>

E. 返回數據

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return Status Code

返回狀態代碼

return_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

成功或失敗

Return Data

返回數據

return_msg

No

String(128)

Signature failure

If not empty, the returned info is the error description.

Signature failure

Parameter format checking error

如果不為空,則返回的信息是錯誤描述。

簽名失敗

參數格式檢查錯誤

如果return_code是SUCCESS,則返回數據還將包括以下字段:

Field Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Result Code

結果代碼

result_code

Yes

String(16)

SUCCESS

SUCCESS/FAIL

SUCCESS: Receives refund application successfully. To get refund status, calling Query Refund API is required.

FAIL: Submitting refund application failed.

成功/失敗

成功:成功收到退款申請。要獲得退款狀態,需要調用Query Refund API。

失敗:提交退款申請失敗。

Error Code

錯誤代碼

err_code

No

String(32)

SYSTEMERROR

For more information, please refer to error code list

有關更多信息,請參閱錯誤代碼列表

Error Code Description

錯誤代碼說明

err_code_des

No

String(128)

System timed out

Describes result data

描述結果數據

Official Account ID

官方帳號

appid

Yes

String(32)

wx888888888888 8888

The Official Account ID submitted when calling the interface

調用界面時提交的官方賬號ID

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

The Vendor ID submitted when calling the
interface

調用接口時提交的商家ID

Device ID

設備ID

device_info

No

String(32)

01346700704576

4

Specifies the terminal device ID assigned by WeChat Payment. The value in this field must match the device_info value used when the order was created.

指定微信支付分配的終端設備ID。此字段中的值必須與創建訂單時使用的device_info值匹配。

Random String

隨機字符串

nonce_str

Yes

String(32)

5K8264ILTKCH16 CQ2502SI8ZNMT M67VS

32 characters or fewer

不超過32個字符

Signature

簽名

sign

Yes

String(32)

5K8264ILTKCH16 CQ2502SI8ZNMT M67VS

Specifies a signature. For more information, see Section 4.3.1 Signature Algorithm.

指定簽名。有關更多信息,請參見第4.3.1節簽名算法。

WeChat Order Number

微信訂單號

transaction_id

Yes

String(32)

12177525012014

07033233368018

Specifies the WeChat payment order id number

指定微信支付訂單ID號

Vendor Order Number

商家訂單號

out_trade_no

Yes

String(32)

12177525012014

07033233368018

Specifies an internal order number created by the Vendor’s system

指定商家系統創建的內部訂單號

Vendor Refund Number

商家退款號碼

out_refund_no

Yes

String(32)

12177525012014

07033233368018

Vendor Refund Number

商家退款號碼

WeChat Refund Number

微信退款號碼

refund_id

Yes

String(32)

12177525012014

07033233368018

WeChat Refund Number

微信退款號碼

Refund Amount

退款金額

refund_fee

Yes

Int

100

Specifies the total refund amount expressed in cents and must be an integer. For more information, see Section 4.2 Payment Amount

A refund can be processed as multiple partial refunds.

指定以美分錶示的總退款金額,且必須為整數。有關更多信息,請參見第4.2節“付款金額”

退款可以作為多次部分退款處理。

Currency Type

貨幣類型

refund_fee_type

Yes

String(8)

GBP

ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Section 4.2 Currency Type.

符合ISO-4217標準,可由三個基於字符的代碼描述。退款貨幣類型必須與出價貨幣類型相同。有關更多信息,請參見第4.2節“貨幣類型”。

Total Amount

總金額

total_fee

Yes

Int

100

Specifies the total order amount expressed in cents and must be an integer. For more information, see Section 4.2 Payment Amount

指定以美分錶示的總訂單金額,且必須為整數。有關更多信息,請參見第4.2節“付款金額”

Order Currency Type

訂單貨幣類型

fee_type

Yes

String(8)

GBP

ISO-4217 standard compliant and be described by three characters based code. For more information, see Section 4.2 Currency Type.

符合ISO-4217標準,可由三個基於字符的代碼描述。有關更多信息,請參見第4.2節“貨幣類型”

Cash Payment Amount

現金支付金額

cash_fee

Yes

Int

100

Specifies the cash payment amount expressed in cents and must be an integer. For more information, see Section 4.2 Payment Amount

指定以美分錶示的現金支付金額,並且必須是整數。有關更多信息,請參見第4.2節“付款金額”

Payment Currency Type

付款貨幣類型

cash_fee_type

Yes

String(8)

CNY

Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Section 4.2 Currency Type.

符合ISO 4217標準,默認使用CNY(人民幣)。有關更多信息,請參見第4.2節“貨幣類型”。

Cash Refund Amount

現金退款金額

cash_refund_fee

Yes

Int

100

Specifies the cash refund amount expressed in cents and must be an integer. For more information, see Section 4.2 Payment Amount

指定以美分錶示的現金退款金額,且必須為整數。有關更多信息,請參見第4.2節“付款金額”

Cash Refund Currency Type

現金退款貨幣類型

cash_refund_fee_type

No

String(8)

CNY

Complies with ISO 4217 standards and uses
CNY (Chinese yuan) by default. For more information, see Section 4.2 Currency Type.

符合ISO 4217標準,默認使用CNY(人民幣)。有關更多信息,請參見第4.2節“貨幣類型”。

Exchange Rate

匯率

rate

Yes

String(16)

650000000

The value is 10 to the 8th power times of the exchange rate from foreign currency to RMB. For example, the exchange rate from foreign currency to RMB is 6.5, the value will be 650000000

該值是從外幣到人民幣的匯率的10的8 次冪。例如,從外幣到人民幣的匯率為6.5,值將為650000000

例如:

<xml>

<return_code><![CDATA[SUCCESS]]></return_code>

<return_msg><![CDATA[OK]]></return_msg>

<appid><![CDATA[wx2421b1c4370ec43b]]></appid>

<mch_id><![CDATA[10000100]]></mch_id>

<nonce_str><![CDATA[NfsMFbUFpdbEhPXP]]></nonce_str>

<sign><![CDATA[B7274EB9F8925EB93100DD2085FA56C0]]></sign>

<result_code><![CDATA[SUCCESS]]></result_code>

<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>

<out_trade_no><![CDATA[1415757673]]></out_trade_no>

<out_refund_no><![CDATA[1415701182]]></out_refund_no>

<refund_id><![CDATA[2008450740201411110000174436]]></refund_id>

<refund_channel><![CDATA[]]></refund_channel>

<refund_fee>1</refund_fee>

<coupon_refund_fee>0</coupon_refund_fee>

</xml>

F. 錯誤代碼

Name

Description

描述

Reason

原因

Solution

SYSTEMERROR

API return error

API返回錯誤

System timed out

系統超時

Call this API again using the same parameters

使用相同的參數再次調用此API

USER_ACCOUNT_ ABNORMAL

Refund request failed

退款請求失敗

User’s account cancelled

用戶的帳戶已取消

This error code means refund request failed, merchants need to handle the refund by themselves

此錯誤代碼表示退款請求失敗,商家需要自行處理退款

NOTENOUGH

Not enough unsettled fund for refund

沒有足夠的未結算資金退款

There is not enough unsettled fund for
refund

沒有足夠的未結算資金退款

This error code means refund request failed, merchants need to recall the refund API once there is enough unsettled fund, or retry it continuously

此錯誤代碼表示退款請求失敗,商家需要在有足夠的未結算資金後召回退款API,或者連續重試

INVALID_TRANSAC TIONID

Invalid transaction_id

無效的transaction_id

Requested parameters are not correct

請求的參數不正確

Incorrect request parameters.

Check whether the original transaction ID exists or whether data failed to be returned from the payment interface.

請求參數不正確。

檢查原始轉賬ID是否存在,或者是否無法從支付界面返回數據

PARAM_ERROR

Parameter error

參數錯誤

Requested parameters are not correct

請求的參數不正確

Incorrect request parameters. Check the
parameters and call the Submit Refund API again.

請求參數不正確。檢查參數並再次調用Submit Refund API。

APPID_NOT_EXIST

APPID DOES NOT EXIST

APPID不存在

No APPID in this parameter

此參數中沒有APPID

Check whether the provided APPID is correct

檢查提供的APPID是否正確

MCHID_NOT_EXIST

MCHID DOES NOT EXIST

MCHID不存在

No MCHID in this parameter

此參數中沒有MCHID

Check whether the provided MCHID is correct

檢查提供的MCHID是否正確

APPID_MCHID_NO T_MATCH

appid does not match mch_id

appid與mch_id不匹配

appid does not match mch_id

appid與mch_id不匹配

Check whether appid belongs to the associated mch_id

檢查appid是否屬於關聯的mch_id

REQUIRE_POST_M ETHOD

Use post method

使用post方法

Data is not transferred by post

數據并非通過post傳輸

Check whether data is submitted by POST
method

檢查數據是否由POST方法提交

SIGNERROR

Signature error

簽名錯誤

Incorrect signature result

簽名結果不正確

Check whether the signature parameter and method complies with signature algorithm requirements

檢查簽名參數和方法是否符合簽名算法要求

XML_FORMAT_ER ROR

INVALID XML FORMAT

無效的XML格式

INVALID XML FORMAT

無效的XML格式

Check whether XML parameters are in the
correct format

檢查XML參數是否格式正確

5.查詢退款

A. 使用案例

提交提交退款後,可以調用此API來檢查退款狀態。提交退款後,可能會延遲處理退款:退款至20分鐘,以及退還銀行卡3個工作日。

注意:一旦部分退款超過20次,請使用商家退款號進行退款查詢。

B. 網址

https://api.mch.weixin.qq.com/pay/refundquery

C. 證書要求

無需證書。

D. 請求參數

注意:所有下標(如$ n)都是從0開始的

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Official Account ID

官方帳號

appid

Yes

String(32)

wx8888888888888888

Specifies Official Account ID assigned by WeChat

微信指定的官方帳號

Vendor ID

商家ID

mch_id

Yes

String(32)

1900000109

Specifies vendor ID assigned by WeChat Payment

微信支付分配的商家ID

Device ID

設備ID

device_info

No

String(32)

013467007045764

Specifies the terminal device ID assigned by WeChat Payment

指定微信支付分配的終端設備ID

Random String

隨機字符串

nonce_str

Yes

String(32)

C380BEC2BFD727A

4B6845133519F3AD6

32 characters or fewer. For more information, see Section 4.3.2 Random String Algorithm.

不超過32個字符。有關更多信息,請參見第4.3.2節“隨機字符串算法”。

Signature

簽名

sign

Yes

String(32)

5K8264ILTKCH16CQ

250 2SI8ZNMTM67VS

Signature. For more information, see Section 4.3.1 Signature Algorithm

簽名。有關更多信息,請參見第4.3.1節“簽名算法”。

Sign type

簽名類型

sign_type

NO

String(32)

HMAC-SHA256 / MD5

Currently support HMAC-SHA256 and MD5, default is MD5. If you choose HMAC-SHA256, sign_type must be pass

目前支持HMAC-SHA256和MD5,默認為MD5。如果選擇HMAC-SHA256,則必須傳遞sign_type

WeChat Order

Number

微信訂單號

transaction_id

Choose

one to

submit

選擇其中一個提交

String(32)

013467007045764

Specifies the WeChat payment order id number

指定微信支付訂單ID號

Vendor Order Number

商家訂單號

out_trade_no

String(32)

121775250120140

7033233368018

out_trade_no is an internal order number within the vendor’s system.

transaction_id will be used over out_trade_no if they are both provided by the vendor.

out_trade_no是商家系統內的內部訂單號。

如果商家提供了transaction_id,則它們將在out_trade_no上使用。

Vendor Refund Number

商家退款號碼

out_refund_no

String(32)

12177525012014

07033233368018

Vendor Refund Number

商家退款號碼

WeChat Refund Number

微信退款號碼

refund_id

String(32)

12177525012014

07033233368018

WeChat Refund Number. Returned from Submit Refund API.

This field will supply the refund_id, out_refund_no, out_trade_no, or transaction_id. Their priority is as shown below:

refund_id>out_refund_no>transactio
n_id>out_trade_no

微信退款號碼。從Submit Refund API返回。

該字段將提供refund_id, out_refund_no, out_trade_no或transaction_id。他們的優先事項如下所示:

refund_id> out_refund_no> transaction_id> out_trade_no

例如:

<xml>

<appid>wx2421b1c4370ec43b</appid>

<mch_id>10000100<b’></mch_id>

<nonce_str>0b9f35f484df17a732e537c37708d1d0</nonce_str>

<out_refund_no></out_refund_no>

<out_trade_no>1415757673<b’></out_trade_no>

<refund_id></refund_id>

<transaction_id></transaction_id>

<sign>66FFB727015F450D167EF38CCC549521</sign>

</xml>

E. 返回數據

Field
Name

字段名稱

ID

Required

必要

Type

類型

Example

Description

描述

Return Status Code

返回狀態代碼

return_code

Yes

String(16)

SUCCESS

SUCCESS or FAIL

Specifies communicating label instead of transaction label. The status of the transaction is determined by the value
of the result_code field.

成功或失敗

指定通信標籤而不是轉賬標籤。轉賬的狀態由result_code字段的值確定。

Return Data

返回數據

return_msg

No

String(128)

Signature failure

If not empty, the returned info is the error description.

Signature failure

Parameter format checking error

如果不為空,則返回的信息是錯誤描述。

簽名失敗

參數格式檢查錯誤

如果return_code是SUCCESS,則返回數據還將包括以下字段:

Field
Name

字段名稱

ID

Required

必要