支付宝微信扫码支付调研
一、支付宝扫码支付
1.1 系统流程说明
1.1.1 条码支付（被扫）
条码支付是支付宝给到线下传统行业的一种收款方式。商家使用扫码枪等条码识别设备扫描用户支付宝钱包上的条码/二维码，完成收款。用户仅需出示付款码，所有收款操作由商家端完成。
使用步骤：
1.用户登录支付宝钱包，点击首页“付款”，进入付款码界面；
2.收银员在商家收银系统操作生成订单，用户确认支付金额；
3.用户出示钱包的“付款码”，收银员用扫码设备来扫描用户手机上的条码/二维码后，商家收银系统提交支付；
4.付款成功后商家收银系统会拿到支付成功或者失败的结果。
产品特点：
收银系统需要有红外扫描枪设备；
用户仅出示手机即可完成付款，方便快捷；
手机无网络要求，可离线支付；
资金实时到账，无现金流压力；
支付宝会根据交易金额、登录状态等信息判断是否需要用户输入密码。
条码支付的流程时序图：
1.商户系统将用户付款码与订单信息一起通过交易支付接口alipay.trade.pay请求到支付宝，并从接口同步返回中获取支付结果。
2.根据公共返回参数中的code，这笔交易可能有四种状态：支付成功（10000），支付失败（40004），等待用户付款（10003）和未知异常（20000）。
特别注意：商户订单号out_trade_no在任何情况下不可重复，即时对于失败或撤销的交易，商户订单号也可能已经被使用了，如需再次发起支付，必须使用新的商户订单号调用接口，否则会报错。
1.1.2 扫码支付（主扫）
扫码支付，指用户打开支付宝钱包中的“扫一扫”功能，扫描商家展示在某收银场景下的二维码并进行支付的模式。该模式适用于线下实体店支付、面对面支付等场景。
使用步骤：
1.收银员在商家收银系统操作生成支付宝订单，并生成二维码；
2.用户登录支付宝钱包，点击首页“付款-扫码付”或直接点击“扫一扫”，进入扫一扫界面；
3.用户扫收银员提供的二维码，核对金额，确认支付；
4.用户付款后商家收银系统会拿到支付成功或者失败的结果。
产品特点：
1.用户仅出示手机扫码即可完成付款，方便快捷；
2.资金实时到账，无现金流压力。
扫码支付的调用时序图:
扫码支付，指用户打开支付宝钱包中的“扫一扫”功能，扫描商户针对每个订单实时生成的订单二维码，并在手机端确认支付。
1.1.3 退款说明
商户由于业务原因可能需要退款，退款的途径按照支付途径原路返回. 支付渠道为花呗、余额等退款即时到账。银行卡的退款时间以银行退款时间为准，一般情况下2小时内可到账。也可以在商户门户(b.alipay.com)中退款
当商户因为业务原因如金额错误，用户退货，对账不平等情况下可能需要退款，可以使用交易成功的商户订单号或支付宝交易号进行退款 , 支持全额和部分退款，其过程如下图所示。
1.1.4 对账说明
场景介绍
商户/系统商可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。
获取账单技术实现大致分两种模式：收款账号接入模式（签约账号即为收款账号）、主账号签约接入模式（此种模式包括ISV接入模式、一个主账号签约+N个收款账号接入模式）。
1. 收款账号接入模式
下载接口中指定appid所对应PID下所有交易记录的对账单。
2. 主账号签约接入模式
包括ISV接入模式、一个主账号签约+N个收款账号接入模式。
第一步：该应用在开放平台上添加第三方应用授权功能。让收款账号给签约主账号授权。收款账号无需签约账单下载接口权限。
第二步：请获取服务端SDK进行接口开发，请在请求参数中传入授权token。签约账号即可查询收款账号的账单。包括账务账单和业务账单。
调用流程
1.商户系统调用查询对账单下载地址接口alipay.data.dataservice.bill.downloadurl.query，传入指定日期，获得该日期账单文件的下载地址。
2.商户系统通过HTTP方式后台访问账单下载链接，将账单csv文件下载到本地后自行处理。注意该下载链接仅30秒，在得到链接后系统需要立刻请求下载账单文件。
业务明细账单：
账务账单明细：
1.1.5 常见资费说明
当面付的费率:
| 服务名称 |
费率 |
服务期限 |
| 单笔费率 |
0.6% |
1年 |
助力中小商户，从签约日至2017.12.31日优惠费率为0.55%（不包含特殊行业）
特殊行业：休闲游戏；网络游戏点卡、游戏渠道代理；游戏系统商；网游周边服务、交易平台；网游运营商（含网页游戏）
非盈利性机构费率：
非营利性机构（如公益机构、公共医院、公立学校等）接入支付宝则继续保持免费，民生服务行业（如水电煤生活缴费、公共交通等）也将维持原有优惠费率不变。
参考官网地址：https://docs.open.alipay.com/300/106140
| 行业 |
商户约定费率 |
服务商基准费率 |
| 停车 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
| 公立医院 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率享受0费率优惠） |
服务商名下所有商户，基准费率为0.2% |
| 民营医院 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
| 服务商名下所有商户，基准费率为0.2% |
||
| 药店 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
| 水燃机构 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.3%） |
服务商协作费按照签约服务合同约定为准 |
| 中小学、幼儿园 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率享受0费率优惠） |
服务商协作费按照签约服务合同约定为准 |
| 物业 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
|
酒店 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
|
客运 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
|
智慧县域 |
商户与支付宝签约的支付宝服务合同约定的或支付宝实际执行的软件服务费率，以较低者为准。 （现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2%
|
| 品牌零售 |
商户与支付宝签署的支付宝服务合同约定的或支付宝实际执行的软件服务费费率，以较低者为准（现行商户实际费率为0.55%） |
服务商名下所有商户，基准费率为0.2% |
1.2 申请要素
1.2.1 申请材料
1. 企业或个体工商户可申请；
2. 需提供真实有效的营业执照；如与签约主体不一致者需提供授权函；授权函要求：公司类型必须盖公章、个体工商户需两选一；
a.法人身份证原件+法人签字；
b.法人身份证原件+个体工商户盖章；
3. 提供门头/内景照片。
1.2.2 上线配置参数
1. partnerId
2. 应用appId
3. 应用私钥
4. 应用公钥
5. 支付宝公钥
6. 签名类型（RSA或RSA2）
例如：
1.3 调用接口
支付宝提供测试沙箱环境，可以在沙箱环境测试完成再上线。
测试地址：https://openapi.alipaydev.com/gateway.do
生产地址：https://openapi.alipay.com/gateway.do
1.3.1 条码支付接口
alipay.trade.pay(统一收单交易支付接口)
支持第三方代理调用
收银员使用扫码设备读取用户手机支付宝“付款码”，将二维码或条码信息通过本接口上送至支付宝发起支付。
公共请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| app_id |
String |
是 |
32 |
支付宝分配给开发者的应用ID |
2014072300007148 |
| method |
String |
是 |
128 |
接口名称 |
alipay.trade.pay |
| format |
String |
否 |
40 |
仅支持JSON |
JSON |
| charset |
String |
是 |
10 |
请求使用的编码格式，如utf-8,gbk,gb2312等 |
utf-8 |
| sign_type |
String |
是 |
10 |
商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 |
RSA2 |
| sign |
String |
是 |
344 |
商户请求参数的签名串，详见签名 |
详见示例 |
| timestamp |
String |
是 |
19 |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
2014-07-24 03:07:50 |
| version |
String |
是 |
3 |
调用的接口版本，固定为：1.0 |
1.0 |
| notify_url |
String |
否 |
256 |
支付宝服务器主动通知商户服务器里指定的页面http/https路径。 |
http://api.test.alipay.net/atinterface/receive_notify.htm |
| app_auth_token |
String |
否 |
40 |
详见应用授权概述 |
|
| biz_content |
String |
是 |
|
请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
|
请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| out_trade_no |
String |
必选 |
64 |
商户订单号,64个字符以内、可包含字母、数字、下划线；需保证在商户端不重复 |
20150320010101001 |
| scene |
String |
必选 |
32 |
支付场景 |
bar_code |
| auth_code |
String |
必选 |
32 |
支付授权码，25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准 |
28763443825664394 |
| product_code |
String |
可选 |
32 |
销售产品码 |
FACE_TO_FACE_PAYMENT |
| subject |
String |
必选 |
256 |
订单标题 |
Iphone6 16G |
| buyer_id |
String |
可选 |
28 |
买家的支付宝用户id，如果为空，会从传入了码值信息中获取买家ID |
2088202954065786 |
| seller_id |
String |
可选 |
28 |
如果该值为空，则默认为商户签约账号对应的支付宝用户ID |
2088102146225135 |
| total_amount |
Price |
可选 |
11 |
订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] |
88.88 |
| trans_currency |
String |
可选 |
8 |
标价币种, total_amount 对应的币种单位。支持英镑：GBP、港币：HKD、美元：USD、新加坡元：SGD、日元：JPY、加拿大元：CAD、澳元：AUD、欧元：EUR、新西兰元：NZD、韩元：KRW、泰铢：THB、瑞士法郎：CHF、瑞典克朗：SEK、丹麦克朗：DKK、挪威克朗：NOK、马来西亚林吉特：MYR、印尼卢比：IDR、菲律宾比索：PHP、毛里求斯卢比：MUR、以色列新谢克尔：ILS、斯里兰卡卢比：LKR、俄罗斯卢布：RUB、阿联酋迪拉姆：AED、捷克克朗：CZK、南非兰特：ZAR、人民币：CNY |
USD |
| settle_currency |
String |
可选 |
8 |
商户指定的结算币种，支持英镑：GBP、港币：HKD、美元：USD、新加坡元：SGD、日元：JPY、加拿大元：CAD、澳元：AUD、欧元：EUR、新西兰元：NZD、韩元：KRW、泰铢：THB、瑞士法郎：CHF、瑞典克朗：SEK、丹麦克朗：DKK、挪威克朗：NOK、马来西亚林吉特：MYR、印尼卢比：IDR、菲律宾比索：PHP、毛里求斯卢比：MUR、以色列新谢克尔：ILS、斯里兰卡卢比：LKR、俄罗斯卢布：RUB、阿联酋迪拉姆：AED、捷克克朗：CZK、南非兰特：ZAR、人民币：CNY |
USD |
| discountable_amount |
Price |
可选 |
11 |
参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]。 |
8.88 |
| body |
String |
可选 |
128 |
订单描述 |
Iphone6 16G |
| goods_detail |
GoodsDetail[] |
可选 |
|
订单包含的商品列表信息，json格式，其它说明详见商品明细说明 |
|
| operator_id |
String |
可选 |
28 |
商户操作员编号 |
yx_001 |
| store_id |
String |
可选 |
32 |
商户门店编号 |
NJ_001 |
| terminal_id |
String |
可选 |
32 |
商户机具终端编号 |
NJ_T_001 |
| extend_params |
ExtendParams |
可选 |
|
业务扩展参数 |
|
| timeout_express |
String |
可选 |
6 |
该笔订单允许的最晚付款时间，逾期将关闭交易。取值范围：1m～15d。m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。 该参数数值不接受小数点， 如 1.5h，可转换为 90m |
90m |
| auth_confirm_mode |
String |
可选 |
32 |
预授权确认模式，授权转交易请求中传入，适用于预授权转交易业务使用，目前只支持PRE_AUTH(预授权产品码) |
COMPLETE：转交易支付完成结束预授权;NOT_COMPLETE：转交易支付完成不结束预授权 |
| terminal_params |
String |
可选 |
2048 |
商户传入终端设备相关信息，具体值要和支付宝约定 |
{"key":"value"} |
公共响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| code |
String |
是 |
- |
网关返回码,详见文档 |
40004 |
| msg |
String |
是 |
- |
网关返回码描述,详见文档 |
Business Failed |
| sub_code |
String |
否 |
- |
业务返回码，参见具体的API接口文档 |
ACQ.TRADE_HAS_SUCCESS |
| sub_msg |
String |
否 |
- |
业务返回码描述，参见具体的API接口文档 |
交易已被支付 |
| sign |
String |
是 |
- |
签名,详见文档 |
DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo= |
响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| trade_no |
String |
必填 |
64 |
支付宝交易号 |
2013112011001004330000121536 |
| out_trade_no |
String |
必填 |
64 |
商户订单号 |
6823789339978248 |
| buyer_logon_id |
String |
必填 |
100 |
买家支付宝账号 |
159****5620 |
| total_amount |
Price |
必填 |
11 |
交易金额 |
120.88 |
| trans_currency |
String |
选填 |
5 |
标价币种, total_amount对应的币种单位。目前支持英镑：GBP、港币：HKD、美元：USD、新加坡元：SGD、日元：JPY、加拿大元：CAD、澳元：AUD、欧元：EUR、新西兰元：NZD、韩元：KRW、泰铢：THB、瑞士法郎：CHF、瑞典克朗：SEK、丹麦克朗：DKK、挪威克朗：NOK、马来西亚林吉特：MYR、印尼卢比：IDR、菲律宾比索：PHP、毛里求斯卢比：MUR、以色列新谢克尔：ILS、斯里兰卡卢比：LKR、俄罗斯卢布：RUB、阿联酋迪拉姆：AED、捷克克朗：CZK、南非兰特：ZAR、人民币：CNY |
USD |
| settle_currency |
String |
选填 |
8 |
商户指定的结算币种，目前支持英镑：GBP、港币：HKD、美元：USD、新加坡元：SGD、日元：JPY、加拿大元：CAD、澳元：AUD、欧元：EUR、新西兰元：NZD、韩元：KRW、泰铢：THB、瑞士法郎：CHF、瑞典克朗：SEK、丹麦克朗：DKK、挪威克朗：NOK、马来西亚林吉特：MYR、印尼卢比：IDR、菲律宾比索：PHP、毛里求斯卢比：MUR、以色列新谢克尔：ILS、斯里兰卡卢比：LKR、俄罗斯卢布：RUB、阿联酋迪拉姆：AED、捷克克朗：CZK、南非兰特：ZAR、人民币：CNY |
USD |
| settle_amount |
String |
选填 |
11 |
结算币种订单金额 |
88.88 |
| pay_currency |
String |
选填 |
8 |
支付币种 |
CNY |
| pay_amount |
String |
选填 |
11 |
支付币种订单金额 |
580.04 |
| settle_trans_rate |
String |
选填 |
32 |
结算币种兑换标价币种汇率 |
1 |
| trans_pay_rate |
String |
选填 |
32 |
标价币种兑换支付币种汇率 |
6.5261 |
| receipt_amount |
String |
必填 |
11 |
实收金额 |
88.88 |
| buyer_pay_amount |
Price |
选填 |
11 |
买家付款的金额 |
8.88 |
| point_amount |
Price |
选填 |
11 |
使用集分宝付款的金额 |
8.12 |
| invoice_amount |
Price |
选填 |
11 |
交易中可给用户开具发票的金额 |
12.50 |
| gmt_payment |
Date |
必填 |
32 |
交易支付时间 |
2014-11-27 15:45:57 |
| fund_bill_list |
TradeFundBill |
必填 |
|
交易支付使用的资金渠道 |
|
| card_balance |
Price |
选填 |
11 |
支付宝卡余额 |
98.23 |
| store_name |
String |
选填 |
512 |
发生支付交易的商户门店名称 |
证大五道口店 |
| buyer_user_id |
String |
必填 |
28 |
买家在支付宝的用户id |
2088101117955611 |
| discount_goods_detail |
String |
选填 |
1024 |
本次交易支付所使用的单品券优惠的商品优惠信息 |
[{"goods_id":"STANDARD1026181538","goods_name":"雪碧","discount_amount":"100.00","voucher_id":"2015102600073002039000002D5O"}] |
| voucher_detail_list |
VoucherDetail |
选填 |
|
本交易支付时使用的所有优惠券信息 |
|
| auth_trade_pay_mode |
String |
选填 |
64 |
预授权支付模式，该参数仅在信用预授权支付场景下返回。信用预授权支付：CREDIT_PREAUTH_PAY |
CREDIT_PREAUTH_PAY |
| business_params |
String |
选填 |
512 |
商户传入业务信息，具体值要和支付宝约定 |
{"data":"123"} |
| buyer_user_type |
String |
选填 |
18 |
买家用户类型。CORPORATE:企业用户；PRIVATE:个人用户。 |
PRIVATE |
| mdiscount_amount |
String |
选填 |
11 |
商家优惠金额 |
88.88 |
| discount_amount |
String |
选填 |
11 |
平台优惠金额 |
88.88 |
1.3.2 扫码支付接口
alipay.trade.precreate(统一收单线下交易预创建)
支持第三方代理调用
收银员通过收银台或商户后台调用支付宝接口，生成二维码后，展示给用户，由用户扫描二维码完成订单支付。
公共请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| app_id |
String |
是 |
32 |
支付宝分配给开发者的应用ID |
2014072300007148 |
| method |
String |
是 |
128 |
接口名称 |
alipay.trade.precreate |
| format |
String |
否 |
40 |
仅支持JSON |
JSON |
| charset |
String |
是 |
10 |
请求使用的编码格式，如utf-8,gbk,gb2312等 |
utf-8 |
| sign_type |
String |
是 |
10 |
商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 |
RSA2 |
| sign |
String |
是 |
344 |
商户请求参数的签名串，详见签名 |
详见示例 |
| timestamp |
String |
是 |
19 |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
2014-07-24 03:07:50 |
| version |
String |
是 |
3 |
调用的接口版本，固定为：1.0 |
1.0 |
| notify_url |
String |
否 |
256 |
支付宝服务器主动通知商户服务器里指定的页面http/https路径。 |
http://api.test.alipay.net/atinterface/receive_notify.htm |
| app_auth_token |
String |
否 |
40 |
详见应用授权概述 |
|
| biz_content |
String |
是 |
|
请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
|
请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| out_trade_no |
String |
必选 |
64 |
商户订单号,64个字符以内、只能包含字母、数字、下划线；需保证在商户端不重复 |
20150320010101001 |
| seller_id |
String |
可选 |
28 |
卖家支付宝用户ID。 如果该值为空，则默认为商户签约账号对应的支付宝用户ID |
2088102146225135 |
| total_amount |
Price |
必选 |
11 |
订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] 如果同时传入了【打折金额】，【不可打折金额】，【订单总金额】三者，则必须满足如下条件：【订单总金额】=【打折金额】+【不可打折金额】 |
88.88 |
| discountable_amount |
Price |
可选 |
11 |
可打折金额. 参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] 如果该值未传入，但传入了【订单总金额】，【不可打折金额】则该值默认为【订单总金额】-【不可打折金额】 |
8.88 |
| subject |
String |
必选 |
256 |
订单标题 |
Iphone6 16G |
| goods_detail |
GoodsDetail[] |
可选 |
|
订单包含的商品列表信息.Json格式. 其它说明详见：“商品明细说明” |
|
| body |
String |
可选 |
128 |
对交易或商品的描述 |
Iphone6 16G |
| operator_id |
String |
可选 |
28 |
商户操作员编号 |
yx_001 |
| store_id |
String |
可选 |
32 |
商户门店编号 |
NJ_001 |
| disable_pay_channels |
String |
可选 |
128 |
禁用渠道，用户不可用指定渠道支付 |
pcredit,moneyFund,debitCardExpress |
| enable_pay_channels |
String |
可选 |
128 |
可用渠道，用户只能在指定渠道范围内支付 |
pcredit,moneyFund,debitCardExpress |
| terminal_id |
String |
可选 |
32 |
商户机具终端编号 |
NJ_T_001 |
| extend_params |
ExtendParams |
可选 |
|
业务扩展参数 |
|
| timeout_express |
String |
可选 |
6 |
该笔订单允许的最晚付款时间，逾期将关闭交易。取值范围：1m～15d。m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。 该参数数值不接受小数点， 如 1.5h，可转换为 90m。 |
90m |
| business_params |
String |
可选 |
512 |
商户传入业务信息，具体值要和支付宝约定，应用于安全，营销等参数直传场景，格式为json格式 |
{"data":"123"} |
公共响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| code |
String |
是 |
- |
网关返回码,详见文档 |
40004 |
| msg |
String |
是 |
- |
网关返回码描述,详见文档 |
Business Failed |
| sub_code |
String |
否 |
- |
业务返回码，参见具体的API接口文档 |
ACQ.TRADE_HAS_SUCCESS |
| sub_msg |
String |
否 |
- |
业务返回码描述，参见具体的API接口文档 |
交易已被支付 |
| sign |
String |
是 |
- |
签名,详见文档 |
DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo= |
响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| out_trade_no |
String |
必填 |
64 |
商户的订单号 |
6823789339978248 |
| qr_code |
String |
必填 |
1024 |
当前预下单请求生成的二维码码串，可以用二维码生成工具根据该码串值生成对应的二维码 |
https://qr.alipay.com/bavh4wjlxf12tper3a |
1.3.3 退款接口
alipay.trade.refund(统一收单交易退款接口)
支持第三方代理调用
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。 交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款 支付宝退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。一笔退款失败后重新提交，要采用原来的退款单号。总退款金额不能超过用户实际支付金额
公共请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| app_id |
String |
是 |
32 |
支付宝分配给开发者的应用ID |
2014072300007148 |
| method |
String |
是 |
128 |
接口名称 |
alipay.trade.refund |
| format |
String |
否 |
40 |
仅支持JSON |
JSON |
| charset |
String |
是 |
10 |
请求使用的编码格式，如utf-8,gbk,gb2312等 |
utf-8 |
| sign_type |
String |
是 |
10 |
商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 |
RSA2 |
| sign |
String |
是 |
344 |
商户请求参数的签名串，详见签名 |
详见示例 |
| timestamp |
String |
是 |
19 |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
2014-07-24 03:07:50 |
| version |
String |
是 |
3 |
调用的接口版本，固定为：1.0 |
1.0 |
| app_auth_token |
String |
否 |
40 |
详见应用授权概述 |
|
| biz_content |
String |
是 |
|
请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
|
请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| out_trade_no |
String |
特殊可选 |
64 |
订单支付时传入的商户订单号,不能和 trade_no同时为空。 |
20150320010101001 |
| trade_no |
String |
特殊可选 |
64 |
支付宝交易号，和商户订单号不能同时为空 |
2014112611001004680073956707 |
| refund_amount |
Price |
必选 |
9 |
需要退款的金额，该金额不能大于订单金额,单位为元，支持两位小数 |
200.12 |
| refund_currency |
String |
可选 |
8 |
订单退款币种信息，非外币交易，不能传入退款币种信息 |
USD |
| refund_reason |
String |
可选 |
256 |
退款的原因说明 |
正常退款 |
| out_request_no |
String |
可选 |
64 |
标识一次退款请求，同一笔交易多次退款需要保证唯一，如需部分退款，则此参数必传。 |
HZ01RF001 |
| operator_id |
String |
可选 |
30 |
商户的操作员编号 |
OP001 |
| store_id |
String |
可选 |
32 |
商户的门店编号 |
NJ_S_001 |
| terminal_id |
String |
可选 |
32 |
商户的终端编号 |
NJ_T_001 |
| goods_detail |
GoodsDetail[] |
可选 |
|
退款包含的商品列表信息，Json格式。 |
|
公共响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| code |
String |
是 |
- |
网关返回码,详见文档 |
40004 |
| msg |
String |
是 |
- |
网关返回码描述,详见文档 |
Business Failed |
| sub_code |
String |
否 |
- |
业务返回码，参见具体的API接口文档 |
ACQ.TRADE_HAS_SUCCESS |
| sub_msg |
String |
否 |
- |
业务返回码描述，参见具体的API接口文档 |
交易已被支付 |
| sign |
String |
是 |
- |
签名,详见文档 |
DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo= |
响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| trade_no |
String |
必填 |
64 |
2013112011001004330000121536 |
支付宝交易号 |
| out_trade_no |
String |
必填 |
64 |
商户订单号 |
6823789339978248 |
| buyer_logon_id |
String |
必填 |
100 |
用户的登录id |
159****5620 |
| fund_change |
String |
必填 |
1 |
本次退款是否发生了资金变化 |
Y |
| refund_fee |
Price |
必填 |
11 |
退款总金额 |
88.88 |
| refund_currency |
String |
选填 |
8 |
退款币种信息 |
USD |
| gmt_refund_pay |
Date |
必填 |
32 |
退款支付时间 |
2014-11-27 15:45:57 |
| refund_detail_item_list |
TradeFundBill |
选填 |
|
退款使用的资金渠道 |
|
| store_name |
String |
选填 |
512 |
交易在支付时候的门店名称 |
望湘园联洋店 |
| buyer_user_id |
String |
必填 |
28 |
买家在支付宝的用户id |
2088101117955611 |
| present_refund_buyer_amount |
String |
选填 |
11 |
本次退款金额中买家退款金额 |
88.88 |
| present_refund_discount_amount |
String |
选填 |
11 |
本次退款金额中平台优惠退款金额 |
88.88 |
| present_refund_mdiscount_amount |
String |
选填 |
11 |
本次退款金额中商家优惠退款金额 |
88.88 |
1.3.4 对账单获取接口
alipay.data.dataservice.bill.downloadurl.query(查询对账单下载地址)
支持第三方代理调用
为方便商户快速查账，支持商户通过本接口获取商户离线账单下载地址
公共请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| app_id |
String |
是 |
32 |
支付宝分配给开发者的应用ID |
2014072300007148 |
| method |
String |
是 |
128 |
接口名称 |
alipay.data.dataservice.bill.downloadurl.query |
| format |
String |
否 |
40 |
仅支持JSON |
JSON |
| charset |
String |
是 |
10 |
请求使用的编码格式，如utf-8,gbk,gb2312等 |
utf-8 |
| sign_type |
String |
是 |
10 |
商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 |
RSA2 |
| sign |
String |
是 |
344 |
商户请求参数的签名串，详见签名 |
详见示例 |
| timestamp |
String |
是 |
19 |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
2014-07-24 03:07:50 |
| version |
String |
是 |
3 |
调用的接口版本，固定为：1.0 |
1.0 |
| app_auth_token |
String |
否 |
40 |
详见应用授权概述 |
|
| biz_content |
String |
是 |
|
请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
|
请求参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| bill_type |
String |
必选 |
10 |
账单类型，商户通过接口或商户经开放平台授权后其所属服务商通过接口可以获取以下账单类型：trade、signcustomer；trade指商户基于支付宝交易收单的业务账单；signcustomer是指基于商户支付宝余额收入及支出等资金变动的帐务账单； |
trade |
| bill_date |
String |
必选 |
15 |
账单时间：日账单格式为yyyy-MM-dd，月账单格式为yyyy-MM。 |
2016-04-05 |
公共响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| code |
String |
是 |
- |
网关返回码,详见文档 |
40004 |
| msg |
String |
是 |
- |
网关返回码描述,详见文档 |
Business Failed |
| sub_code |
String |
否 |
- |
业务返回码，参见具体的API接口文档 |
ACQ.TRADE_HAS_SUCCESS |
| sub_msg |
String |
否 |
- |
业务返回码描述，参见具体的API接口文档 |
交易已被支付 |
| sign |
String |
是 |
- |
签名,详见文档 |
DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo= |
响应参数
| 参数 |
类型 |
是否必填 |
最大长度 |
描述 |
示例值 |
| bill_download_url |
String |
必填 |
2048 |
账单下载地址链接，获取连接后30秒后未下载，链接地址失效。 |
http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&userId=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X |
二、微信扫码支付
2.1 系统流程说明
2.1.1 条码支付（被扫）
步骤1：用户选择刷卡支付付款并打开微信，进入“我”->“钱包”->“收付款”条码界面；
步骤2：收银员在商户系统操作生成支付订单，用户确认支付金额；
步骤3：商户收银员用扫码设备扫描用户的条码/二维码，商户收银系统提交支付；
步骤4：微信支付后台系统收到支付请求，根据验证密码规则判断是否验证用户的支付密码，不需要验证密码的交易直接发起扣款，需要验证密码的交易会弹出密码输入框。支付成功后微信端会弹出成功页面，支付失败会弹出错误提示。
（注：用户刷卡条形码规则：18位纯数字，以10、11、12、13、14、15开头）
|
我的钱包 |
刷卡支付界面 |
|
输入密码，确认支付 |
支付成功后页面提示 |
根据商户具体的情况，刷卡支付接入模式可分为：商户后台接入和门店接入；
根据用户是否需要输入支付密码可分为：免密模式和验密模式。
1、接入模式-商户后台接入
该模式适合具备统一后台系统的商户。门店收银台与商户后台通信，商户后台系统负责与微信支付系统发送交易请求和接收返回结果。
图5.4 商户后台接入刷卡支付
2、接入模式-门店接入
该模式适合门店收银台通过公网直接与微信后台通信的商户。门店收银台直接发起交易请求和处理返回结果。商户可以根据实际需要，处理门店和商户后台系统之间的其它业务流程。
图5.5 门店接入刷卡支付
3、免密支付流程
本节以商户后台接入模式说明支付流程，请参看以下时序图：
图5.6 刷卡支付免密流程时序图
流程详细说明：
（1）收银员在商户收银台生成支付订单，向用户展示支付金额；
（2）用户打开微信客户端，点击“我的钱包”，选择“刷卡”，进入条码界面；
（3）使用扫码设备读取用户手机屏幕上的条码；
（4）扫码设备将读取的信息上传给门店收银台；
（5）门店收银台得到支付信息后，向商户收银后台发起支付请求。
（6）商户后台对门店收银台的支付请求进行处理，生成签名后调用【提交刷卡支付API】向微信支付系统发起支付请求。
（7）微信支付系统得到商户侧的支付请求之后会对请求进行验证，验证通过之后会对请求数据进行处理，最后将处理后的支付结果返回给商户收银后台。如果支付成功，微信支付系统会将支付结果返回给商户，同时把支付结果通知给用户（以短信、微信消息的形式通知）。
（8）商户收银后台对得到的支付结果进行签名验证和处理，再将支付结果返回给门店收银台。
（9）收银员看到门店收银台的支付结果后给用户发货。
4、验密支付流程
场景交互与免密模式相同，不同的是在商户调用【提交刷卡支付API】发起支付请求之后，微信支付后台提示用户输入密码确认支付，接口同步返回USERPAYING状态，商户系统再轮询调用查询订单接口来确认当前用户是否已经支付成功。
以下时序图说明验密支付流程：
图5.7 刷卡支付验证密码流程时序图
由于在商户收银后台向微信支付系统发起支付请求之前的流程是完全一样的，所以这里只介绍商户发起支付请求之后的逻辑。
（1）商户门店生成订单后，收银台向后台系统发起支付请求。
（2）后台调用微信支付【提交刷卡支付API】生成支付交易。
（3）微信支付系统对商户请求进行验证，验证通过后判断当前用户需要输入密码。
（4）微信支付系统返回USERPAYING状态，商户后台系统将应答结果返回给商户门店收银台。
（5)微信支付系统通知用户微信客户端输入密码。
（6）用户得到输入密码提示后，确认支付并输入密码。
（7）完成密码输入，提交微信支付。
（8）微信客户端在用户完成支付后提示微信支付后台系统返回的支付结果，而且微信支付系统会通过短信、微信消息给用户发送支付结果提醒。
（9）商户收银台得到USERPAYING状态后，经过商户后台系统调用【查询订单API】查询实际支付结果。
（10）如果支付结果仍为USERPAYING，则每隔5秒循环调用【查询订单API】判断实际支付结果，如果用户取消支付或累计30秒用户都未支付，商户收银台退出查询流程后继续调用【撤销订单API】撤销支付交易。
5、异常处理
用户遇到支付异常，请按如下说明处理
（1）用户微信端弹出系统错误提示框，用户可在交易列表查看交易情况，如果未找到订单，需要商户重新发起支付交易；如果订单显示成功支付，商户收银系统再次调用【查询订单API】查询实际支付结果；
（2）用户微信端弹出支付失败提示，例如：余额不足，信用卡失效。需要重新发起支付；
（3）当交易超时或支付交易失败，商户收银系统必须调用【撤销订单API】，撤销此交易。
（4）由于银行系统异常、用户余额不足、不支持用户卡种等原因使当前支付交易失败，商户收银系统应该把错误提示明确展示给收银员。
（5）根据返回的错误码，判断是否需要撤销交易，具体详见API返回错误码列表。
2.1.2 扫码支付（主扫）
场景介绍
用户扫描商户展示在各种场景的二维码进行支付。
步骤1：商户根据微信支付的规则，为不同商品生成不同的二维码（如图6.1），展示在各种场景，用于用户扫描购买。
步骤2：用户使用微信“扫一扫”（如图6.2）扫描二维码后，获取商品支付信息，引导用户完成支付（如图6.3）。
|
图6.1 支付二维码 |
图6.2 打开微信扫一扫二维码 |
图6.3 确认支付页面 |
步骤（3）：用户确认支付，输入支付密码（如图6.4）。
步骤（4）：支付完成后会提示用户支付成功（如图6.5），商户后台得到支付成功的通知，然后进行发货处理。
|
图6.4 用户确认支付，输入密码 |
图6.5 支付成功提示 |
商户后台系统先调用微信支付的统一下单接口，微信后台系统返回链接参数code_url，商户后台系统将code_url值生成二维码图片，用户使用微信客户端扫码后发起支付。注意：code_url有效期为2小时，过期后扫码不能再发起支付。
业务流程时序图
图6.9 原生支付模式二时序图
业务流程说明：
（1）商户后台系统根据用户选购的商品生成订单。
（2）用户确认支付后调用微信支付【统一下单API】生成预支付交易；
（3）微信支付系统收到请求后生成预支付交易单，并返回交易会话的二维码链接code_url。
（4）商户后台系统根据返回的code_url生成二维码。
（5）用户打开微信“扫一扫”扫描二维码，微信客户端将扫码内容发送到微信支付系统。
（6）微信支付系统收到客户端请求，验证链接有效性后发起用户支付，要求用户授权。
（7）用户在微信客户端输入密码，确认支付后，微信客户端提交授权。
（8）微信支付系统根据用户授权完成支付交易。
（9）微信支付系统完成支付交易后给微信客户端返回交易结果，并将交易结果通过短信、微信消息提示用户。微信客户端展示支付交易结果页面。
（10）微信支付系统通过发送异步消息通知商户后台系统支付结果。商户后台系统需回复接收情况，通知微信后台系统不再发送该单的支付通知。
（11）未收到支付通知的情况，商户后台系统调用【查询订单API】。
（12）商户确认订单已支付后给用户发货。
生成二维码规则
对应链接格式：weixin：//wxpay/bizpayurl?sr=XXXXX。请商户调用第三方库将code_url生成二维码图片。该模式链接较短，生成的二维码打印到结账小票上的识别率较高。
例如，将weixin：//wxpay/s/An4baqw生成二维码见图6.10。
图6.10 原生支付“模式二”二维码示例
二维码相关知识
二维码背景知识介绍：
http://www.thonky.com/qr-code-tutorial/
http://coolshell.cn/articles/10590.html
2.1.3 退款说明
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。
注意：
1、交易时间超过一年的订单无法提交退款
2、微信支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号
3、请求频率限制：150qps，即每秒钟正常的申请退款请求次数不超过150次
错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款申请请求不超过6次
4、每个支付订单的部分退款次数不能超过50次
2.1.4 对账说明
商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致，通过对账单核对后可校正支付状态。
注意：
1、微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中，跟原支付单订单号一致；
2、微信在次日9点启动生成前一天的对账单，建议商户10点后再获取；
3、对账单中涉及金额的字段单位为“元”。
4、对账单接口只能下载三个月以内的账单。
2.2 申请要素
2.2.1 申请材料
| 信息项 |
备注 |
| 企业名称 |
需与当地政府颁发的商业许可证书或企业注册证上的企业名称完全一致，信息审核审核成功后，企业名称不可修改。 |
| 营业执照注册号 |
15位营业执照注册号或18位的统一社会信用代码。 |
| 自动对公打款验证 |
户名 |
| 对公账户 |
|
| 开户银行 |
|
| 开户省市 |
|
| 运营者身份证姓名 |
|
| 运营者身份证号码 |
|
| 运营者手机号码 |
|
| 运营者身份证照片 |
彩色照片正反面 |
| 医疗机构执业许可证 |
彩色照片 |
| 事业单位法人证书 |
彩色照片 |
2.2.2 上线配置参数
1. 微信公众号应用ID：AppID
2. 微信公众号应用密钥：AppSecret
3. 微信支付商户号
4. 微信支付密钥
5. 微信支付https安全证书（apiclient_cert.p12文件）
2.3 调用接口
2.3.1 条码支付接口
收银员使用扫码设备读取微信用户刷卡授权码以后，二维码或条码信息传送至商户收银台，由商户收银台或者商户后台调用该接口发起支付。
提醒1：提交支付请求后微信会同步返回支付结果。当返回结果为“系统错误”时，商户系统等待5秒后调用【查询订单API】，查询支付实际交易结果；当返回结果为“USERPAYING”时，商户系统可设置间隔时间(建议10秒)重新查询支付结果，直到支付成功或超时(建议30秒)；
提醒2：在调用查询接口返回后，如果交易状况不明晰，请调用【撤销订单API】，此时如果交易失败则关闭订单，该单不能再支付成功；如果交易成功，则将扣款退回到用户账户。当撤销无返回或错误时，请再次调用。注意：请勿扣款后立即调用【撤销订单API】,建议至少15秒后再调用。撤销订单API需要双向证书。
接口地址【SDK下载】：https://api.mch.weixin.qq.com/pay/micropay
是否需要证书：不需要。
输入参数
| 名称 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wx8888888888888888 |
微信分配的公众账号ID（企业号corpid即为此appId） |
| 商户号 |
mch_id |
是 |
String(32) |
1900000109 |
微信支付分配的商户号 |
| 设备号 |
device_info |
否 |
String(32) |
013467007045764 |
终端设备号(商户自定义，如门店编号) |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
随机字符串，不长于32位。推荐随机数生成算法 |
| 签名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
签名，详见签名生成算法 |
| 签名类型 |
sign_type |
否 |
String(32) |
HMAC-SHA256 |
签名类型，目前支持HMAC-SHA256和MD5，默认为MD5 |
| 商品描述 |
body |
是 |
String(128) |
image形象店-深圳腾大- QQ公仔 |
商品简单描述，该字段须严格按照规范传递，具体请见参数规定 |
| 商品详情 |
detail |
否 |
String(6000) |
|
单品优惠功能字段，需要接入详见单品优惠详细说明 |
| 附加数据 |
attach |
否 |
String(127) |
说明 |
附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据 |
| 商户订单号 |
out_trade_no |
是 |
String(32) |
1217752501201407033233368018 |
商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|*且在同一个商户号下唯一。详见商户订单号 |
| 订单金额 |
total_fee |
是 |
Int |
888 |
订单总金额，单位为分，只能为整数，详见支付金额 |
| 货币类型 |
fee_type |
否 |
String(16) |
CNY |
符合ISO4217标准的三位字母代码，默认人民币：CNY，详见货币类型 |
| 终端IP |
spbill_create_ip |
是 |
String(16) |
8.8.8.8 |
调用微信支付API的机器IP |
| 订单优惠标记 |
goods_tag |
否 |
String(32) |
1234 |
订单优惠标记，代金券或立减优惠功能的参数，详见代金券或立减优惠 |
| 指定支付方式 |
limit_pay |
否 |
String(32) |
no_credit |
no_credit--指定不能使用信用卡支付 |
| 交易起始时间 |
time_start |
否 |
String(14) |
20091225091010 |
订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则 |
| 交易结束时间 |
time_expire |
否 |
String(14) |
20091227091010 |
订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。注意：最短失效时间间隔需大于1分钟 |
| 授权码 |
auth_code |
是 |
String(128) |
120061098828009406 |
扫码支付授权码，设备读取用户微信中的条码或者二维码信息 |
| +场景信息 |
scene_info |
否 |
String(256) |
{"store_info" : { |
该字段用于上报场景信息，目前支持上报实际门店信息。该字段为JSON对象数据，对象格式为{"store_info":{"id": "门店ID","name": "名称","area_code": "编码","address": "地址" }} ，字段详细说明请点击行前的+展开 |
举例如下：
刷卡支付测试
注：参数值用XML转义即可，CDATA标签用于说明数据不被XML解析器解析。
返回结果
| 名称 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 返回状态码 |
return_code |
是 |
String(16) |
SUCCESS |
SUCCESS/FAIL |
| 返回信息 |
return_msg |
否 |
String(128) |
签名失败 |
返回信息，如非空，为错误原因 |
当return_code为SUCCESS的时候，还会包括以下字段：
| 名称 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wx8888888888888888 |
调用接口提交的公众账号ID |
| 商户号 |
mch_id |
是 |
String(32) |
1900000109 |
调用接口提交的商户号 |
| 设备号 |
device_info |
否 |
String(32) |
013467007045764 |
调用接口提交的终端设备号， |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
微信返回的随机字符串 |
| 签名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
微信返回的签名，详见签名生成算法 |
| 业务结果 |
result_code |
是 |
String(16) |
SUCCESS |
SUCCESS/FAIL |
| 错误代码 |
err_code |
否 |
String(32) |
SYSTEMERROR |
详细参见错误列表 |
| 错误代码描述 |
err_code_des |
否 |
String(128) |
系统错误 |
错误返回的信息描述 |
当return_code 和result_code都为SUCCESS的时，还会包括以下字段：
| 名称 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 用户标识 |
openid |
是 |
String(128) |
Y |
用户在商户appid 下的唯一标识 |
| 是否关注公众账号 |
is_subscribe |
是 |
String(1) |
Y |
用户是否关注公众账号，仅在公众账号类型支付有效，取值范围：Y或N;Y-关注;N-未关注 |
| 交易类型 |
trade_type |
是 |
String(16) |
MICROPAY |
MICROPAY 刷卡支付 |
| 付款银行 |
bank_type |
是 |
String(32) |
CMC |
银行类型，采用字符串类型的银行标识，详见银行类型 |
| 货币类型 |
fee_type |
否 |
String(16) |
CNY |
符合ISO 4217标准的三位字母代码，默认人民币：CNY，详见货币类型 |
| 订单金额 |
total_fee |
是 |
Int |
888 |
订单总金额，单位为分，只能为整数，详见支付金额 |
| 应结订单金额 |
settlement_total_fee |
否 |
Int |
100 |
当订单使用了免充值型优惠券后返回该参数，应结订单金额=订单金额-免充值优惠券金额。 |
| 代金券金额 |
coupon_fee |
否 |
Int |
100 |
“代金券”金额<=订单金额，订单金额-“代金券”金额=现金支付金额，详见支付金额 |
| 现金支付货币类型 |
cash_fee_type |
否 |
String(16) |
CNY |
符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见货币类型 |
| 现金支付金额 |
cash_fee |
是 |
Int |
100 |
订单现金支付金额，详见支付金额 |
| 微信支付订单号 |
transaction_id |
是 |
String(32) |
1217752501201407033233368018 |
微信支付订单号 |
| 商户订单号 |
out_trade_no |
是 |
String(32) |
1217752501201407033233368018 |
商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|*且在同一个商户号下唯一。 |
| 商家数据包 |
attach |
否 |
String(128) |
123456 |
商家数据包，原样返回 |
| 支付完成时间 |
time_end |
是 |
String(14) |
20141030133525 |
订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。详见时间规则 |
| 营销详情 |
promotion_detail |
否 |
String(6000) |
示例见下文 |
新增返回，单品优惠功能字段，需要接入请见详细说明 |
举例如下：
错误码
注意：如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支付；如果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态，如果长时间（建议30秒）都得不到明确状态请调用撤销订单接口。
| 名称 |
描述 |
支付状态 |
原因 |
解决方案 |
| SYSTEMERROR |
接口返回错误 |
支付结果未知 |
系统超时 |
请立即调用被扫订单结果查询API，查询当前订单状态，并根据订单的状态决定下一步的操作。 |
| PARAM_ERROR |
参数错误 |
支付确认失败 |
请求参数未按指引进行填写 |
请根据接口返回的详细信息检查您的程序 |
| ORDERPAID |
订单已支付 |
支付确认失败 |
订单号重复 |
请确认该订单号是否重复支付，如果是新单，请使用新订单号提交 |
| NOAUTH |
商户无权限 |
支付确认失败 |
商户没有开通被扫支付权限 |
请开通商户号权限。请联系产品或商务申请 |
| AUTHCODEEXPIRE |
二维码已过期，请用户在微信上刷新后再试 |
支付确认失败 |
用户的条码已经过期 |
请收银员提示用户，请用户在微信上刷新条码，然后请收银员重新扫码。 直接将错误展示给收银员 |
| NOTENOUGH |
余额不足 |
支付确认失败 |
用户的零钱余额不足 |
请收银员提示用户更换当前支付的卡，然后请收银员重新扫码。建议：商户系统返回给收银台的提示为“用户余额不足.提示用户换卡支付” |
| NOTSUPORTCARD |
不支持卡类型 |
支付确认失败 |
用户使用卡种不支持当前支付形式 |
请用户重新选择卡种 建议：商户系统返回给收银台的提示为“该卡不支持当前支付，提示用户换卡支付或绑新卡支付” |
| ORDERCLOSED |
订单已关闭 |
支付确认失败 |
该订单已关 |
商户订单号异常，请重新下单支付 |
| ORDERREVERSED |
订单已撤销 |
支付确认失败 |
当前订单已经被撤销 |
当前订单状态为“订单已撤销”，请提示用户重新支付 |
| BANKERROR |
银行系统异常 |
支付结果未知 |
银行端超时 |
请立即调用被扫订单结果查询API，查询当前订单的不同状态，决定下一步的操作。 |
| USERPAYING |
用户支付中，需要输入密码 |
支付结果未知 |
该笔交易因为业务规则要求，需要用户输入支付密码。 |
等待5秒，然后调用被扫订单结果查询API，查询当前订单的不同状态，决定下一步的操作。 |
| AUTH_CODE_ERROR |
授权码参数错误 |
支付确认失败 |
请求参数未按指引进行填写 |
每个二维码仅限使用一次，请刷新再试 |
| AUTH_CODE_INVALID |
授权码检验错误 |
支付确认失败 |
收银员扫描的不是微信支付的条码 |
请扫描微信支付被扫条码/二维码 |
| XML_FORMAT_ERROR |
XML格式错误 |
支付确认失败 |
XML格式错误 |
请检查XML参数格式是否正确 |
| REQUIRE_POST_METHOD |
请使用post方法 |
支付确认失败 |
未使用post传递参数 |
请检查请求参数是否通过post方法提交 |
| SIGNERROR |
签名错误 |
支付确认失败 |
参数签名结果不正确 |
请检查签名参数和方法是否都符合签名算法要求 |
| LACK_PARAMS |
缺少参数 |
支付确认失败 |
缺少必要的请求参数 |
请检查参数是否齐全 |
| NOT_UTF8 |
编码格式错误 |
支付确认失败 |
未使用指定编码格式 |
请使用UTF-8编码格式 |
| BUYER_MISMATCH |
支付帐号错误 |
支付确认失败 |
暂不支持同一笔订单更换支付方 |
请确认支付方是否相同 |
| APPID_NOT_EXIST |
APPID不存在 |
支付确认失败 |
参数中缺少APPID |
请检查APPID是否正确 |
| MCHID_NOT_EXIST |
MCHID不存在 |
支付确认失败 |
参数中缺少MCHID |
请检查MCHID是否正确 |
| OUT_TRADE_NO_USED |
商户订单号重复 |
支付确认失败 |
同一笔交易不能多次提交 |
请核实商户订单号是否重复提交 |
| APPID_MCHID_NOT_MATCH |
appid和mch_id不匹配 |
支付确认失败 |
appid和mch_id不匹配 |
请确认appid和mch_id是否匹配 |
| INVALID_REQUEST |
无效请求 |
支付确认失败 |
商户系统异常导致，商户权限异常、重复请求支付、证书错误、频率限制等 |
请确认商户系统是否正常，是否具有相应支付权限，确认证书是否正确，控制频率 |
| TRADE_ERROR |
交易错误 |
支付确认失败 |
业务错误导致交易失败、用户账号异常、风控、规则限制等 |
请确认帐号是否存在异常 |
2.3.2 扫码支付接口
除被扫支付场景以外，商户系统先调用该接口在微信支付服务后台生成预支付交易单，返回正确的预支付交易会话标识后再按扫码、JSAPI、APP等不同场景生成交易串调起支付。
接口链接-URL地址：https://api.mch.weixin.qq.com/pay/unifiedorder
是否需要证书:否
请求参数
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wxd678efh567hg6787 |
微信支付分配的公众账号ID（企业号corpid即为此appId） |
| 商户号 |
mch_id |
是 |
String(32) |
1230000109 |
微信支付分配的商户号 |
| 设备号 |
device_info |
否 |
String(32) |
013467007045764 |
自定义参数，可以为终端设备号(门店号或收银设备ID)，PC网页或公众号内支付可以传"WEB" |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
随机字符串，长度要求在32位以内。推荐随机数生成算法 |
| 签名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
通过签名算法计算得出的签名值，详见签名生成算法 |
| 签名类型 |
sign_type |
否 |
String(32) |
MD5 |
签名类型，默认为MD5，支持HMAC-SHA256和MD5。 |
| 商品描述 |
body |
是 |
String(128) |
腾讯充值中心-QQ会员充值 |
商品简单描述，该字段请按照规范传递，具体请见参数规定 |
| 商品详情 |
detail |
否 |
String(6000) |
|
商品详细描述，对于使用单品优惠的商户，改字段必须按照规范上传，详见“单品优惠参数说明” |
| 附加数据 |
attach |
否 |
String(127) |
深圳分店 |
附加数据，在查询API和支付通知中原样返回，可作为自定义参数使用。 |
| 商户订单号 |
out_trade_no |
是 |
String(32) |
20150806125346 |
商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|* 且在同一个商户号下唯一。详见商户订单号 |
| 标价币种 |
fee_type |
否 |
String(16) |
CNY |
符合ISO 4217标准的三位字母代码，默认人民币：CNY，详细列表请参见货币类型 |
| 标价金额 |
total_fee |
是 |
Int |
88 |
订单总金额，单位为分，详见支付金额 |
| 终端IP |
spbill_create_ip |
是 |
String(16) |
123.12.12.123 |
APP和网页支付提交用户端ip，Native支付填调用微信支付API的机器IP。 |
| 交易起始时间 |
time_start |
否 |
String(14) |
20091225091010 |
订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则 |
| 交易结束时间 |
time_expire |
否 |
String(14) |
20091227091010 |
订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。订单失效时间是针对订单号而言的，由于在请求支付的时候有一个必传参数prepay_id只有两小时的有效期，所以在重入时间超过2小时的时候需要重新请求下单接口获取新的prepay_id。其他详见时间规则 建议：最短失效时间间隔大于1分钟 |
| 订单优惠标记 |
goods_tag |
否 |
String(32) |
WXG |
订单优惠标记，使用代金券或立减优惠功能时需要的参数，说明详见代金券或立减优惠 |
| 通知地址 |
notify_url |
是 |
String(256) |
http://www.weixin.qq.com/wxpay/pay.php |
异步接收微信支付结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。 |
| 交易类型 |
trade_type |
是 |
String(16) |
JSAPI |
JSAPI 公众号支付 NATIVE 扫码支付 APP APP支付 说明详见参数规定 |
| 商品ID |
product_id |
否 |
String(32) |
12235413214070356458058 |
trade_type=NATIVE时（即扫码支付），此参数必传。此参数为二维码中包含的商品ID，商户自行定义。 |
| 指定支付方式 |
limit_pay |
否 |
String(32) |
no_credit |
上传此参数no_credit--可限制用户不能使用信用卡支付 |
| 用户标识 |
openid |
否 |
String(128) |
oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
trade_type=JSAPI时（即公众号支付），此参数必传，此参数为微信用户在商户对应appid下的唯一标识。openid如何获取，可参考【获取openid】。企业号请使用【企业号OAuth2.0接口】获取企业号内成员userid，再调用【企业号userid转openid接口】进行转换 |
| +场景信息 |
scene_info |
否 |
String(256) |
{"store_info" : { |
该字段用于上报场景信息，目前支持上报实际门店信息。该字段为JSON对象数据，对象格式为{"store_info":{"id": "门店ID","name": "名称","area_code": "编码","address": "地址" }} ，字段详细说明请点击行前的+展开 |
举例如下：
JSAPI支付测试
注：参数值用XML转义即可，CDATA标签用于说明数据不被XML解析器解析。
返回结果
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 返回状态码 |
return_code |
是 |
String(16) |
SUCCESS |
SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断 |
| 返回信息 |
return_msg |
否 |
String(128) |
签名失败 |
返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
以下字段在return_code为SUCCESS的时候有返回
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wx8888888888888888 |
调用接口提交的公众账号ID |
| 商户号 |
mch_id |
是 |
String(32) |
1900000109 |
调用接口提交的商户号 |
| 设备号 |
device_info |
否 |
String(32) |
013467007045764 |
自定义参数，可以为请求支付的终端设备号等 |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
微信返回的随机字符串 |
| 签名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
微信返回的签名值，详见签名算法 |
| 业务结果 |
result_code |
是 |
String(16) |
SUCCESS |
SUCCESS/FAIL |
| 错误代码 |
err_code |
否 |
String(32) |
SYSTEMERROR |
详细参见下文错误列表 |
| 错误代码描述 |
err_code_des |
否 |
String(128) |
系统错误 |
错误信息描述 |
以下字段在return_code 和result_code都为SUCCESS的时候有返回
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 交易类型 |
trade_type |
是 |
String(16) |
JSAPI |
JSAPI 公众号支付 NATIVE 扫码支付 APP APP支付 说明详见参数规定 |
| 预支付交易会话标识 |
prepay_id |
是 |
String(64) |
wx201410272009395522657a690389285100 |
微信生成的预支付会话标识，用于后续接口调用中使用，该值有效期为2小时 |
| 二维码链接 |
code_url |
否 |
String(64) |
URl：weixin：//wxpay/s/An4baqw |
trade_type为NATIVE时有返回，用于生成二维码，展示给用户进行扫码支付 |
举例如下：
错误码
| 名称 |
描述 |
原因 |
解决方案 |
| NOAUTH |
商户无此接口权限 |
商户未开通此接口权限 |
请商户前往申请此接口权限 |
| NOTENOUGH |
余额不足 |
用户帐号余额不足 |
用户帐号余额不足，请用户充值或更换支付卡后再支付 |
| ORDERPAID |
商户订单已支付 |
商户订单已支付，无需重复操作 |
商户订单已支付，无需更多操作 |
| ORDERCLOSED |
订单已关闭 |
当前订单已关闭，无法支付 |
当前订单已关闭，请重新下单 |
| SYSTEMERROR |
系统错误 |
系统超时 |
系统异常，请用相同参数重新调用 |
| APPID_NOT_EXIST |
APPID不存在 |
参数中缺少APPID |
请检查APPID是否正确 |
| MCHID_NOT_EXIST |
MCHID不存在 |
参数中缺少MCHID |
请检查MCHID是否正确 |
| APPID_MCHID_NOT_MATCH |
appid和mch_id不匹配 |
appid和mch_id不匹配 |
请确认appid和mch_id是否匹配 |
| LACK_PARAMS |
缺少参数 |
缺少必要的请求参数 |
请检查参数是否齐全 |
| OUT_TRADE_NO_USED |
商户订单号重复 |
同一笔交易不能多次提交 |
请核实商户订单号是否重复提交 |
| SIGNERROR |
签名错误 |
参数签名结果不正确 |
请检查签名参数和方法是否都符合签名算法要求 |
| XML_FORMAT_ERROR |
XML格式错误 |
XML格式错误 |
请检查XML参数格式是否正确 |
| REQUIRE_POST_METHOD |
请使用post方法 |
未使用post传递参数 |
请检查请求参数是否通过post方法提交 |
| POST_DATA_EMPTY |
post数据为空 |
post数据不能为空 |
请检查post数据是否为空 |
| NOT_UTF8 |
编码格式错误 |
未使用指定编码格式 |
请使用UTF-8编码格式 |
2.3.3 退款接口
接口地址-接口链接：https://api.mch.weixin.qq.com/secapi/pay/refund
是否需要证书:请求需要双向证书。 详见证书使用
请求参数
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wx8888888888888888 |
微信分配的公众账号ID（企业号corpid即为此appId） |
| 商户号 |
mch_id |
是 |
String(32) |
1900000109 |
微信支付分配的商户号 |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
随机字符串，不长于32位。推荐随机数生成算法 |
| 签名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
签名，详见签名生成算法 |
| 签名类型 |
sign_type |
否 |
String(32) |
HMAC-SHA256 |
签名类型，目前支持HMAC-SHA256和MD5，默认为MD5 |
| 微信订单号 |
transaction_id |
二选一 |
String(32) |
1217752501201407033233368018 |
微信生成的订单号，在支付通知中有返回 |
| 商户订单号 |
out_trade_no |
String(32) |
1217752501201407033233368018 |
商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|*@ ，且在同一个商户号下唯一。 |
|
| 商户退款单号 |
out_refund_no |
是 |
String(64) |
1217752501201407033233368018 |
商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一退款单号多次请求只退一笔。 |
| 订单金额 |
total_fee |
是 |
Int |
100 |
订单总金额，单位为分，只能为整数，详见支付金额 |
| 退款金额 |
refund_fee |
是 |
Int |
100 |
退款总金额，订单总金额，单位为分，只能为整数，详见支付金额 |
| 退款货币种类 |
refund_fee_type |
否 |
String(8) |
CNY |
退款货币类型，需与支付一致，或者不填。符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见货币类型 |
| 退款原因 |
refund_desc |
否 |
String(80) |
商品已售完 |
若商户传入，会在下发给用户的退款消息中体现退款原因 |
| 退款资金来源 |
refund_account |
否 |
String(30) |
REFUND_SOURCE_RECHARGE_FUNDS |
仅针对老资金流商户使用 REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款（默认使用未结算资金退款） REFUND_SOURCE_RECHARGE_FUNDS---可用余额退款 |
| 退款结果通知url |
notify_url |
否 |
String(256) |
https://weixin.qq.com/notify/ |
异步接收微信支付退款结果通知的回调地址，通知URL必须为外网可访问的url，不允许带参数 如果参数中传了notify_url，则商户平台上配置的回调地址将不会生效。 |
举例如下：
返回结果
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 返回状态码 |
return_code |
是 |
String(16) |
SUCCESS |
SUCCESS/FAIL |
| 返回信息 |
return_msg |
否 |
String(128) |
签名失败 |
返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
以下字段在return_code为SUCCESS的时候有返回
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 业务结果 |
result_code |
是 |
String(16) |
SUCCESS |
SUCCESS/FAIL SUCCESS退款申请接收成功，结果通过退款查询接口查询 FAIL 提交业务失败 |
| 错误代码 |
err_code |
否 |
String(32) |
SYSTEMERROR |
列表详见错误码列表 |
| 错误代码描述 |
err_code_des |
否 |
String(128) |
系统超时 |
结果信息描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wx8888888888888888 |
微信分配的公众账号ID |
| 商户号 |
mch_id |
是 |
String(32) |
1900000109 |
微信支付分配的商户号 |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
随机字符串，不长于32位 |
| 签名 |
sign |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
签名，详见签名算法 |
| 微信订单号 |
transaction_id |
是 |
String(32) |
4007752501201407033233368018 |
微信订单号 |
| 商户订单号 |
out_trade_no |
是 |
String(32) |
33368018 |
商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-|*@ ，且在同一个商户号下唯一。 |
| 商户退款单号 |
out_refund_no |
是 |
String(64) |
121775250 |
商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一退款单号多次请求只退一笔。 |
| 微信退款单号 |
refund_id |
是 |
String(32) |
2007752501201407033233368018 |
微信退款单号 |
| 退款金额 |
refund_fee |
是 |
Int |
100 |
退款总金额,单位为分,可以做部分退款 |
| 应结退款金额 |
settlement_refund_fee |
否 |
Int |
100 |
去掉非充值代金券退款金额后的退款金额，退款金额=申请退款金额-非充值代金券退款金额，退款金额<=申请退款金额 |
| 标价金额 |
total_fee |
是 |
Int |
100 |
订单总金额，单位为分，只能为整数，详见支付金额 |
| 应结订单金额 |
settlement_total_fee |
否 |
Int |
100 |
去掉非充值代金券金额后的订单总金额，应结订单金额=订单金额-非充值代金券金额，应结订单金额<=订单金额。 |
| 标价币种 |
fee_type |
否 |
String(8) |
CNY |
订单金额货币类型，符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见货币类型 |
| 现金支付金额 |
cash_fee |
是 |
Int |
100 |
现金支付金额，单位为分，只能为整数，详见支付金额 |
| 现金支付币种 |
cash_fee_type |
否 |
String(16) |
CNY |
货币类型，符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见货币类型 |
| 现金退款金额 |
cash_refund_fee |
否 |
Int |
100 |
现金退款金额，单位为分，只能为整数，详见支付金额 |
| 代金券类型 |
coupon_type_$n |
否 |
String(8) |
CASH |
CASH--充值代金券 NO_CASH---非充值代金券 订单使用代金券时有返回（取值：CASH、NO_CASH）。$n为下标,从0开始编号，举例：coupon_type_0 |
| 代金券退款总金额 |
coupon_refund_fee |
否 |
Int |
100 |
代金券退款金额<=退款金额，退款金额-代金券或立减优惠退款金额为现金，说明详见代金券或立减优惠 |
| 单个代金券退款金额 |
coupon_refund_fee_$n |
否 |
Int |
100 |
代金券退款金额<=退款金额，退款金额-代金券或立减优惠退款金额为现金，说明详见代金券或立减优惠 |
| 退款代金券使用数量 |
coupon_refund_count |
否 |
Int |
1 |
退款代金券使用数量 |
| 退款代金券ID |
coupon_refund_id_$n |
否 |
String(20) |
10000 |
退款代金券ID, $n为下标，从0开始编号 |
举例如下：
错误码
| 名称 |
描述 |
原因 |
解决方案 |
| SYSTEMERROR |
接口返回错误 |
系统超时等 |
请不要更换商户退款单号，请使用相同参数再次调用API。 |
| BIZERR_NEED_RETRY |
退款业务流程错误，需要商户触发重试来解决 |
并发情况下，业务被拒绝，商户重试即可解决 |
请不要更换商户退款单号，请使用相同参数再次调用API。 |
| TRADE_OVERDUE |
订单已经超过退款期限 |
订单已经超过可退款的最大期限(支付后一年内可退款) |
请选择其他方式自行退款 |
| ERROR |
业务错误 |
申请退款业务发生错误 |
该错误都会返回具体的错误原因，请根据实际返回做相应处理。 |
| USER_ACCOUNT_ABNORMAL |
退款请求失败 |
用户帐号注销 |
此状态代表退款申请失败，商户可自行处理退款。 |
| INVALID_REQ_TOO_MUCH |
无效请求过多 |
连续错误请求数过多被系统短暂屏蔽 |
请检查业务是否正常，确认业务正常后请在1分钟后再来重试 |
| NOTENOUGH |
余额不足 |
商户可用退款余额不足 |
此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |
| INVALID_TRANSACTIONID |
无效transaction_id |
请求参数未按指引进行填写 |
请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败 |
| PARAM_ERROR |
参数错误 |
请求参数未按指引进行填写 |
请求参数错误，请重新检查再调用退款申请 |
| APPID_NOT_EXIST |
APPID不存在 |
参数中缺少APPID |
请检查APPID是否正确 |
| MCHID_NOT_EXIST |
MCHID不存在 |
参数中缺少MCHID |
请检查MCHID是否正确 |
| REQUIRE_POST_METHOD |
请使用post方法 |
未使用post传递参数 |
请检查请求参数是否通过post方法提交 |
| SIGNERROR |
签名错误 |
参数签名结果不正确 |
请检查签名参数和方法是否都符合签名算法要求 |
| XML_FORMAT_ERROR |
XML格式错误 |
XML格式错误 |
请检查XML参数格式是否正确 |
| FREQUENCY_LIMITED |
频率限制 |
2个月之前的订单申请退款有频率限制 |
该笔退款未受理，请降低频率后重试 |
2.3.4 对账单获取接口
接口链接:https://api.mch.weixin.qq.com/pay/downloadbill
是否需要证书:不需要。
请求参数
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 公众账号ID |
appid |
是 |
String(32) |
wx8888888888888888 |
微信分配的公众账号ID（企业号corpid即为此appId） |
| 商户号 |
mch_id |
是 |
String(32) |
1900000109 |
微信支付分配的商户号 |
| 随机字符串 |
nonce_str |
是 |
String(32) |
5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
随机字符串，不长于32位。推荐随机数生成算法 |
| 签名 |
sign |
是 |
String(32) |
C380BEC2BFD727A4B6845133519F3AD6 |
签名，详见签名生成算法 |
| 签名类型 |
sign_type |
否 |
String(32) |
HMAC-SHA256 |
签名类型，目前支持HMAC-SHA256和MD5，默认为MD5 |
| 对账单日期 |
bill_date |
是 |
String(8) |
20140603 |
下载对账单的日期，格式：20140603 |
| 账单类型 |
bill_type |
是 |
String(8) |
ALL |
ALL，返回当日所有订单信息，默认值 SUCCESS，返回当日成功支付的订单 REFUND，返回当日退款订单 RECHARGE_REFUND，返回当日充值退款订单 |
| 压缩账单 |
tar_type |
否 |
String(8) |
GZIP |
非必传参数，固定值：GZIP，返回格式为.gzip的压缩包账单。不传则默认为数据流形式。 |
返回结果
失败时，返回以下字段
| 字段名 |
变量名 |
必填 |
类型 |
示例值 |
描述 |
| 返回状态码 |
return_code |
是 |
String(16) |
FAIL |
FAIL |
| 返回信息 |
return_msg |
否 |
String(128) |
签名失败 |
返回信息，如非空，为错误原因 如：签名失败、参数格式错误等。 |
成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退款结果一致，具体字段说明可查阅相应接口。
第一行为表头，根据请求下载的对账单类型不同而不同(由bill_type决定),目前有：
当日所有订单
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额，退款类型，退款状态,商品名称,商户数据包,手续费,费率
当日成功支付的订单
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,商品名称,商户数据包,手续费,费率
当日退款的订单
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率
从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘1左边键的字符，字段顺序与表头一致。
倒数第二行为订单统计标题，最后一行为统计数据
总交易单数，总交易额，总退款金额，总代金券或立减优惠退款金额，手续费总金额
举例如下：
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率
`2014-11-1016：33：45,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1001690740201411100005734289,`1415640626,`085e9858e3ba5186aafcbaed1,`MICROPAY,`SUCCESS,`CFT,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
`2014-11-1016：46：14,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1002780740201411100005729794,`1415635270,`085e9858e90ca40c0b5aee463,`MICROPAY,`SUCCESS,`CFT,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额
`2,`0.02,`0.0,`0.0,`0
错误码
| 名称 |
描述 |
原因 |
解决方案 |
| SYSTEMERROR |
下载失败 |
系统超时 |
请尝试再次查询。 |
| invalid bill_type |
参数错误 |
请求参数未按指引进行填写 |
参数错误，请重新检查 |
| data format error |
|||
| missing parameter |
|||
| SIGN ERROR |
|||
| NO Bill Exist |
账单不存在 |
当前商户号没有已成交的订单，不生成对账单 |
请检查当前商户号在指定日期内是否有成功的交易。 |
| Bill Creating |
账单未生成 |
当前商户号没有已成交的订单或对账单尚未生成 |
请先检查当前商户号在指定日期内是否有成功的交易，如指定日期有交易则表示账单正在生成中，请在上午10点以后再下载。 |
| CompressGZip Error |
账单压缩失败 |
账单压缩失败，请稍后重试 |
账单压缩失败，请稍后重试 |
| UnCompressGZip Error |
账单解压失败 |
账单解压失败，请稍后重试 |
账单解压失败，请稍后重试 |