文档名称
统一付款码支付接口文档
文档说明：
本文档是用于线下付款码支付。
文档版本：
| 版本号 | 修定人 | 制定日期 | 修订日期 |
|---|---|---|---|
| 3.0.0 | 杨铝杰 | 2021-12-27 | 2021-12-27 |
背景介绍:
扫码支付， 是基于微信， 支付宝钱包客户端提供的支付服务功能。 同时向商户提供销售经营分析、 账户和资金管理的功能支持。 用户通过扫描二维码调起支付模块完成支付。
流程说明:
业务实现流程
接口说明:
小额支付接口
业务功能
收银员使用扫码设备读取微信用户条码授权码以后， 二维码或条码信息传送至商户收银台， 由商户收银台或者商户后台调用该接口发起支付对用户进行收款
交互模式
请求： 后台请求交互模式
返回结果： 后台请求交互模式
请求 url：
https://pay.xrtpay.cn/xrtpay/gateway
请求参数列表
POST XML 内容体进行请求
| 字段名 | 变量名 | 必填 | 类型 | 说明 |
|---|---|---|---|---|
| 业务参数 | ———— | ———— | ———— | ———— |
| 接口类型 | service | 是 | String(32) | unified.trade.micropay |
| 版本号 | version | 否 | String(8) | 默认值是 3.0 |
| 字符集 | charset | 否 | String(8) | 可选值 UTF-8，GBK,默认为 UTF-8 |
| 签名方式 | sign_type | 是 | String(8) | 取值：SM3 默认： SM3 |
| 商户号 | 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 |
| 授权码 | auth_code | 是 | String(128) | 扫码支付授权码， 设备读取用户展示的条码或者二维码信息 |
| 随机字符串 | nonce_str | 是 | String(32) | 随机字符串， 不长于 32 位 |
| 单品营销 | commodity_detail | 否 | string | 单品优惠功能字段，json 格式，详见附录说明 |
| 花呗分期数 | 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 默认值是 2.0。 |
| 字符集 | charset | 是 | String(8) | 可选值 UTF-8，默认为 UTF-8。 |
| 签名方式 | sign_type | 否 | String(8) | 取值： SM3 默认： SM3 |
| 返回状态码 | 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.micropay, pay.alipay.micropay |
| 是否关注公众账号 | is_subscribe | 否 | Int | 用户是否关注公众账号，0-关注， 1-未关注,仅在公众账号类型支付有效 |
| 支付结果 | pay_result | 是 | Int | 支付结果：0成功；其它—失败 |
| 支付结果信息 | pay_info | 否 | String(64) | 支付结果信息， 支付成功时为空 |
| 平台订单号 | transaction_id | 是 | String(32) | 平台订单号 |
| 第三方订单号 | out_transaction_id | 是 | String(32) | 第三方订单号 |
| 结算金额 | settlement_total_fee | 否 | Int | 当订单使用了免充值型优惠券后返回该参数， 应结订单金额=订单金额-免充值优惠券金额。 |
| 优惠功能 | promotion_detail | 否 | String(6000) | 微信支付时，营销详情列表，使返回值为 Json 格 式。详见下文说明：附录-单品营销 |
| 商户订单号 | out_trade_no | 是 | String(32) | 商户系统内部的定单号， 32 个字符内、 可包含字母 |
| 总金额 | total_fee | 是 | Int | 总金额， 以分为单位， 不允许包含任何字、符号 |
| 付款方附加数据 | issAddnData | 否 | String(8000) | 云闪付支付时，返回商品维度优惠信息。本域需整 体做 Base64 编码，本域采用 JSON 格式。目前仅 包含“商品优惠信息 dctDetail”子域，后续将根 据业务需要新增子域。详见附录-单品营销 |
| 优惠信息 | couponInfo | 否 | String(500) | 云闪付支付时，本域需整体做 Base64 编码，本域 采用 JSON 格式，以方便扩展。本域全部内容用 “[ ]”包含；内部可含多个对象，每个对象用“{ }” 包含，对象之间以“,”分隔。详见附录 |
| 货币种类 | 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 次后还未成功作支付超时处理。
数据格式：
采用 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 表示调用失败。
数字签名：
参考签名页
问题排查:
备注:
- 更多返回错误代码请看首页的错误代码描述
文档更新时间: 2022-03-03 16:43 作者：EricYang
