接口说明
被扫交易接口,若涉及指定买家姓名身份证号等敏感信息时需要将全报文进行加密处理后再调用此接口完成被扫支付。加密方式见开发指引敏感信息接口加密说明。
场景说明: 如果用户支付密码用时比较长,商户多次查询完成时,用户还没有输密码完成,拉卡拉这边会按照一定的轮询策略(总时间范围大概在两个小时的多次查询)继续向账户端发起查询,查询成功后再按照接口中通知地址通知商户。如果用户在拉卡拉的轮询查询都完成了还没有完成输入密码,此时交易还处于中间态,只能依赖商户发起手工查询,触发拉卡拉再次向账户端发起交易结果查询。
调用地址
使用HTTP协议,POST方式提交。
测试环境: https://test.wsmsd.cn/sit/api/v3/labs/trans/micropay_encry
生产环境::https://s2.lakala.com/api/v3/labs/trans/micropay_encry
请求报文
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| merchant_no | 商户号 | M | String(32) | 拉卡拉分配的商户号 |
| term_no | 终端号 | M | String(32) | 拉卡拉分配的业务终端号 |
| out_trade_no | 商户交易流水号 | M | String(32) | 商户系统唯一,不可重复 |
| auth_code | 支付授权码 | M | String(32) | 扫码支付授权码,设备读取用户APP中的条码或者二维码信息,用户付款码条形码规则见说明 |
| total_amount | 金额 | M | String(12) | 单位分,整数型字符 |
| location_info | 地址位置信息 | M | Object | 地址位置信息,风控要求必送 |
| busi_mode | 业务模式 | C | String(8) | 业务模式: ACQ-收单 不填,默认为“ACQ-收单” |
| subject | 订单标题 | C | String(42) | 标题,用于简单描述订单或商品(账户端控制,实际最多42个字符),微信支付必送。 |
| pay_order_no | 拉卡拉支付业务订单号 | C | String(64) | 拉卡拉订单系统订单号,以拉卡拉支付业务订单号为驱动的支付行为,需上传该字段。 订单交易下单,交易时上送订单系统订单号,交易流程中会校验有效性、判重 |
| notify_url | 商户通知地址 | C | String(128) | 商户通知地址,如上传,且 pay_order_no 不存在情况下,且支付响应报文是交易中状态的场景下,则按此地址通知商户 |
| settle_type | 结算类型 | C | String(4) | “0”或者空,常规结算方式; |
| remark | 备注 | C | String(128) |
|
| scan_type | 扫码类型 | C | String(1) | 0或不填:扫码支付 1:支付宝刷脸支付;2: 微信刷脸支付 |
| identity_info | 身份信息 | C | String(1024) | 实名支付信息,json字符串,如{“identityNo”:”32000000000000000X”,”name”:”张三”} |
| acc_busi_fields | 账户端业务信息域 | C | Object | 参见以下acc_busi_fields字段详细说明,不同类型的auth_code对应不同的账户端,需要填写不同的信息 |
支持的auth_code说明
| 属性 | 说明 | 备注 |
|---|
| 微信 | WECHAT | 付款码10 11 12 13 14 15开头 |
| 支付宝 | ALIPAY | 付款码25 26 27 28 29 30开头 |
| 银联 | UQRCODEPAY | 付款码62开头 |
| 数币人民币 | DCPAY | 付款码01开头 |
| 翼支付 | BESTPAY | 付款码51开头 |
| 苏宁 | SUNING | 付款码83开头 |
location_info字段说明
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| request_ip | 请求方IP地址 | M | String(64) | 请求方的IP地址,存在必填,格式如36.45.36.95 |
| base_station | 基站信息 | C | String(128) | 客户端设备的基站信息(主扫时基站信息使用该字段) |
| location | 纬度,经度 | C | String(32) | 商户终端的地理位置,银联二维码交易必填,整体格式:纬度,经度,+表示北纬、东经,-表示南纬、 西经。 经度格式:1位正负号+3位整数+1位小数点+5位小数; 纬度格式:1位正负号+2位整数+1位小数点+6位小数; 举例:+31.221345,+121.12345 |
支付宝二维码被扫场景下acc_busi_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| extend_params | 业务扩展参数 | C | object | 支付宝业务扩展参数 ,主要用于花呗分期,见extend_params字段说明 |
| business_params | 商户传入业务信息 | C | String(512) | 商户传入业务信息,应用于安全,营销 等参数直传场景,格式为 json 格式。 |
| goods_detail | 商品详情 | C | String(6000) | 订单包含的商品列表信息,Json数组。见“支付宝goods_detail字段说明” |
| store_id | 商户门店编号 | C | String(32) | 支付宝收单上送 |
| alipay_store_id(不再使用) | 支付宝店铺编号 | C | String(32) | 支付宝已不再使用该字段 |
| timeout_express | 交易有效时间 | C | String(2) | 订单的有效时间,以分钟为单位。如果在有效时间内没有完成付款,则在账户端该订单失效。如果不上送,以账户端订单失效时间为准。 建议不超过15分钟。不传值则默认5分钟。 |
| disable_pay_channels | 支付宝禁用支付渠道 | C | String(32) | “credit_group”表示禁用信用卡 |
| business_params | 商户传入业务信息 | C | String(512) | 商户传入业务信息,应用于安全,营销等参数直传场景,格式为 json 格式。 示例:{“enable_thirdpar ty_subsidy”:”N”} |
| min_age | 允许的最小买家年龄 | C | String(2) | 买家年龄必须大于等于所传数值 |
| priority_pay_assets | 优先使用资产 | C | object | 优先使用资产 |
支付宝extend_params字段说明
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| sys_service_pr ovider_id | 服务商的PID | C | String(64) | 系统商编号,该参数作为系统商返佣数据提取的依据,请填写系统商签约协议的 PID |
| hb_fq_num | 花呗分期期数 | M | String(5) | 支付宝花呗分期必送字段: 花呗分期数 3:3期 6:6期 12:12期 |
| hb_fq_seller_percent | 卖家承担手续费比例 | M | String(3) | 支付宝花呗分期必送字段: 卖家承担手续费比例,间连模式下只支持传0。 |
支付宝goods_detail字段说明
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| goods_id |
| M | String(32) | 商品的编号 |
| alipay_goods_id |
| C | String(32) | 支付宝定义的统一商品编号 |
| goods_name |
| M | String(256) | 商品名称 |
| quantity |
| M | Number | 商品数量 |
| price |
| M | Price | 商品价格 单位元 |
| goods_category |
| C | String(24) | 商品类目 |
| categories_tree |
| C | String(128) | 商品类目树,从商品类目根节点到叶子节点的类目 id 组成,类目 id 值使用|分 割 |
| body |
| C | String(512) | 商品描述信息 |
| show_url |
| C | String(256) | 商品的展示地址 |
示例
“goods_detail”: “[{"goods_id":"1002","goods_name":"葱油拌面","quantity":"1","price":"1.10"}]”,
支付宝priority_pay_assets字段说明
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| assets_list | 资产列表 | C | list | 资产列表 |
| –asset_name | 资产名称 | C | String | 花呗资产,如:pcredit |
微信二维码被扫场景下acc_busi_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| sub_appid | 子商户公众账号ID sub_appid | C | String(32) | 微信公众平台基本配置中的AppID(应用ID),传入后支付成功可返回对应公众号下的用户openid,只对微信支付有效 |
| detail | 商品详情 | C | String(1024) | 单品优惠功能字段,json字符串格式,内容见以下“微信detail字段说明” |
| goods_tag | 订单优惠标记 | C | String(32) | 订单优惠标记,微信平台配置的商品标记,用于优惠券或者满减使用,accountType为WECHAT时,可选填此字段 |
| device_info | 设备号 | C | String(32) | 终端设备号(商户自定义,如门店编号) |
| limit_pay | 指定支付方式 | C | String(20) | no_credit–指定不能使用信用卡支付 |
| scene_info | 场景信息 | C | String(256) | 该字段用于上报场景信息,目前支持上报实际门店信息。 |
微信detail字段说明
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| cost_price |
| C | String(12) | 1.商户侧一张小票订单可能被分多次支付,订单原 价用于记录整张小票的交易金额。 2.当订单原价与支付金额不相等,则不享受优惠。 3.该字段主要用于防止同一张小票分多次支付,以 享受多次优惠的情况,正常支付订单不必上传此参 数。 如:608800 |
| receipt_id |
| C | String(12) | 商家小票 ID |
| goods_detail |
| M | String | 单品信息,使用Json数组格式提交,内容见以下“微信goods_detail字段说明” |
微信goods_detail字段说明
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| goods_id |
| M | String(32) | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成。如“商品编码” |
| wxpay_goods_id |
| C | String(32) | 微信支付定义的统一商品编号 |
| goods_name |
| C | String(256) | 商品的实际名称 |
| quantity |
| M | int | 用户购买的数量 |
| price |
| M | int | 单位为:分。如果商户有优惠,需传输商户优惠后的单价 |
银联二维码被扫场景下acc_busi_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| acq_addn_data_order_info | 银联订单信息 | C | String(600) | 银联二维码单品营销时上送 |
| acq_addn_data_goods_info | 银联商品信息 | C | String(6000) | 银联单品营销商品信息 |
示例
“acq_addn_data_order_info”: “{"title": "日用品","dctAmount": "2","addnInfo": "屈臣氏(人民广场)店"}”,
“acq_addn_data_goods_info”: “[{"id": "202230001","name": "test测试单品","price": "1","quantity": "1"}]”
响应报文
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| need_query | 是否需要发起查询 | M | String(32) | 0=不需要 1=需要 当返回1时,代表订单处理中,商户需主动发起查询 |
| merchant_no | 商户号 | M | String(32) | 拉卡拉分配的商户号(请求接口中商户号) |
| out_trade_no | 商户交易流水号 | M | String(32) | 请求报文中的商户交易流水号 |
| trade_no | 拉卡拉交易流水号 | M | String(32) | 拉卡拉交易流水号 |
| log_no | 拉卡拉对账单流水号 | M | String(14) | 拉卡拉对账单流水号 |
| acc_trade_no | 账户端交易订单号 | C | String(32) | 账户端交易流水号 |
| account_type | 钱包类型 | M | String(16) | 微信:WECHAT 支付宝:ALIPAY 银联:UQRCODEPAY 翼支付: BESTPAY 苏宁易付宝: SUNING 数字货币:DCPAY |
| total_amount | 订单金额 | M | String(12) | 单位分,整数数字型字符 订单金额=付款人实际发生金额+商户优惠金额+账户端优惠金额 |
| payer_amount | 付款人实际发生金额 | M | String(12) |
|
| acc_settle_amount | 账户端应结订单金额 | M | String(12) | 应结订单金额,单位分 ,账户端应结订单金额=付款人实际发生金额+账户端优惠金额 |
| acc_mdiscount_amount | 商户优惠金额(账户端) | C | String(12) | 账户端返回商户优惠金额,单位分 |
| acc_discount_amount | 账户端优惠金额 | C | String(12) | 账户端返回账户端优惠金额,单位分 |
| acc_other_discount_amount | 账户端其它优惠金额 | C | String(12) | 账户端返回账户端其它优惠金额,单位分 |
| trade_time | 交易完成时间 | M | String(14) | 以账户端返回时间为准 |
| bank_type | 付款银行 | C | String(128) | 付款银行 |
| card_type | 银行卡类型 | C | String(16) | 00:借记 01:贷记 02:微信零钱 03:支付宝花呗 04:支付宝其他 05:数字货币 06:拉卡拉支付账户 99:未知 |
| remark | 备注 | C | String(128) |
|
| acc_resp_fields | 账户端返回信息域 | C | Object | 账户端返回信息域 |
支付宝二维码被扫场景下返回acc_resp_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| user_id | 买家在支付宝的用户id | M | String(64) | buyer_user_id |
| store_id | 商户门店编号 | C | String(32) | 支付宝收单上送 |
| alipay_store_id(不再使用) | 支付宝店铺编号 | C | String(32) | 支付宝已不再使用该字段 |
| fund_bill_list | 交易支付使用的资金渠道(未上线) | C | String(512) |
|
| voucher_detail_list | 所有优惠券信息(未上线) | C | String(4096) |
|
| sub_mch_id | 子商户号 | C
| String(20) | 账户端子商户号 |
示例
“fund_bill_list”: “[{"amount":"1.00","fund_channel":"MDISCOUNT"},{"amount":"5.00","fund_channel":"ALIPAYACCOUNT"}]”,
“voucher_detail_list”: “[{"amount":"6.00","id":"202203030007300281380B7C5COQ","memo":"拉卡拉 测试用,浦东机场店,定向投放,不在店铺页展示","merchant_contribute":"6.00","name":"【必点】秘制豆浆","other_contribute":"0.00","purchase_ant_contribute":"0.00","purchase_buyer_contribute":"5.00","purchase_merchant_contribute":"1.00","template_id":"20220302000730017404006Z3HMI","type":"ALIPAY_ITEM_VOUCHER"}]”,
微信二维码被扫场景下返回acc_resp_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| open_id | 用户标识 | M | String(64) | 用户在商户appid下的唯一标识 |
| user_id | 用户子标识 | C | String(64) | sub_open_id |
| acc_activity_id | 活动 ID | C | String(32) | 在账户端商户后台配置的批次 ID |
| promotion_detail | 优惠功能信息 | C | String(4096) |
|
| sub_mch_id | 子商户号 | C
| String(20) | 账户端子商户号 |
银联二维码被扫场景下返回acc_resp_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| user_id | 用户id | M | String(64) | 云闪付APP支付时返回 |
| up_iss_addn_data | 银联单品营销 附加数据 | C | String(8000) | 参与单品营销优惠时返回 |
| up_coupon_info | 银联优惠信息/出资方信息 | C | String(500) | 参与单品营销优惠时返回 |
示例
“up_iss_addn_data”: “{"dctDetail":[{"id":"202230001","dctQuantity":"1","dctPrice":"1","dctId":"2112022022345425"}]}”,
“up_coupon_info”: “[{"id":"2112022022345425","desc":"lkl单品测试","type":"CP01","spnsrId":"8223310581202EY","offstAmt":"1"}]”,
数币被扫场景下返回acc_resp_fields域内容
| 字段名 | 中文名称 | 是否必填 | 类型 | 说明 |
|---|
| trade_info | 出资方信息 | C | String(512) | 数字货币中行返回示例说明:[{“fundchannel”:”BOC”,”amount”:”18”}] |
示例
请求报文
{
"req_time": "20210907150256",
"version": "3.0",
"out_org_code": "OP00000003",
"req_data": {
"merchant_no": "822290070111135",
"term_no": "29034705",
"out_trade_no": "FD660E1FAA3A4470933CDEDAE1EC1D8E",
"auth_code": "135178236713755038",
"total_amount": "123",
"location_info": {
"request_ip": "10.176.1.192",
"location": "+37.123456789,-121.123456789"
}
}
}复制响应报文
{
"msg": "用户支付中",
"resp_time": "20210907150258",
"code": "BBS10000",
"resp_data": {
"need_query": "1",
"out_trade_no": "FD660E1FAA3A4470933CDEDAE1EC1D8E",
"trade_no": "2021090766210003630077",
"log_no": "66210003630077",
"acc_trade_no": "",
"account_type": "WECHAT",
"total_amount": "123",
"payer_amount": "",
"acc_settle_amount": "",
"acc_mdiscount_amount": "",
"acc_discount_amount": "",
"trade_time": "20210907150258",
"bank_type": "",
"card_type": ""
}
}