文档名称
统一扫码支付接口文档
文档说明：
本文档是用于线下付款码支付。
文档版本：
| 版本号 | 修定人 | 制定日期 | 修订日期 |
|---|---|---|---|
| 3.0.0 | 杨铝杰 | 2021-12-27 | 2021-12-27 |
行业场景:
顾客扫码支付
流程说明:
业务实现流程
扫码支付业务
使用场景 ：
步骤（1） ：左图，商户根据微信支付的规则，在 POS 终端生成订单二维码。
步骤（2） ：右图，用户使用微信扫描二维码后，获取商品信息，同时到商户后台下单。
步骤（3） ：左图，用户开始支付，输入支付密码。
步骤（4） ：右图，支付成功，商户后台得到通知，进行发货处理
接口调用时序：
商户生成订单，先调用统一下单接口获取到 code_url，此 URL 直接生成二维码，用户扫码后调起支付。
时序图如下：
接口说明:
扫码支付接口
业务功能
初始化扫码请求，通过该请求生成二维码来进行扫码支付。
交互模式
请求：后台请求交互模式
返回结果+通知：后台请求交互模式+后台通知交互模式
请求URL:
https://pay.xrtpay.cn/xrtpay/gateway
请求参数列表
POST XML 内容体进行请求
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 业务参数 | ———— | ———— | ———— | ———— |
| 接口类型 | service | 是 | String(32) | 接口类型：pay.weixin.native，pay.alipay.native,pay.unpay.native |
| 版本号 | version | 否 | String(8) | 版本号，version 默认值是 3.0 |
| 字符集 | charset | 否 | String(8) | 可选值 UTF-8 ，默认为 UTF-8 |
| 签名方式 | sign_type | 否 | String(8) | 签名类型，取值：MD5 默认：MD5 |
| 商户号 | mch_id | 是 | 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 |
| 通知地址 | notify_url | 是 | String(255) | 接收…通知的 URL，需给绝对路径，255字符内格式如：http://wap.tenpay.com/tenpay.asp |
| 订单生成时间 | 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。该时间取自商户服务器 |
| 商品标记 | goods_tag | 否 | String(32) | 商品标记，微信平台配置的商品标记，用于优惠券或者满减使用 |
| 商品 ID | product_id | 否 | String(32) | 预留字段此 id 为静态可打印的二维码中包含的商品ID，商户自行维护。 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串，不长于32位 |
| 花呗分期数 | hb_fq_num | 否 | String(2) | 仅适用于支付宝花呗分期，可选：3,6,12 期分期数 通过该域的上送，请求方可实现花呗分期单通道 |
| 终端信息 | terminal_info | 是 | json | 商户侧受理终端信息，格式为 json 格式。详见附录说明 |
| 地区信息 | area_info | 否 | String(7) | 商户所在地地区信息，7 位定长，各部分说明如下： （1）1-3 位：国家代码，参见世界各国和地区名称代码 （GB/T 2659-94）。 境内商户受理的业务，国家代码固定填 156。 （2）4-7 位：地区代码，采用《银联卡跨行业务地区代 码标准》。 境外商户受理的业务，地区代码用全 0 填充。 |
| 签名 | sign | 是 | String(32) | MD5 签名结果，详见“下文数字签名 MD5 签名规则” |
返回结果
数据按 XML 的格式实时返回
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 版本号 | version | 是 | String(8) | 版本号，version 默认值是 1.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 签名结果，详见“下文数字签名 MD5 签名规则” |
| 以下字段在 status 和 result_code 都为 0 的时候有返回 |
|---|
| 二维码链接 | code_url | 是 | String(64) | 此参数可直接生成二维码展示出来进行扫码支付|
扫码通知接口
通知结果参数列表
通知 URL 是 6.1 节中提交的参数 notify_url，支付完成后，…会把相关支付和用户信息发送到该 URL，商户需要接收处理信息。
对后台通知交互时，如果收到商户的应答不是成功或超时，微信认为通知失败， 会通过一定的策略（如 30 分钟共 8 次）定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。
由于存在重新发送后台通知的情况， 因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知 。
推荐的做法是， 当收到通知进行处理时， 首先检查对应业务数据的状态， 判断该通知是否已经处理过， 如果没有处理过再进行处理， 如果处理过直接返回结果成功。 在对业务数据进行状态检查和处理之前， 要采用数据锁进行并发控制， 以避免函数重入造成的数据混乱。
后台通知通过请求中的 notify_url 进行， post
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 接口类型 | service | 是 | String(32) | 接口类型：pay.weixin.native |
| 版本号 | version | 是 | String(8) | 版本号，version 默认值是 1.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) | 0 表示成功非 0 表示失败 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串，不长于 32 位 |
| 错误代码 | err_code | 否 | String(32) | 参考错误码 |
| 错误代码描述 | err_msg | 否 | String (128) | 结果信息描述 |
| 签名 | sign | 是 | String(32) | MD5 签名结果，详见“下文数字签名 MD5 签名规则” |
| 以下字段在 status 和 result_code 都为 0 的时候有返回 |
|---|
| 用户标识 | openid | 是 | String(128) | 用户在商户 appid 下的唯一标识 |
|---|---|---|---|---|
| 交易类型 | trade_type | 是 | String (16) | pay.weixin.native、pay.weixin.micropay |
| 是否关注公众 | 账号is_subscribe | 是 | Int | 用户是否关注公众账号，0-关注，1-未关注，仅在公众账号类型支付有效 |
| 支付结果 | pay_result | 是 | Int | 支付结果：0—成功；其它—失败 |
| 支付结果信息 | pay_info | 否 | String(64) | 支付结果信息，支付成功时为空 |
| …订单号 | transaction_id | 是 | String(32) | …交易号 |
| 商户订单号 | 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。该时间取自服务器 |
后台通知结果反馈
…后台通过 notify_url 通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：
| 返回结果 | 结果说明 |
|---|---|
| success | 处理成功，…系统收到此结果后不再进行后续通知 |
| fail 或其它字符 | 处理不成功，…收到此结果或者没有收到任何结果，系统通过补单机制（补单机制）再次通知 |
数据格式:
提交数据
采用 HTTP 标准的 POST 协议，为了保证接收方接收数据正确,传输数据必须签名。
<xml>
<service>pay.weixin.native </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>
</xml>XML 数据格式
采用标准 XML 协议，所有参数只存在一级节点中，不采用多级节点嵌套。
协议级错误返回：
<xml>
<status>500</status>
<message><![CDATA[SYSERR]]></message>
</xml>
正确返回数据:
```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 表示调用失败。
补单机制:
注意：对后台通知交互模式，如果…收到商户的应答不“success”或超时，…认为通知失败，会通过一定的策略（如30分钟共8 次）定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回“success”。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱
注意事项:
1、所有涉及到金额的单位都是分，最小的单位是 1 分，不能有小数出现
2、 notify_url是…服务器从后台直接发起请求到商户服务器，商户处理时不能检查用户的cookie 或 session；商户更新 DB等发货流程需要在 notify_url 完成后，以确保掉单时，..补单能成功补上
3、 notify_url 有可能重复通知，商户需要做去重处理，避免多次发货
4、 notify_url 收到的通知，商户处理成功或检查订单已经处理，需要返回处理成功的标志“success”，以告知…不再通知
5、 其它注意事项
（1） 参数大小写问题
请留意文档中要求的字符大小写问题， 如“md5运算后，字符串的字符要转换为大写”。
（2） 参数格式问题
所有传入参数，均为字符串类型，请注意文档中各处的具体要求。
（3） 时间戳问题
请使用 Linux 时间戳，注意为字符串格式。精确到秒，不需要到毫秒，即 10 位数字。
（4） 同一商户订单号支付问题
商户的 out_trade_no 必须全局唯一，调试和生产环境，都需要使用唯一的订单号。注意：
当商户的同一个商户号绑定了多种支付方式也需要加标识来区分，不能出现重复。当发起支付返回失败时，一定要用原订单的 out_trade_no 而不能重新生成新的订单号发起支付，避免同一单重复支付。
问题排查:
备注:
- 更多返回错误代码请看首页的错误代码描述
