微信公众号&小程序

1、修订记录

修订 日期 说明 作者
0.1 2020/06/08 新接口参数定义 邓文泉
0.2 2021/08/08 单品信息中增加 promotionId
0.3 2021/08/12 删除支付宝，银联等参数
0.4 2021/08/13 删除mer_amount
0.5 2021/09/13 删除 province/city
0.6 2021/12/27 支持国密 王晶
0.7 2022/02/17 seller_name修改为非必填 王晶
0.8 2022/03/17 version为3.9时 新增支付成功异步通知营销相关字段 刘雷
0.9 2022/03/18 新增银联259号文条码改造相关字段 刘雷
1.0 2022/07/05 新增实名认证信息 刘雷
1.2 2022/07/27 新增付款方gps信息和付款方ip入参 王晶
1.3 2023/01/09 新增同步响应参数发往渠道流水号channel_send_sn 林竞
1.4 2024/01/12 terminal_ip字段长度限制由8改为64位 康少雄
1.5 2024/07/26 新增请求参数goods_tag订单优惠标记 陈思达
1.6 2024/11/04 新增请求参数merchant_marketing_info商户自主营销信息 郑世康

2、业务说明

（1）场景说明

商户已有H5商城网站，用户通过消息或扫描二维码在微信内打开网页时，可以调用银盛支付微信公众号&小程序下单接口完成下单购买的流程。

（2）接口说明

1、该接口支持微信公众号、微信小程序支付，通过参数”is_minipg“区分；

2、调用接口前，商户需要先在微信侧 申请公众号或小程序的APPID等参数； 3、商户调用该接口生成预支付交易单，银盛支付将返回预支付参数；商户根据返回的预支付参数，通过JSAPI唤起支付。

3、请求地址

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

4、请求参数说明

4.1公共请求参数

