SaaS服务码支付

1、修订记录

修订 日期 说明 作者
0.1 2020/11/11 新接口参数定义 康少雄
0.2 2021/06/22 支持saas服务码D0 王晶
0.3 2021/12/23 增加子商户ip submer_ip 刘雷
0.4 2021/12/27 支持国密 王晶
0.5 2022/02/17 seller_name修改为非必填 王晶
0.6 2022/03/17 version为3.9时 新增支付成功异步通知营销相关字段 刘雷
0.7 2022/03/18 新增银联259号文条码改造相关字段 刘雷
0.8 2022/10/19 对异步通知coupon_info字段的参数说明进行调整，及在异步通知中添加alipay_trx_resp_coupon_info，ali_goods_details, ali_platform_dis_amount,ali_merchant_amount参数字段 刘军

2、业务说明

（1）场景说明

为满足商户对接“方便快捷”的支付需求，设计了银盛支付SaaS服务码API支付业务。商户仅需对接一个支付接口，即可完成微信、支付宝、银联云闪付聚合扫码支付的开发对接， 满足商户特定场景和特定内容的需要

（2）接口说明

新增聚合订单二维码api，以满足更多业务场景的需求。

3、请求地址

环境 HTTPS请求地址
正式环境 https://qrcode.ysepay.com/gateway.do

4、请求参数说明

4.1公共请求参数

