文档名称
统一小额支付接口文档
文档说明：
本文件描述…针对线下 O2O 手机支付行业提供的支付解决方案。供内部相关开发和技术支持人员与商户平台服务方技术人员使用。文档分别从交互模式、签名、接口、注意事项等方面详细介绍了工作方式和开发过程，可以帮助开发人员快速入门并掌握开发技能，同时也可以作为日后接口参数以及参数类型的速查手册。
文档版本：
| 版本号 | 修定人 | 制定日期 | 修订日期 |
|---|---|---|---|
| 2.1.0 | 杨敏 | 2017-03-20 | 2019-12-09 |
背景介绍:
扫码支付， 是基于微信， 手机 qq， 支付宝钱包客户端提供的支付服务功能。 同时向商户提供销售经营分析、 账户和资金管理的功能支持。 用户通过扫描二维码、 反扫二维码等多种方式调起支付模块完成支付。
流程说明:
业务实现流程
小额支付业务
使用场景：
(1)用户打开小额刷卡界面， 商家扫描到用户二维码或条码后发起支付， 通过 Post 生成订单的必要信息调用易办事 API。 API 返回 XML 格式的数据，返回调用结果。 支付成功后微信|手机 qq|支付宝钱包会提示用户交易结果， 如下图：
(2)在步骤 1 中， 如果用户使用小额已支付金额超过日限额(详细说明见下文)， 会提示用户输入密码。
(3)当步骤 1 未返回未成功或支付中状态， 可以主动调用查单接口查询支付状态。
(4)在交易状况不明晰的情况下调用冲正接口， 如果交易成功， 取消扣款， 如果交易失败则关闭订单。
接口调用时序图：
用户使用小额支付的免密额度以微信， 手机 qq， 支付宝钱包实时的额度限制为准。
接口说明:
小额支付接口
业务功能
收银员使用扫码设备读取微信用户刷卡授权码以后， 二维码或条码信息传送至商户收银台， 由商户收银台或者商户后台调用该接口发起支付对用户进行收款
交互模式
请求： 后台请求交互模式
返回结果： 后台请求交互模式
请求 url：
http://pay.xrtpay.com/xrtpay/gateway
请求参数列表
POST XML 内容体进行请求
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 业务参数 | ———— | ———— | ———— | ———— |
| 接口类型 | service | 是 | String(32) | unified.trade.micropay |
| 版本号 | version | 否 | String(8) | 默认值是 2.0 |
| 字符集 | charset | 否 | String(8) | 可选值 UTF-8，默认为 UTF-8 |
| 签名方式 | sign_type | 否 | String(8) | 取值：MD5 默认： MD5 |
| 商户号 | mch_id | 是 | String(32) | 商户号， 由技术部分配 |
| 大商户编号 | groupno | 否 | String(32) | 如果不为空，则用大商户密钥进行签名 |
| 商户订单号 | out_trade_no | 是 | String(32) | 商户系统内部的订单号 ,32个字符内、可包含字母,确保在商户系统唯一 |
| 设备号 | device_info | 是 | String(32) | 终端设备号(开头匹配类型统计) |
| 商品描述 | body | 是 | String(127) | 商品描述 |
| 附加信息 | attach | 否 | String(128) | 商户附加信息，可做扩展参数， 255 字符内 |
| 总金额 | total_fee | 是 | Int | 总金额，以分为单位，不允许包含任何字、符号 |
| 终端 IP | mch_create_ip | 是 | String(16) | 订单生成的机器 IP |
| 授权码 | auth_code | 是 | String(128) | 扫码支付授权码， 设备读取用户展示的条码或者二维码信息 |
| 订单生成时间 | time_start | 否 | String(14) | 订单生成时间， 格式为 yyyymmddhhmmss， 如2009 年 12 月 25 日 9 点 10 分 10 秒表示为20091225091010。 时区为 GMT+8 beijing。 该时间取自商户服务器 |
| 订单超时时间 | time_expire | 否 | String(14) | 订单失效时间， 格式为 yyyymmddhhmmss， 如2009 年 12 月 27 日 9 点 10 分 10 秒表示为20091227091010。 时区为 GMT+8 beijing。 该时间取自商户服务器 |
| 操作员 | op_user_id | 否 | String(32) | 操作员帐号,默认为商户号 |
| 门店编号 | op_shop_id | 否 | String(32) | |
| 设备编号 | op_device_id | 否 | String(32) | |
| 商品标记 | goods_tag | 否 | String(32) | 商品标记 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串， 不长于 32 位 |
| 签名 | sign | 是 | String(32) | MD5 签名结果， 详见“ 下文数字签名 MD5 签名规则” |
返回结果
数据按 XML 的格式实时返回
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 版本号 | version | 是 | String(8) | version 默认值是 2.0。 |
| 字符集 | charset | 是 | String(8) | 可选值 UTF-8，默认为 UTF-8。 |
| 签名方式 | sign_type | 否 | String(8) | 取值： MD5 默认： MD5 |
| 返回状态码 | status | 是 | String(16) | 0 表示成功非0 表示失败此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断 |
| 返回信息 | message | 否 | String(128) | 返回信息，如非空，为错误原因签名失败参数格式校验错误 |
| 以下字段在 status 为 0 的时候有返回 |
|---|
| 业务结果 | result_code | 是 | String(16) | 0 表示成功非 0 表示失败 |
|---|---|---|---|---|
| 商户号 | mch_id | 是 | String(32) | 商户号， 由技术部分配 |
| 设备号 | device_info | 否 | String(32) | 终端设备号 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串， 不长于 32 位 |
| 错误代码 | err_code | 否 | String(32) | 具体错误码请看文档最后错误码列表 |
| 错误代码描述 | err_msg | 否 | String (128) | 结果信息描述 |
| 结果信息描述 | sign | 是 | String(32 | MD5 签名结果， 详见“下文数字签名 签名规则” |
| 以下字段在 status 和 result_code 都为 0 的时候有返回 |
|---|
| 用户标识 | openid | 否 | String(128) | 用户在商户 appid 下的唯一标识 |
|---|---|---|---|---|
| 交易类型 | trade_type | 是 | String(16) | pay.weixin.micropaypay.qq.micropaypay.alipay.micropay |
| 是否关注公众账号 | is_subscribe | 否 | Int | 用户是否关注公众账号，0-关注， 1-未关注,仅在公众账号类型支付有效 |
| 支付结果 | pay_result | 是 | Int | 支付结果：0成功；其它—失败 |
| 支付结果信息 | pay_info | 否 | String(64) | 支付结果信息， 支付成功时为空 |
| ..订单号 | transaction_id | 是 | String(32) | ..交易号 |
| 第三方订单号 | out_transaction_id | 是 | String(32) | 第三方订单号 |
| 子商户是否关注 | sub_is_subscribe | 否 | Int | 用户是否关注子公众账号，0-关注，1-未关注，仅在公众账号类型支付有效 |
| 子商户 appid | sub_appid | 否 | String | 子商户 appid |
| 商户订单号 | out_trade_no | 是 | String(32) | 商户系统内部的定单号， 32 个字符内、 可包含字母 |
| 总金额 | total_fee | 是 | Int | 总金额， 以分为单位， 不允许包含任何字、符号 |
| 现金券金额 | coupon_fee | 否 | Int | 现金券支付金额<=订单总金额,订单总金额-现金券金额为现金支付金额 |
| 货币种类 | fee_type | 否 | String(8) | 货币类型， 符合 ISO 4217 标准的三位字母代码， 默认人民币： CNY |
| 附加信息 | attach | 否 | String(128) | 商家数据包， 原样返回 |
| 付款银行 | bank_type | 否 | String(16) | 银行类型 |
| 银行订单号 | bank_billno | 否 | String(32) | 银行订单号， 若为微信支付则为空 |
| 支付完成时间 | time_end | 是 | String(14) | 支付完成时间， 格式为 yyyyMMddhhmmss， 如2009 年 12 月27日9点10分10秒表示为20091227091010。时区为 GMT+8 beijing。该时间取自…服务器 |
当调用扣款接口返回支付中或失败状态， 需要调用查询接口查询订单实际支付状态 。 当遇到用户超过日限额需要输入密码返回“支付中” 的状态， 建议 10 秒调一次查询， 调用 3 次后还未成功作支付超时处理。
冲正接口
业务功能
当支付返回失败， 或收银系统超时需要取消交易， 可以调用该接口。 接口逻辑 ： 支付失败的关单， 支付成功的撤销支付。 注意： 支付成功的单如需实现相同功能请调用退款接口。
交互模式
请求： 后台请求交互模式
返回结果： 后台请求交互模式
请求 url：
http://pay.xrtpay.com/xrtpay/gateway
请求参数列表
POST XML 内容体进行请求
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 业务参数 | ———— | ———— | ———— | ———— |
| 接口类型 | service | 是 | String(32) | unified.micropay.reverse |
| 版本号 | version | 否 | String(8) | 默认值是 2.0 |
| 字符集 | charset | 否 | String(8) | 可选值UTF-8，默认为 UTF-8 |
| 签名方式 | sign_type | 否 | String(8) | 取值：MD5 默认：MD5 |
| 商户号 | mch_id | 是 | String(32) | 商户号，由技术部分配 |
| 商户订单号 | out_trade_no | 是 | String(32) | 商户系统内部的订单号 ,32 个字符内、可包含字母,确保在商户系统唯一 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串，不长于32位 |
| 签名 | sign | 是 | String(32) | MD5 签名结果，详见“下文数字签名 MD5 签名规则” |
返回结果
数据按 XML 的格式实时返回
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 版本号 | version | 是 | String(8) | 默认值是 2.0。 |
| 字符集 | charset | 是 | String(8) | 默认为 UTF-8。 |
| 签名方式 | sign_type | 否 | String(8) | 取值： MD5 默认： MD5 |
| 返回状态码 | status | 是 | String(16) | 0 表示成功非 0 表示失败此字段是通信标识， 非交易标识， 交易是否成功需要查看 result_code 来判断 |
| 返回信息 | message | 否 | String(128) | 返回信息， 如非空，为错误原因签名失败参数格式校验错误 |
| 以下字段在 status 为 0 的时候有返回 |
|---|
| 业务结果 | result_code | 是 | String(16) | 0 表示成功非 0 表示失败0 表示关单成功， 此笔订单不能再发起支付； 若已支付完成， 则会发起退款；非 0 或其它表示关单接口异常，可再次发起关单操作； |
|---|---|---|---|---|
| 商户号 | mch_id | 是 | String(32) | 商户号， 由技术人员分配 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串， 不长于 32 位 |
| 错误代码 | err_code | 否 | String(32) | 具体错误码请看文档最后错误码列表 |
| 错误代码描述 | err_msg | 否 | String(128) | 结果信息描述 |
| 签名 | sign | 是 | String(32) | MD5 签名结果， 详见“下文数字签名 MD5 签名规则” |
数据格式：
采用 HTTPS 标准的 POST 协议， 为了保证接收方接收数据正确,传输数据必须签名。
<xml>
<service>unified.trade.micropay</service>
<attach><![CDATA[att]]></attach>
<body><![CDATA[支付测试]]></body>
<device_info>1000</device_info>
<mch_id>10000100</mch_id>
<nonce_str>adf880d5c8986bd0deb6423c92c9d948</nonce_str>
<out_trade_no>1406046836</out_trade_no>
<spbill_create_ip>127.0.0.1</spbill_create_ip>
<total_fee>1</total_fee>
<sign><![CDATA[F53145E553092CE52E4CAA4D2B49A91C]]></sign>
</xmlXML 数据格式
采用标准 XML 协议， 所有参数只存在一级节点中， 不采用多级节点嵌套。
协议级错误返回：
<xml>
<status>500</status>
<message><![CDATA[SYSERR]]></message>
</xml>正确返回数据：
<xml>
<status>0</status>
<message><![CDATA[OK]]></message>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[FvYSnPuFFPkAr77M]]></nonce_str>
<sign><![CDATA[63238039D6E43634297CF2A6EB5F3B72]]></sign>
<result_code>0</result_code>
<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<is_subscribe><![CDATA[Y]]></is_subscribe>
<trade_type><![CDATA[MICROPAY]]></trade_type>
<bank_type><![CDATA[CCB_CREDIT]]></bank_type>
<total_fee>1</total_fee>
<coupon_fee>0</coupon_fee>
<fee_type><![CDATA[CNY]]></fee_type>
<transaction_id><![CDATA[1008450740201407220000058756]]></transaction_id>
<out_trade_no><![CDATA[1406033828]]></out_trade_no>
<attach><![CDATA[att]]></attach>
<time_end><![CDATA[20140722160655]]></time_end>
</xml>业务级错误返回：
<xml>
<status>0</status>
<message><![CDATA[OK]]></message>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[sthBJ9QyUG6vkrjJ]]></nonce_str>
<sign><![CDATA[6277A96D7875D4FF23AA7B6A4C3046AB]]></sign>
<result_code>1</result_code>
<err_code><![CDATA[AUTHCODE_EXPIRE]]></err_code>
<err_code_des><![CDATA[二维码已过期， 请刷新再试]]></err_code_des>
</xml>一般有返回有 status 参数， 0 表示调用成功； 非 0 表示调用失败。
数字签名：
为了保证数据传输过程中的数据真实性和完整性， 我们需要对数据进行数字签名， 在接收签名数据之后进行签名校验。
数字签名有两个步骤， 先按一定规则拼接要签名的原始串， 再选择具体的算法和密钥计算出签名结果。
一般失败的结果不签名。
签名原始串
无论是请求还是应答， 签名原始串按以下方式组装成字符串：
1、 除 sign 字段外， 所有参数按照字段名的 ascii 码从小到大排序后使用 QueryString 的格式（即key1=value1&key2=value2…） 拼接而成， 空值不传递， 不参与签名组串。
2、 签名原始串中， 字段名和字段值都采用原始值， 不进行 URL Encode。
3、 …返回的应答或通知消息可能会由于升级增加参数， 请验证应答签名时注意允许这种情况。
举例：
调用某个接口， 接口有如下字段：
<xml><body><![CDATA[测试支付]]></body>
<mch_create_ip><![CDATA[127.0.0.1]]></mch_create_ip>
<mch_id><![CDATA[001075552110006]]></mch_id>
<nonce_str><![CDATA[1409196838]]></nonce_str>
<notify_url><![CDATA[http://227.0.0.1:9001/javak/sds?123&23=3]]></notify_url>
<out_trade_no><![CDATA[141903606228]]></out_trade_no>
<service><![CDATA[unified.trade.micropay]]></service>
<sign><![CDATA[83684D9546F261997EFF2ECFAC372583]]></sign>
<total_fee><![CDATA[1]]></total_fee>
</xml>
正确的签名字段排序为：
body=测试支付
&mch_create_ip=127.0.0.1&mch_id=001075552110006&nonce_str=1409196838¬ify_url=http://227.0.0.1:9001/javak/sds?123&23=3&out_trade_no=141903606228&service=pay.
weixin.scancode&total_fee=1签名算法
目前暂只支持 MD5 签名
MD5 签名
MD5 是一种摘要生成算法， 通过在签名原始串后加上商户通信密钥的内容， 进行 MD5 运算， 形成的摘要字符串即为签名结果。 为了方便比较， 签名结果统一转换为大写字符。
注意： 签名时将字符串转化成字节流时指定的编码字符集应与参数 charset 一致。
MD5 签名计算公式：
sign = Md5(原字符串&key=商户密钥). toUpperCase
如：
假设以下为 XML 传入参数：
<xml><body><![CDATA[测试支付]]></body>
<mch_create_ip><![CDATA[127.0.0.1]]></mch_create_ip>
<mch_id><![CDATA[001075552110006]]></mch_id>
<nonce_str><![CDATA[1409196838]]></nonce_str>
<notify_url><![CDATA[http://227.0.0.1:9001/javak/sds?123&23=3]]></notify_url>
<out_trade_no><![CDATA[141903606228]]></out_trade_no>
<service><![CDATA[unified.trade.micropay]]></service>
<sign><![CDATA[83684D9546F261997EFF2ECFAC372583]]></sign>
<total_fee><![CDATA[1]]></total_fee>
</xml>假设商户密钥为： e1cf0ddcf6b47b59c351565d8ad717af
i： 经过 a 过程 URL 键值对字典序排序后的字符串 string1 为：
body=测试支付
&mch_create_ip=127.0.0.1&mch_id=001075552110006&nonce_str=1409196838¬ify_url=http://227.0.0.1:9001/javak/sds?123&23=3&out_trade_no=141903606228&service=pay.weixin.scancode&total_fee=1
ii： 经过 b 过程后得到 sign 为：
sign=md5(string1&key=e1cf0ddcf6b47b59c351565d8ad717af).toUpperCase
=md5(body=测试支付
&mch_create_ip=127.0.0.1&mch_id=001075552110006&nonce_str=1409196838¬ify_url=http://227.0.0.1:9001/javak/sds?123&23=3&out_trade_no=141903606228&service=unified.trade.micropay&total_fee=1&key=e1cf0ddcf6b47b59c351565d8ad717af).toUpperCase()
=”83684D9546F261997EFF2ECFAC372583”
注意事项：
1、 所有涉及到金额的单位都是分，最小的单位是 1 分，不能有小数出现
2、 其它注意事项
（ 1） 参数大小写问题
请留意文档中要求的字符大小写问题， 如 “ md5 运算后， 字符串的字符要转换为大写” 。
（ 2） 参数格式问题
所有传入参数，均为字符串类型，请注意文档中各处的具体要求。
（ 3） 时间戳问题
请使用 Linux 时间戳， 注意为字符串格式。 精确到秒， 不需要到毫秒， 即 10 位数字。
（ 4） 同一商户订单号支付问题
商户的 out_trade_no 必须全局唯一， 调试和生产环境， 都需要使用唯一的订单号。 注意：
当商户的同一个商户号绑定了多种支付方式也需要加标识来区分，不能出现重复。当发起支付返回失败时一定要用原订单的 out_trade_no 而不能重新生成新的订单号发起支付，避免同一单重复支付。
| 错误码 | 说明 | 类型 |
|---|---|---|
| 66227001 | 商户签名校验失败 | QQ 钱包 |
| 66227002 | 商户没有 QQ 钱包支付权限 | QQ 钱包 |
| 66227003 | 不在扫码支付的允许列表 | QQ 钱包 |
| 66227004 | 字符集转换失败 | QQ 钱包 |
| 66227005 | 需要用户输入支付密码 | QQ 钱包 |
| 66227006 | 用户授权码无效 | QQ 钱包 |
| 66227007 | 用户证书非法 | QQ 钱包 |
| 66227008 | 余额不足 | QQ 钱包 |
| 66227009 | 撤单失败， 订单已撤单 | QQ 钱包 |
| 66227010 | 撤单失败， 订单已支付成功 | QQ 钱包 |
| 66227011 | 撤单失败， 订单已退款 | QQ 钱包 |
| TRADE_SETTLE_ERROR | 分账信息校验失败 | 支付宝 |
| TRADE_BUYER_NOT_MATCH | 交易买家不匹配 | 支付宝 |
| CONTEXT_INCONSISTENT | 交易信息被篡改 | 支付宝 |
| TRADE_HAS_SUCCESS | 交易已经支付 | 支付宝 |
| TRADE_HAS_CLOSE | 交易已经关闭 | 支付宝 |
| REASON_ILLEGAL_STATUS | 交易的状态不合法 | 支付宝 |
| EXIST_FORBIDDEN_WORD | 订单信息中包含违禁词 | 支付宝 |
| ACCESS_FORBIDDEN | 没有权限使用该产品 | 支付宝 |
| SELLER_NOT_EXIST | 卖家不存在 | 支付宝 |
| BUYER_NOT_EXIST | 买家不存在 | 支付宝 |
| BUYER_ENABLE_STATUS_FORBID | 买家状态非法， 无法继续交易 | 支付宝 |
| BUYER_SELLER_EQUAL | 卖家买家账号相同， 不能进行交易 | 支付宝 |
| INVALID_PARAMETER | 参数无效 | 支付宝 |
| INVALID_RECEIVE_ACCOUNT | 卖家不在设置的收款账户列表之中 | 支付宝 |
| SYSTEMERROR | 接口返回（ 系统） 错误 | 微信 |
| PARAM_ERROR | 参数错误 | 微信 |
| ORDERPAID | 订单已支付 | 微信 |
| NOAUTH | 商户无权限 | 微信 |
| AUTHCODEEXPIRE | 二维码已过期， 请用户在微信上刷新后再试 | 微信 |
| NOTENOUGH | 余额不足 | 微信 |
| NOTSUPORTCARD | 不支持卡类型 | 微信 |
| ORDERCLOSED | 订单已关闭 | 微信 |
| ORDERREVERSED | 订单已撤销 | 微信 |
| BANKERROR | 银行系统异常 | 微信 |
| USERPAYING | 用户支付中， 需要输入密码 | 微信 |
| AUTH_CODE_ERROR | 授权码参数错误 | 微信 |
| AUTH_CODE_INVALID | 授权码检验错误 | 微信 |
| XML_FORMAT_ERROR | XML 格式错误 | 微信 |
| REQUIRE_POST_METHOD | 请使用 post 方法 | 微信 |
| Signature error | 签名错误 | 微信 |
| LACK_PARAMS | 缺少参数 | 微信 |
| NOT_UTF8 | 编码格式错误 | 微信 |
| BUYER_MISMATCH | 支付帐号错误 | 微信 |
| APPID_NOT_EXIST | APPID 不存在 | 微信 |
| MCHID_NOT_EXIST | MCHID 不存在 | 微信 |
| OUT_TRADE_NO_USED | 商户订单号重复 | 微信 |
| APPID_MCHID_NOT_MATCH | appid 和 mch_id 不匹配 | 微信 |
| ORDERNOTEXIST | 此交易订单号不存在 | 微信 |
问题排查:
备注:
- 更多返回错误代码请看首页的错误代码描述