参数 类型(字节长度） 必填 参数说明
method String(128) Y 接口名称 固定值 ysepay.online.weixin.pay
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(190) Y 交易成功异步通知到商户的后台地址，http路径支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3，支持TLS1.0、TLS1.1、TLS1.2
version String(3) Y 接口版本3.0/3.4 当前版本 3.4
tran_type String(1) N 交易类型，说明：1或者空：非担保交易，2：担保交易，无特殊需求 不用填此字段
biz_content String Y 业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递

4.2 业务请求参数

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

参数 类型(字节长度） 必填 参数说明
out_trade_no String(1,32) Y 商户系统生成的订单号，须保证在商户端不重复，生成规则前8位必须为交易日期，如20220525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成，示例值：202205256843192280647118
shopdate String(8,8) N 商户系统的交易发生日期格式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
extra_common_param String(2000) N 公用回传参数 商户自定义数据域，原样返回
business_code String(1,10) Y 业务代码 ，请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码
sub_openid String(128) Y 用户在商户appid下的唯一标识。可参考https://pay.weixin.qq.com/wiki/doc/apiv3/terms_definition/chapter1_1_3.shtml#part-3获取
is_minipg String(1) N 【微信小程序支付：1】，【 微信公众号支付：2或不传】
appid String(32) Y 商户在微信侧申请的小程序或公众号APPID。当发起公众号支付时，需填写公众号的APPID(应用ID)；当发起小程序支付时，需填写小程序的APPID(应用ID)
sub_merchant SubMerchantInfo N 二级商户信息, Json格式，暂包括merName、merShortName、merAddr、mobileNo、merNo、category、mrchntCertId，如果有值则二级商户信息都不能为空，如果没值则都不能有值
consignee_info ConsigeeInfo N 收货人信息json格式
limit_credit_pay String(2) N 是否限制信用卡支付。值为1表示禁用信用卡支付，0或为空表示不限制
allow_repeat_pay String(2) N 是否允许多次支付,Y：允许;N：不允许（参数为空或者Y时，默认该笔订单交易状态非成功状态时，支持选择其他支付方式继续付款， 当为N时表示该笔订单交易状态为失败状态时，不支持选择其他支付方式继续付款）
fail_notify_url String(190) N 失败通知地址（交易状态为失败时，银盛通知商户网站里指定的页面http路径，支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3）注：只有不允许重复支付的交易才会通知
detail String(6000) N 微信商品详情，单品优惠活动 参考 detail附录
submer_ip String(16) N 请求方ip 112.112.112.112
union_qrcode_259_params UnionQrCodeBaseRequest N 银联259号文条码改造字段，json格式
buyer_realname_info buyer_realname_info N 实名认证信息 :有证件类型、证件姓名、证件号，非必填，如果三个字段一个填写就都必填，要么就都不上送
gps GpsInformation N 付款方gps信息 ,结构见4.2.6
payer_ip String N 付款方ip
merchant_marketing_info String N 商户自主营销信息，json格式。coupon_id优惠券id、marketing_source_id营销来源id，示例值：merchant_marketing_info: {"coupon_id": "231", "marketing_source_id": "23232" }

4.2.1 二级商户 SubMerchantInfo

参数 类型(字节长度） 必填 参数说明
merName String(50) N 二级商户名称,支持25个中文
merShortName String(50) N 二级商户简称,支持25个中文
merAddr String(200) N 二级商户地址,支持100个中文
telephone String(13) N 固定电话/手机号码二选一
merNo String(32) N 二级商户编号
category String(20) N 类目，按附件内容输入类目编号
mrchntCertId String（15,18） N 身份证号,只支持身份证格式(如果签名方式为RSA，则用DES加密，密钥为商户号前8位，不足8位在商户号前补空格；如果签名方式为SM，则用SM加密)

4.2.2 收货人信息 ConsigeeInfo

参数 类型(字节长度） 必填 参数说明
consigneeName String(150) N 收货人姓名
consigneeAddr String(200) N 收货地址
transportationInfo String(200) N 物流配送信息（物流名称+订单号）
commodityName String(150) N 商品名称
commodityNumber String(10) N 商品数量,

4.2.3 detail 微信单品优惠活动

参数 类型(字节长度） 必填 参数说明
cost_price double N 订单原价，整数不超过14位，小数不 超过2位，单位元 10．50
receipt_id String(32) N 商品小票ID，长度不能超过32位 Ys001001
goods_tag String(32) N 订单优惠标记，代金券或立减优惠功能的参数
goods_detail List Y 商品列表

4.2.3.1 goods 微信商品列表

参数 类型(字节长度） 必填 参数说明
goods_id String(32) Y 商户商品编码,由半角的大小写字母，数字，下划线，中划线中的一种或者几种组成，长度不能超过32位 Shouji_abcef_001-001
wxpay_goods_id String(32) N 微信支付定义的统一商品编号，长度不能超过32 ,1001
goods_name String(256) N 商品的实际名称，长度不能超过256
quantity int(10) Y 数量，只能是正整数 ,1000
price Double Y 商品单价，单位元，整数部分不能超过12位，小数不能超过2位 , 100.20

4.2.4 银联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(64) O 商户端终端设备 IP 地址。注：如经、维度信息未上送，该字段必送。
encryp_rand_num String(10) N 加密随机因子
secret_text String(16) N 密文数据

4.2.5 购买人实名认证信息 buyer_realname_info

参数 类型(字节长度） 必填 参数说明
id_no String Y 证件号,只支持身份证格式(如果签名方式为RSA，则用DES加密，密钥为商户号前8位，不足8位在商户号前补空格；如果签名方式为SM，则用SM加密)
id_type String Y 证件类型，只支持身份证，枚举值：1
id_name String Y 证件姓名

4.2.6 付款方GPS信息 GpsInformation

参数 类型 必填 参数说明
latitude Double N 纬度，范围-90~90
longitude Double N 经度，范围-180~180

5、响应参数说明

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

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

5.1 公共响应参数

参数 类型(字节长度） 必填 参数说明
sign String Y 签名字符串，Base64编码
ysepay_online_weixin_pay_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
extra_common_param String(2000) N 公用回传参数 商户自定义数据域，原样返回
jsapi_pay_info String Y Json格式字符串，作用于原生态的js支付时的参数
is_discount String N 是否参与优惠，Y表示参与，N表示不参与
total_discount double N 参考总优惠金额 100．00
channel_send_sn String(50) N 发往渠道流水号

5.3 jsapi_pay_info 支付串

参数 类型(长度） 必填 参数说明
appId string[1,32] Y 商户在微信侧申请的APPID，接口返回jsapi_pay_info中的信息 wxd678efh567hg6787
timeStamp string[1,32] Y 时间戳，接口返回jsapi_pay_info中的信息
nonceStr string[1,32] Y 随机字机串，接口返回jsapi_pay_info中的信息 5K8264ILTKCH16CQ2502SI8
package string[1,128] Y 订单详情扩展字符串，接口返回jsapi_pay_info中的信息 prepay_id=u802345jgfjsdfg
signType string[1,32] Y 签名方式，接口返回 jsapi_pay_info中的信息 MD5
paySign string[1,256] Y 签名，接口返回jsapi_pay_info中的信息 C380BEC2BFD727A4B6845132

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

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

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

参数 类型(字节长度） 必填 参数说明
sign_type String Y 签名类型 默认 RSA
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(20) N 银盛支付交易流水号
trade_status String Y 交易目前所处的状态。成功状态的值： TRADE_SUCCESS TRADE_CLOSED等具体详情看下文中的交易状态详解
account_date String（10） N 入账的时间，格式"yyyyMMdd" 20140724
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
channel_send_sn String(50) N 发往渠道流水号 12345678a
paygate_no String(16) N 支付网关编号 (9000010)银联-微信 (10010001)网联-微信
channel_recv_sn String(50) N 渠道返回流水号 12345678a
card_type String N 卡类型credit:信用卡debit:借记卡
extra_common_param String(2000) N 公用回传参数 商户自定义数据域，原样返回
is_discount String N 是否参与优惠，Y表示参数，N表示不参与
total_discount double N 参考汇总优惠金额 100．00
wxpay_coupon_info String N 微信优惠活动优惠明细 Json 参考 附录及定义
wxpay_coupon_good_detail List N 微信优惠活动单品信息 Json 参考 附录及定义
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- 单品优惠
type String(32) N 优惠类型COUPON- 代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致）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
promotionId String(32) Y 券或者立减优惠id 关联 promotionDetail.promotion_id

7、样例

7.1 detail 字段值

//注意goods_detail字段的格式为"goods_detail":[{}],较多商户写成"goods_detail":{}
{
    "cost_price":608800, 
    "receipt_id":"wx123", 
    "goods_detail":[
        {
            "goods_id":"商品编码", 
            "wxpay_goods_id":"1001", 
            "goods_name":"", 
            "quantity":1, 
            "price":528800
        }, 
        {
            "goods_id":"商品编码", 
            "wxpay_goods_id":"1002", 
            "goods_name":"iPhone6s 32G", 
            "quantity":1, 
            "price":608800
        }
    ]
}

7.2 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.3 wxpay_coupon_good_detail

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

7.4 二级商户 sub_merchant

{
    "merName": "二级商户名称",
    "merShortName": "二级商户简称",
    "merAddr": "二级商户地址",
    "mobileNo": "二级商户服务电话",
    "merNo": "二级商户编号",
    "category": "类目",
    "mrchntCertId": "身份证号"
}

7.5 收货人信息 consignee_info

{
    "consigneeName": "收货人姓名",
    "consigneeAddr": "收货地址",
    "transportationInfo": "物流配送信息",
    "commodityName": "商品名称",
    "commodityNumber": "商品数量"
}

8、附录

8.1 交易状态

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

results matching ""

    No results matching ""