iPos接口接入报文规范 - 统一下单交易 - 《iPos-SA支付版》

交易请求报文
交易请求报文说明
交易返回报文
交易返回报文说明
服务商模式的微信小程序调用支付特别说明

交易请求报文

JSON:

{
    "request_type": "unifiedorder_request",
    "isspid": "39493002",
    "pos_id": "1511300001",
    "store_id": "1511300001",
    "pos_seq": "1511300000002",
    "user_id": "user01",
    "system_id": "8888",
    "device_ip": "127.0.0.1",
    "memo": "订单备注",
    "unifiedorder_request": {
        "pay_type": "515",
        "trade_type": "JSAPI",
        "tx_amt": "1",
        "sub_appid": "wxa138a13aca591b95",
        "buyer_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
        "valid_time": "60",
        "body": "商品描述",
        "goods_detail": [
            {
                "goods_id": "apple-01",
                "payment_goods_id": "20010001",
                "goods_name": "ipad",
                "quantity": 1,
                "price": 200000,
                "goods_category": "34543238",
                "body": "特价手机",
                "show_url": "http://www.alipay.com/xxx.jpg"
            },
            {
                "goods_id": "apple-02",
                "payment_goods_id": "20010002",
                "goods_name": "ipad2",
                "quantity": 1,
                "price": 200000,
                "goods_category": "34543239",
                "body": "特价手机2",
                "show_url": "http://www.alipay.com/xxx2.jpg"
            }
        ],
        "notify_url": "http://www.baidu.com/",
        "extend_params": {
            "split_flag": "R",
            "plan_split_date": "20230418",
            "split_info": {
                "keep_amt": "800",
                "split_list": [
                    {
                        "merchant_id": "10000000000001",
                        "div_amt": "150"
                    },
                    {
                        "merchant_id": "10000000000002",
                        "div_amt": "50"
                    }
                ]
            }
        }
    },
    "sign": "59B62BEBCA649C24DC25C44706677423"
}

XML:

<?xml version="1.0" encoding="GBK"?>
<business_trans>
    <request_type>unifiedorder_request</request_type>
    <isspid>39493002</isspid>
    <pos_id>1511300001</pos_id>
    <store_id>1511300001</store_id>
    <pos_seq>1511300000002</pos_seq>
    <user_id>user01</user_id>
    <system_id>8888</system_id>
    <device_ip>127.0.0.1</device_ip>
    <memo>订单备注</memo>
    <unifiedorder_request>
        <pay_type>515</pay_type>
        <trade_type>JSAPI</trade_type>
        <tx_amt>1</tx_amt>
        <sub_appid>wxa138a13aca591b95</sub_appid>
        <buyer_id>oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</buyer_id>
        <valid_time>60</valid_time>
        <body>商品描述</body>
        <goods_detail><![CDATA[商品信息(JSON)]]></goods_detail>
        <notify_url><![CDATA[http://www.baidu.com/]]></notify_url>
        <extend_params><![CDATA[扩展参数]]></extend_params>
    </unifiedorder_request>
</business_trans>

交易请求报文说明

节点名称	中文名称	类型	说明	是否必填
sign	报文签名	String(32)	请求报文格式为JSON时必填计算签名方式请看2.1章节	可选
request_type	请求类型	String(32)	固定值：unifiedorder_request	必填
isspid	商户号	String(8)	翼码商户号，由翼码提供	必填
pos_id	终端号	String(20)	商户自定义终端号	必填
store_id	门店号	String(20)	商户自定义门店号	必填
pos_seq	支付请求流水号	String(32)	同一个翼码商户号下唯一，不可重复使用，且大于12位	必填
user_id	操作员标识	String(20)	操作员号	可空
system_id	系统平台号	String(4)	由翼码提供	必填
device_ip	设备IP	String(15)	发起交易的门店或设备公网IP(仅支持IPv4) 根据央行要求必须传真实公网IP 否则商家会被风控！！！	可空
memo	订单备注	String(128)		可空
unifiedorder_request ->pay_type	支付类型	String(3)	515：微信小程序	必填
unifiedorder_request ->trade_type	交易类型	String(16)	微信小程序取值如下：JSAPI	必填
unifiedorder_request ->sub_appid	子商户应用ID	String(32)	发起交易商户号所绑定的小程序appid 如果有传appid就使用传的appid进行交易如果没传就使用系统中配置的appid进行交易	可空
unifiedorder_request ->buyer_id	用户标识	String(128)	微信小程序：用户在商户appid下的唯一标识(openid)	必填
unifiedorder_request ->valid_time	订单有效时间	String(3)	单位：分钟，最大不能超过120分钟不传则以通道方默认时间为准	可空
unifiedorder_request ->body	商品描述	String(100)	建议中文按3个字节计算，最大不超过33个中文不传则默认为“商户简称(门店名称)”	可空
unifiedorder_request ->goods_detail	商品信息	JSONArray	订单包含的商品信息列表，详细参数见下表使用XML格式报文时，建议使用CDATA标签包裹内容	可空
unifiedorder_request ->tx_amt	交易金额	Number(9)	支付金额，单位为分，不支持小数点	必填
unifiedorder_request ->notify_url	异步通知地址	String(256)	4.20.交易结果通知使用XML格式报文时，建议使用CDATA标签包裹内容	可空
unifiedorder_request ->extend_params	扩展参数	JSON	用于扩展一些特殊的支付参数字段，详细参数见下表使用XML格式报文时，建议使用CDATA标签包裹内容	可空

自定义门店号(store_id)和自定义终端号(pos_id)需经过4.1终端绑定交易接口绑定成功过的值才可以调用，绑定一次即可不需要重复绑定。

用户标识(buyer_id)获取方式

微信 - 小程序获取OpenID：https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html

goods_detail 商品信息 (JSONArray)

JSON节点	类型	说明	是否必填	范例
goods_id	String(32)	商品的编号	必填	apple-01
payment_goods_id	String(32)	支付平台商品编号	可空	20010001
goods_name	String(256)	商品名称	必填	ipad
quantity	Number(9)	商品数量	必填	1
price	Number(8)	商品单价，单位为分	必填	200000
goods_category	String(24)	商品类目仅支付宝时生效	可空	34543238
body	String(1000)	商品描述信息仅支付宝时生效	可空	特价手机
show_url	String(400)	商品的展示地址仅支付宝时生效	可空	http://www.alipay.com/xxx.jpg

goods_detail 样例：

[
    {
        "goods_id" : "apple-01",
        "payment_goods_id" : "20010001",
        "goods_name" : "ipad",
        "quantity" : 1,
        "price" : 200000,
        "goods_category" : "34543238",
        "body" : "特价手机",
        "show_url" : "http://www.alipay.com/xxx.jpg"
    },
    {
        "goods_id" : "apple-02",
        "payment_goods_id" : "20010002",
        "goods_name" : "ipad2",
        "quantity" : 1,
        "price" : 200000,
        "goods_category" : "34543239",
        "body" : "特价手机2",
        "show_url" : "http://www.alipay.com/xxx2.jpg"
    }
]

extend_params 扩展参数 (JSON)

JSON节点	类型	说明	是否必填	范例
split_flag	String	分账标识 N：不分账 R：实时分账 D：延时分账不传该节点时，将按控制台配置处理该节点与分账功能相关具体联系业务确认开通功能	可空	R
plan_split_date	String	预分账日期，格式：yyyymmdd 仅延时分账类型(split_flag=D)时支持传入	可空	20230418
split_info	JSON	分账信息仅支持请求实时分账split_flag=R 该节点与分账功能相关具体联系业务确认开通功能	可空

分账业务相关的特别说明：
1. split_flag=N 不分账时，split_info不允许传入；
2. split_flag=R 实时分账时，split_info必传，其中keep_amt与div_amt叠加必须全额分完整笔订单；
3. split_flag=D 延时分账时，split_info不允许传入，在后续流程中调用延迟交易确认接口完成分账，或使用翼码分账系统界面进行分账。

split_info 分账信息

JSON节点	类型	说明	是否必填	范例
is_clean_split	String	N：不使用净值分账 Y：使用净值分账不传默认为N，即不使用净值分账净值分账目前仅对部分通道开放，使用此能力前请先与技术支持确认净值分账仅在交易手续费内扣时才起作用当使用净值分账时，分账信息和分账明细必须要传分账比例，且分账方自留比例(keep_percentage)与所有分账比例(div_percentage)之和必须要为100%	可空	Y
keep_amt	String	分账方自留金额，单位为分，可传0表示不自留不使用净值分账(is_clean_split=N)时，该节点必填，分账方自留比例(keep_percentage)节点无效	可空	1000
keep_percentage	String	分账方自留比例，单位为%，最多支持小数点后两位，可传0表示不自留使用净值分账(is_clean_split=Y)时，该节点必填，分账方自留金额(keep_amt)节点无效	可空	50.26
split_list	Array	分账明细	必填

split_list 分账明细

JSON节点	类型	说明	是否必填	范例
merchant_id	String	分账接收方的分账商户号	必填	10000000000001
div_amt	String	分账金额，单位为分，必须大于0 不使用净值分账(is_clean_split=N)时，该节点必填，分账比例(div_percentage)节点无效	可空	1000
div_percentage	String	分账比例，单位为%，最多支持小数点后两位，必须大于0 使用净值分账(is_clean_split=Y)时，该节点必填，分账金额(div_amt)节点无效	可空	23.55

若业务涉及100%分账给接收方，请与业务对接人联系申请使用净值分账功能。

extend_params 样例：

{
    "split_flag": "R",
    "plan_split_date": "20230418",
    "split_info": {
        "keep_amt": "800",
        "split_list": [
            {
                "merchant_id": "10000000000001",
                "div_amt": "150"
            },
            {
                "merchant_id": "10000000000002",
                "div_amt": "50"
            }
        ]
    }
}

交易返回报文

{
    "response_type": "unifiedorder_response",
    "isspid": "39493002",
    "pos_id": "1511300001",
    "pos_seq": "1511300000002",
    "sys_seq": "0311095321465179",
    "trans_time": "20160311095321",
    "pay_type": "515",
    "pay_id": "wx1712341601086258515448c31980502232",
    "nonce_str": "lj1v8w5rqdiftm8zst5gwhjbvebcvyhl",
    "time_stamp": "1571286856",
    "sign_type": "MD5",
    "pay_sign": "9280696fced8329af66d7be472f9e7f6",
    "result": {
        "id": "9998",
        "comment": "下单成功,等待用户支付"
    },
    "sign": "D2E991C64AE4B6AD857A94904BDDB608"
}

<?xml version="1.0" encoding="GBK"?>
<business_trans>
    <response_type>unifiedorder_response</response_type>
    <isspid>39493002</isspid>
    <pos_id>1511300001</pos_id>
    <pos_seq>1511300000002</pos_seq>
    <sys_seq>0311095321465179</sys_seq>
    <trans_time>20160311095321</trans_time>
    <pay_type>515</pay_type>
    <pay_id>wx1712341601086258515448c31980502232</pay_id>
    <nonce_str>lj1v8w5rqdiftm8zst5gwhjbvebcvyhl</nonce_str>
    <time_stamp>1571286856</time_stamp>
    <sign_type>MD5</sign_type>
    <pay_sign><![CDATA[9280696fced8329af66d7be472f9e7f6]]></pay_sign>
    <result>
        <id>9998</id>
        <comment>下单成功,等待用户支付</comment>
    </result>
</business_trans>

交易返回报文说明

标准接口会因业务升级需要而新增节点，请在解析返回报文时避免新增未知节点产生的程序出错！

节点名称	中文名称	类型	说明	是否必填
sign	报文签名	String(32)	请求报文格式为JSON时必填计算签名方式请看2.1章节	可选
response_type	返回类型	String(32)	固定值：unifiedorder_response	必填
isspid	商户号	String(8)	翼码商户号，由翼码提供	必填
pos_id	终端号	String(20)	商户自定义终端号	必填
pos_seq	支付请求流水号	String(32)	支付请求流水号，和请求报文相同	必填
sys_seq	随机串号	String(16)	随机生成串号，仅用于日志跟踪用，不保存	必填
trans_time	接口返回时间	String(14)	接口返回时间，格式：yyyyMMddHHmmss	必填
pay_type	支付类型	String(3)	515：微信小程序	必填
pay_id	交易标识id	String(64)	微信小程序：微信生成的预支付回话标识(prepay_id) 下单成功时必填	可选
nonce_str	随机字符串	String(32)	微信小程序下单成功时必填	可选
time_stamp	时间戳	Integer	微信小程序下单成功时必填当接口返回整型时，请先转为字符串后调用微信api	可选
sign_type	签名方式	String(10)	微信小程序下单成功时必填	可选
pay_sign	支付签名	String(32)	微信小程序下单成功时必填 XML报文时将使用CDATA标签包裹	可选
result ->id	响应码	String(4)	9998 - 下单成功等待用户支付，需调用查询接口确认交易其它失败，错误信息说明见“响应码解释”字段	必填
result ->comment	响应码解释	String(64)	响应码对应中文注解，用于显示提示	必填

标准接口会因业务升级需要而新增节点，请在解析返回报文时避免新增未知节点产生的程序出错！

服务商模式的微信小程序调用支付特别说明

由于微信小程序支付在服务商模式下，在小程序调起支付API时计算签名字段(paySign)必须使用服务商的key，因此由服务商计算好入参与签名后返回给商户进行调用。

小程序调起支付API微信官方文档

调用wx.requestPayment(OBJECT)发起微信支付，Object参数取值说明：

timeStamp 取【统一下单交易】返回的 time_stamp （当接口返回整型时，请先转为字符串后调用微信api）

nonceStr 取【统一下单交易】返回的 nonce_str

package 中 prepay_id 取【统一下单交易】返回的 pay_id，格式如：prepay_id=wx1712341601086258515448c31980502232

paySign 取【统一下单交易】返回的pay_sign

signType 取【统一下单交易】返回的sign_type

以返回报文为例的示例代码：

wx.requestPayment
(
  {
    "timeStamp": "1414561699",
    "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
    "package": "prepay_id=wx201410272009395522657a690389285100",
    "signType": "RSA",
    "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg==",
    "success":function(res){},
    "fail":function(res){},
    "complete":function(res){}
  }
)

4.14.统一下单交易