参数 类型(字节长度） 必填 参数说明
method String(128) Y 接口名称 固定值 ysepay.online.polycodepay
partner_id String(20) Y 在银盛支付开设的服务商商户号，请联系客户经理提供
timestamp String(19) Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值：2014-07-24 03:07:50
charset String(10) Y 商户网站使用的编码格式，如UTF-8、GBK、GB2312等，默认值 GBK
sign_type String(10) Y 报文签名算法，RSA、SM
sign String(256) Y 签名字符串，再用Base64编码
notify_url String(500) Y 交易成功异步通知到商户的后台地址，http路径支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3，支持TLS1.0、TLS1.1、TLS1.2
version String(3) Y 版本号3.0/3.2/3.5 当前版本3.5
tran_type String(1) N 交易类型，说明：1或者空：非担保交易，2：担保交易(D0不支持)，无特殊需求 不用填此字段
biz_content String Y 业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递

4.2 业务请求参数

参数名biz_content,值为一个json格式对象，下面列表描述json对象的值

参数 类型(字节长度） 必填 参数说明
out_trade_no String(1,32) Y 商户系统生成的订单号，须保证在商户端不重复，生成规则前8位必须为交易日期，如20220525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成，示例值：202205256843192280647118
shopdate String(8,8) Y 商户系统的交易发生日期格式yyyyMMdd 示例值：20180525
subject String(1,250) Y 订单备注
total_amount Number(10,2) Y 该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度 示例值：100
currency String(3) N 默认CNY（人民币）
seller_id String(1,20) Y 收款商户号（银盛支付生成并下发）
seller_name String(1,50) N 收款商户号对应商户名称
timeout_express String(2,6) Y 设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭，取值范围：1m～15d。m-分钟，h-小时，d-天。该参数数值不接受小数点，如1.5h，可转换为90m。注意：设置了未付款交易超时时间的情况下，若我司在限定时间内没有收到成功支付通知，则会关闭交易，关闭后该笔交易若付款方支付成功的情况下，会自动原路退款至付款方。示例值：96h 代表96小时后订单自动关闭
business_code String(1,10) Y 业务代码，saas服务码T1: 00510046，saas服务码D0: 00510047(不支持担保交易)
extra_common_param String(2000) N 公用回传参数 商户自定义数据域，原样返回
submer_ip String(16) N 子商户ip 112.112.112.112
union_qrcode_259_params UnionQrCodeBaseRequest N 银联259号文条码改造字段，json格式

4.2.1 银联259号文条码改造字段 UnionQrCodeBaseRequest

参数 类型(字节长度） 必填 参数说明
terminal_no String(8) Y 终端号，收单机构为商户终端分配的唯一编号
terminal_type String(2) Y 终端类型（线下交易场景必填）：01 自动柜员机（含 ATM 和 CDM）和多媒体自助终端、02 传统 POS、03 mPOS、04 智能 POS、05 II 型固定电话、06 云闪付终端、07 保留使用、08 手机 POS、09 刷脸付终端、10 条码支付受理终端、11 辅助受理终端、12 行业终端（公交、地铁用于指定行业的终端）、13 MIS 终端
serial_num String(50) O 终端序列号，备注：终端类型为 02;03;04;05;06;08;09或10时,必须填写终端序列号
network_license String(5) N 银行卡受理终端产品入网认证编号，备注：终端类型为 02;03;04;05;06;08;09或10时,终端设备如果有相关参数,建议填写
app_version String(5) N 终端应用程序的版本号，备注：终端类型为 02;03;04;05;06;08;09或10时,建议填写。终端应用程序的版本号,应用程序变更应保证版本号不重复。
terminal_gps String(32) O 交易设备位置信息，格式:纬度/经度,东经为正数，西经为负数;北纬为正数，南纬为负数,线下交易场景、terminal_ip和terminal_gps 二者选其一 必填
terminal_ip String(8) O 商户端终端设备 IP 地址。注：如经、维度信息未上送，该字段必送。
encryp_rand_num String(10) N 加密随机因子
secret_text String(16) N 密文数据

5、响应参数说明

银盛支付对商户的请求数据处理完成后，会将处理的结果数据同步回执给商户。

请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

5.1 公共响应参数

参数 类型(字节长度） 必填 参数说明
sign String Y 签名字符串，Base64编码
ysepay_online_polycodepay_response String Y 业务响应参数的集合，最大长度不限

5.2 业务响应参数

参数 类型(字节长度） 必填 参数说明
code String Y 响应代码
msg String Y 响应代码描述
out_trade_no String(32) Y 商户系统生成的订单号 示例值：6843192280647118
trade_no String(30) N 银盛支付交易流水号
trade_status String Y 交易目前所处的状态。成功状态的值： TRADE_SUCCESS 示例值：附录8.1
total_amount Number Y 该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值：100
currency String(3) N 币种 默认CNY（人民币）
poly_code_url String(1024) Y 聚合订单码地址 示例值：http://qpay.qq.com/qr/0e02ebc4
extra_common_param String(2000) N 商户自定义数据域，原样返回 例123456789

6、服务器异步通知参数说明

银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。

请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

参数 类型(字节长度） 必填 参数说明
sign_type String Y 签名类型（RSA/SM），对应交易请求传入签名类型
sign String Y 签名字符串，Base64编码
notify_type String Y 通知类型 固定值 directpay.status.sync
notify_time String(19) Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值： 2014-07-24 03:07:50
out_trade_no String(32) Y 商户系统生成的订单号 示例值：6843192280647118
total_amount Number N 该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值：100
trade_no String(30) N 银盛支付交易流水号
trade_status String Y 交易目前所处的状态。成功状态的值： TRADE_SUCCESS\ TRADE_CLOSED 示例值：附录8.1
account_date String（10） N 入账的时间，格式"yyyyMMdd" 示例值：20140724
openid String（128） N 子商户appid下用户唯一标识
payer_fee Number N 该笔订单的付款方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值：1.00
payee_fee Number N 该笔订单的收款方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值： 1.00
partner_fee Number N 该笔订单的合作方手续费(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值：1.00
fee Number N 该笔订单的手续费总和(参考)，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。示例值：1.00
coupon_info String N JSON字符串,银联营销渠道响应优惠信，version小于3.6版本为List的JSON字符串，3.6版本（含）以上为CouponInfo的JSON字符串
settlement_amount Number N 结算金额 示例值：100
channel_send_sn String(50) N 发往渠道流水号 示例值：12345678a
paygate_no String(16) N 支付网关编号 参考附录 示例值：10000
channel_recv_sn String(50) N 渠道返回流水号 示例值：12345678a
card_type String N 卡类型credit:信用卡debit:借记卡
buyer_user_id String N 支付宝用户Uid
buyer_logon_id String N 该字段于2023-9-1已不支持使用，请使用buyer_id对接，如有疑问请咨询银盛技术支持！
payer_bank_account_no String N 银联云闪付款方账号
is_discount String N 是否参与优惠,Y/N 版本3.3及以上支持
total_discount_fee double N 参考优惠手续费(汇总) 10.00；版本3.3及以上支持
total_discount double N 参考优惠金额(汇总) 10.00；版本3.3及以上支持
wxpay_coupon_info String N 微信优惠明细 版本3.3及以上支持 示例值：样例7.1
wxpay_coupon_good_detail List N 微信营销单品json 组 版本3.3及以支持 示例值：样例7.2
alipay_trx_resp_coupon_info String(4000) N 支付宝营销渠道响应优惠信息 JSON字符串，具体见6.5
ali_merchant_amount String N 支付宝商家优惠金额，版本号3.5及以上支持
ali_platform_dis_amount String N 支付宝平台优惠金额，版本号3.5及以上支持
ali_goods_details String(4096) N 支付宝营销渠道响应商品详情信息 JSON字符串，具体见6.6
preferential_amount Number N 营销优惠金额 版本3.9及以支持 示例值：样例1.2
preferential_fee Number N 营销优惠手续费 版本3.9及以支持 示例值：样例0.02
marketing_rule_json String N 营销规则信息json 版本3.9及以支持

6.1 wxpay_coupon_info（微信营销）

参数 类型(字节长度） 必填 参数说明
fee_type String(16) N 标价币种，默认CNY
total_fee double Y 标价金额，订单总金额，单位为元 12.00
cash_fee_type String(16) N 现金支付币种，默认CNY
cash_fee double Y 现金支付金额 ：订单现金支付金额（即客户实际付款金额），单位元 1.01
settlement_total_fee double N 现金支付金额：当订单使用了免充值型优惠券后返回该参数，应结订单金额=订单金额-免充值优惠券金额。单位元
coupon_fee double N 代金券金额：代金券”金额<=订单金额，订单金额-“代金券”金额=现金支付金额,单位元
ext String N 附录字段
promotionDetail String Y 单品优惠活动，详细信息如下 json

6.1.1 promotionDetail

参数 类型(字节长度） 必填 参数说明
promotion_id String(32) Y 券 ID券或者立减优惠ID 例 109519
name String(64) N 优惠名称 例 单品惠-6
scope String(32) N 优惠范围 GLOBAL- 全场代金券；SINGLE- 单品优惠 例 SINGLE
type String(32) N 优惠类型COUPON- 代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致）DISCOUNT- 优惠券，不走结算资金的免充值型优惠券，（境外商户券币种与标价币种一致 例 DISCOUNT
amount double Y 用户享受优惠的金额（优惠券面额=微信出资金额+商家出资金额+其他出资方金额 ），单位：元 例 5.00
activity_id String(32) N 活动 ID，在微信商户后台配置的批次 ID 例 931386
wxpay_contribute String(32) N 微信出资 特指由微信支付商户平台创建的优惠，出资金额 等于本项优惠总金额，单位为元 例 0.00
merchant_contribute String(32) N 商户出资 特指商户自己创建的优惠，出资金额等于本项优惠总金额，单位为元 例 0.00
other_contribute String(32) N 其他出资 其他出资方出资金额，单位为元 例 5.00

6.2 wxpay_coupon_good_detail（微信营销列表）

参数 类型(字节长度） 必填 参数说明
goods_id String(32) Y 商户商品编码 由半角的大小写字母、数字、中划线、下划线中的种或几种组成 例 109519
goods_remark String(128) N 商品备注 goods_remark 为备注字段，按照配置原样返回，字段内容在微信后台配置券时进行设置。例 1001
discount_amount double Y 商品优惠金额 单品的总优惠金额，单位为元 例 1.00
quantity Int Y 商品数量 用户购买的数量 例 11
price double Y 商品价格 单位为：元。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔 100 元的订单使用了商场发的纸质优惠券 100-50，则活动商品的单价应为原单价-50) 例 5288.00

6.3 银联 CupQrCouponDetail

参数 类型(字节长度） 必填 参数说明
spnsrId double Y 出资方,1：银联出资，2：付款方（比如银行）出资，3：商户出资offstAmt
offstAmt double Y 出资金额 ，单位为元

6.4 银联 CouponInfo

参数 类型(字节长度） 必填 参数说明
amount Double Y 清算金额 ，单位为元
origAmount Double Y 订单金额， 单位为元,商户提交的订单金额
cupQrCouponDetail List N 优惠信息-二维码,成功的二维码类交易交易必填，活动维度的优惠展示
issAddnData IssAddnData N 付款方附加数据,交易成功返回，商品维度的优惠展示
cupAcpCouponInfo CupAcpCouponInfo N 优惠信息全渠道,成功的全渠道类交易（如：Wap，手机控件 等）必填,活动维度的优惠展示

6.4.1 CupQrCouponDetail

参数 类型(字节长度） 必填 参数说明
spnsrId double Y 出资方，1：银联出资，2：付款方（比如银行）出资，3：商户出资offstAmt
offstAmt double Y 出资金额 ，单位为元

6.4.2 IssAddnData

参数 类型(字节长度） 必填 参数说明 样例
dctDetail List N 商品优惠信息 交易成功，且请求参数中的收款方附加信息域中的单品命中优惠。商品维度展示优惠信息。

6.4.2.1 DctDetail说明

参数 类型(字节长度） 必填 参数说明
id String Y 参与优惠的商品编号
dctId String Y 优惠活动的编号
dctQuantity int Y 商品优惠数量，本商品数量为 10，其中 2 件参示例：本商品数量为 10，其中 2 件参
dctPrice double Y 商品优惠金额，单位:元。示例：商品单价10元，共 5件，其中2件参与优惠，每件优惠 3元，则本字段值为 6.00
addnInfo String N 附加信息，内容自定义

6.4.3 CupAcpCouponInfo说明

参数 类型(字节长度） 必填 参数说明
discountAmt double Y 总的优惠金额,单位:元,注：退货的时候返回，表示总的优惠回退金额
mchtDiscountAmt double N 商户出资金额,单位:元,注：退货的时候返回，表示商户出资的回退金额
activityId String N 活动编号,票券编号、活动编号等，格式自定义
activityNm String N 活动简称,优惠活动简称，可用于展示、打单等
addnPrintInfo String N 活动打印信息,内容自定义

6.5 支付宝营销 alipay_trx_resp_coupon_info

参数 类型(字节长度） 必填 参数说明
total_amount double Y 订单金额 单位为元
receipt_amount double Y 商户实收金额 商家在交易中实际收到的款项， 单位为元
buyer_pay_amount double Y 用户实付金额 用户在交易中支付的金额，单位为元。
invoice_amount double Y 开票金额 用户在交易中支付的可开具发票的金额
point_amount double Y 集分宝支付金额 使用集分宝付款的金额
fund_bill_list List Y 支付金额信息
voucher_detail_list List N 本交易支付时使用的所有优惠券信息
gmt_payment String Y 交易支付时间 2014-11-27 15:45:57

6.5.1 AlipayTradeFundBill

参数 类型(字节长度） 必填 参数说明
fund_channel_str String Y 交易使用的资金渠道 示例值：ALIPAYACCOUNT
bank_code String N 银行卡支付时的银行代码 示例值：CEB
amount double Y 该支付工具类型所使用的金额 示例值：10.00
real_amount double N 渠道实际付款金额 示例值：11.21
fund_type_str String N 集分宝支付金额 示例值：11.21

6.5.2 VoucherDetail 说明

参数 类型(字节长度） 必填 参数说明
id String Y 券 id,示例值：必填
name String Y 券名称
type_str String Y 券类型 示例值：ALIPAY_FIX_VOUCHER
amount double Y 优惠券面值
merchant_contribute double N 商家出资
other_contribute double N 其他出资方出资金额
memo String N 优惠券备注信息
template_id String N 卷模板id 示例值：20171030000730015359000EMZP0
other_contribute_detail List N List 优惠券的其他出资方明细
purchase_buyer_contribute double N
purchase_merchant_contribute double N
purchase_ant_contribute double N

6.6 支付宝营销 ali_goods_details

参数 类型(字节长度） 必填 参数说明
id String(64) Y 记录编号，唯一标识
tradesn String(30) Y 银盛交易流水
seq Integer(4) Y 银盛交易流水序列号
createtime String Y 创建时间 2014-11-27 15:45:57
wxpayGoodsId String(32) N 渠道单品标识
goodsName String(256) N 营销单品名称
goodsId String(32) Y 营销单品标识
goodsRemark String(256) N 营销单品备注
quantity NUMBER(10) N 营销单品数量
price NUMBER(15,4) N 营销单品价格
type String(32) N 记录类型 参考 下表类型
discountAmount NUMBER(15,4) Y 抵扣金额
goodsDetailJson String(3000) N 单品营销参数JSON字符串

7、样例

7.1 wxpay_coupon_info

{
    "cash_fee": 22.09,
    "cash_fee_type": "CNY",
    "coupon_fee": 4,
    "fee_type": "CNY",
    "promotionDetails": [{
        "activity_id": "72560",
        "amount": 4,
        "merchant_contribute": 0,
        "name": "21--30 单品免充 4",
        "other_contribute": 4,
        "promotion_id": "0219457",
        "scope": "SINGLE",
        "type": "DISCOUNT",
        "wxpay_contribute": 0
    }],
    "settlement_total_fee": 22.09,
    "total_fee": 26.09
}

7.2 wxpay_coupon_good_detail

{
    "discount_amount": 4,
    "goods_id": "11111",
    "goods_remark": "商品名称",
    "price": 26.1,
    "quantity": 1
}

7.3 coupon_Info 银联优惠

[{
    "spnsrId": "1",
    "offstAmt": 1
}, {
    "spnsrId": "2",
    "offstAmt": 2
}]

8、附录

8.1 交易状态

枚举名称 枚举说明
WAIT_BUYER_PAY 交易创建，等待买家付款。
TRADE_CLOSED 在指定时间段内未支付时关闭的交易；客户主动关闭订单。
TRADE_SUCCESS 交易成功，且可对该交易做操作，如：多级分润、退款等。
TRADE_PART_REFUND 部分退款成功。
TRADE_ALL_REFUND 全部退款成功。
WAIT_SELLER_SEND_GOODS 买家已付款，等待卖家发货
WAIT_BUYER_CONFIRM_GOODS 卖家已发货，等待买家确认

8.2 参考错误码

错误码 错误描述 解决方案
ACQ.SYSTEM_ERROR 系统错误 请调用查询接口查询订单状态
ACQ.CONNECT_PAYGATE_TIME_OUT 业务超时 请调用查询接口查询订单状态
ACQ.INVALID_PARAMETER 参数无效 检查请求参数，修改后重新发起请求

8.3 支付网关编号

支付渠道代码 支付渠道
900000001 银联-支付宝
9000010 银联-微信
10810001 银联扫码-银联云闪付
10010001 网联-微信
10000012 网联-支付宝

results matching ""

    No results matching ""