iPos接口接入报文规范 - 聚合动态码支付下单 - 《iPos-SA支付版》

交易请求报文
交易请求报文说明
- goods_detail 商品信息 (JSONArray)
- extend_params 扩展参数 (JSON)
  - split_info 分账信息
    - split_list 分账明细
交易返回报文
交易返回报文说明
- code_url 聚合二维码信息

交易请求报文

JSON:

{
    "request_type": "scanpay_qrcode_request",
    "isspid": "39493002",
    "pos_id": "1511300001",
    "store_id": "1511300001",
    "pos_seq": "2018121400000004",
    "user_id": "user01",
    "system_id": "8888",
    "memo": "订单备注",
    "scanpay_qrcode_request": {
        "tx_amt": "1",
        "body": "商品描述",
        "notify_url": "http://www.baidu.com/",
        "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": {
            "hb_fq_num": "3",
            "hb_fq_seller_percent": "100",
            "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": "314DA43E7E244105ECBD45F797264854"
}

XML:

<?xml version="1.0" encoding="GBK"?>
<business_trans>
    <request_type>scanpay_qrcode_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>
    <memo>订单备注</memo>
    <scanpay_qrcode_request>
        <tx_amt>1</tx_amt>
        <body>商品描述</body>
        <notify_url><![CDATA[http://www.baidu.com/]]></notify_url>
        <goods_detail><![CDATA[商品信息(JSON)]]></goods_detail>
        <extend_params><![CDATA[扩展参数(JSON)]]></extend_params>
    </scanpay_qrcode_request>
</business_trans>

交易请求报文说明

节点名称	中文名称	类型	说明	是否必填
sign	报文签名	String(32)	请求报文格式为JSON时必填计算签名方式请看2.1章节	可选
request_type	请求类型	String(32)	固定值：scanpay_qrcode_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)	由翼码提供	必填
memo	订单备注	String(128)		可空
scanpay_qrcode_request ->tx_amt	交易金额	Number(9)	单位为分	必填
scanpay_qrcode_request ->body	商品描述	String(100)	建议中文按3个字节计算，最大不超过33个中文不传则默认为“商户简称(门店名称)”	可空
scanpay_qrcode_request ->notify_url	异步通知地址	String(256)	4.20.交易结果通知使用XML格式报文时，建议使用CDATA标签包裹内容	可空
scanpay_qrcode_request ->goods_detail	商品信息	JSONArray	订单包含的商品信息列表，详细参数见下表使用XML格式报文时，建议使用CDATA标签包裹内容	可空
scanpay_qrcode_request ->extend_params	扩展参数	JSON	用于扩展一些特殊的支付参数字段，详细参数见下表使用XML格式报文时，建议使用CDATA标签包裹内容	可空

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

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节点	类型	说明	是否必填	范例
hb_fq_num	String	花呗分期数，仅支持传入3、6、12，其他期数暂不支持仅支付宝时生效 hb_fq_num与hb_fq_seller_percent必须同时传入且使用花呗分期商品明细必传	可空	3
hb_fq_seller_percent	String	花呗卖家承担收费比例，商家承担手续费传入100，用户承担手续费传入0，仅支持传入100、0两种，其他比例暂不支持仅支付宝时生效 hb_fq_num与hb_fq_seller_percent必须同时传入且使用花呗分期商品明细必传	可空	100
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 样例：

{
    "hb_fq_num": "3",
    "hb_fq_seller_percent": "100",
    "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"
            }
        ]
    }
}

交易返回报文

JSON:

{
    "response_type": "scanpay_qrcode_response",
    "isspid": "39493002",
    "pos_id": "6666666666",
    "pos_seq": "2018121400000004",
    "trans_time": "20181214143516",
    "sys_seq": "0741136885a748c1",
    "code_url": "http://ipos-sa.imageco.cn/qrcode?state=1FGL3T1B7057T",
    "extend": "",
    "result": {
        "id": "9998",
        "comment": "下单成功，等待用户支付"
    },
    "sign": "F6106656C20AB23B547B0C30DD819793"
}

XML:

<?xml version="1.0" encoding="GBK"?>
<business_trans>
    <response_type>scanpay_qrcode_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>
    <code_url><![CDATA[http://ipos-sa.imageco.cn/qrcode?state=1FGL3T1B7057T]]></code_url>
    <extend><![CDATA[扩展字段(json格式)]]></extend>
    <result>
        <id>9998</id>
        <comment>下单成功,等待用户支付</comment>
    </result>
</business_trans>

交易返回报文说明

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

节点名称	中文名称	类型	说明	是否必填
sign	报文签名	String(32)	返回报文格式为JSON时必填计算签名方式请看2.1章节	可选
response_type	返回类型	String(32)	固定值：scanpay_qrcode_response	必填
isspid	商户号	String(8)	翼码商户号，由翼码提供	必填
pos_id	终端号	String(20)	商户自定义终端号	必填
pos_seq	支付请求流水号	String(32)	支付请求流水号，和请求报文相同	必填
sys_seq	随机串号	String(16)	随机生成串号，仅用于日志跟踪用，不保存	必填
trans_time	接口返回时间	String(14)	接口返回时间，格式：yyyyMMddHHmmss	必填
code_url	聚合二维码信息	String(100)	聚合二维码的信息商户系统生成二维码提供给支付方扫码支持支付宝、微信、云闪付APP XML报文时使用CDATA标签包裹	可选
extend	扩展信息	String	扩展信息字段内容为json格式预留字段后续业务扩展使用 XML报文时使用CDATA标签包裹	可空
result ->id	响应码	String(4)	9998：下单成功，等待用户扫码(交易结果需调用查询接口确认) 其它失败，错误信息说明见“响应码解释”字段	必填
result ->comment	响应码解释	String(64)	响应码对应中文注解，用于显示提示	必填

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

code_url 聚合二维码信息

返回的URL生成二维码给用户扫码，支持微信、支付宝、云闪付扫码。

测试环境URL为http协议，域名为ipos-sa.imageco.cn，例：http://ipos-sa.imageco.cn/qrcode?state=1FGL3T1B7057T

生产环境URL为https协议
a.域名为ipos-sa-std.wangcaio2o.com，例：https://ipos-sa-std.wangcaio2o.com/qrcode?state=1FGL3T1B7057T
b.域名为ipos-sa-kylin.wangcaio2o.com，例：https://ipos-sa-kylin.wangcaio2o.com/qrcode?state=1FGL3T1B7057T
不同域名以实际返回为准

4.21.聚合动态码支付下单