聚合收银台异步通知
1、修订记录
| 修订记录 |
日期 |
说明 |
| 1.0 |
2024.02.28 |
初版 |
2、业务说明
2.1、接口说明
银盛支付对商户的请求数据处理完成后，会将处理成功的数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。
注意：
1、接入方接受异步通知结果后，返回success表示该次异步通知成功，银盛将会按成功处理该次异步通知。
2、接入方接收到异步通知后，同步返回非success，银盛认为该次异步通知失败了，银盛将会再通知5次，间隔频率分别为1分钟、5分钟、10分钟、30分钟、60分钟共5次通知。凡是其中一次返回success银盛将会终止通知。
3、同样的通知可能会多次发送给接入方（例如调用接入方超时，接入方返回失败等）。
2.2、接入方接受异步通知接口的要求：
1、接受方式：POST
2、接受主体类型：application/json
3、需要对通知的数据进行验签，验签使用公钥验签，详见demo
4、必须要有一个返回值 该值为String类型。
5、接入方必须能够正确处理重复的通知，以避免函数重入造成的数据混乱。
3、异步通知报文结构
3.1、公共请求参数
| 参数 |
类型(长度） |
必填 |
参数说明 |
| timeStamp |
String |
Y |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
| src |
String |
Y |
异步通知来源，固定"pregate" |
| reqId |
String |
Y |
请求流水号 |
| charset |
String(10) |
Y |
编码格式 固定为UTF-8 |
| sign |
String |
Y |
签名，需要银盛公钥验签,详见demo |
| bizContent |
String |
Y |
业务响应数据 json字符串 |
3.2、业务请求参数
（bizContent加密前的json数据明文字符串）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| mercId |
String |
Y |
商户号 |
| orderId |
String |
Y |
订单号 |
| amount |
Number |
Y |
交易金额(单位:元) |
| currencyCode |
String |
Y |
币种 |
| tradeSn |
String |
Y |
交易流水号 |
| payerInfo |
String |
N |
付款方信息 |
| settlementAmt |
Number |
Y |
结算金额 |
| payAmt |
Number |
Y |
买家付款金额 |
| payTime |
String |
Y |
交易支付时间 |
| channelSendSn |
String |
Y |
发往渠道流水 |
| channelRecvSn |
String |
Y |
渠道返回流水 |
| buyerLogonId |
String |
N |
支付宝账号(支付宝交易时返回) |
| remark |
String |
N |
备注 |
| srcFee |
Number |
N |
发起方手续费 |
| payeeFee |
Number |
N |
收款方手续费 |
| payerFee |
Number |
N |
付款方手续费 |
| payMode |
String |
N |
支付方式 |
| accountDate |
String |
N |
会计日期(yyyyMMdd) |
| dctGoodsInfo |
String |
N |
单品优惠信息 3.2.4 单品优惠信息（dctGoodsInfo） |
| couponInfo |
String |
N |
银联优惠信息 3.2.3 支付宝优惠信息（couponInfo） |
| alipayTrxRespCouponInfo |
String |
N |
支付宝优惠信息 3.2.2 支付宝优惠信息（alipayTrxRespCouponInfo） |
| wxpayCouponInfo |
String |
N |
微信优惠信息 3.2.1 微信优惠信息（wxpayCouponInfo） |
| srcUserCode |
String |
N |
发起方用户号 |
| busiCode |
String |
N |
业务代码
00510102-聚合收银台D0；
00510103-聚合收银台；
|
| totalDiscountAmt |
Number |
N |
总优惠金额（元） 备注：总优惠金额 = 支付宝优惠金额+微信优惠金额+银联优惠金额+营销系统优惠金额+自主营销优惠金额 |
| yscouponInfo |
String |
N |
包含营销系统的所有营销信息 |
| openId |
String |
N |
微信交易的用户信息 |
| userId |
String |
N |
支付宝、银联云闪付交易的用户信息 |
| payerBankaccountType |
String |
N |
付款方卡类型。
credit:信用卡 debit:借记卡 |
| note |
String |
N |
订单说明 |
3.2.1、微信营销（wxpayCouponInfo）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| fee_type |
String |
N |
标价币种，默认人民币CNY |
| total_fee |
Double |
Y |
标价金额，订单总金额，单位为元 例:12.00 |
| cash_fee_type |
String |
N |
现金支付币种，默认CNY |
| cash_fee |
Double |
Y |
现金支付金额 ：订单现金支付金额（即客户实际付款金额），单位元, 例: 1.01 |
| settlement_total_fee |
Double |
N |
应结订单金额：当订单使用了免充值型优惠券后返回该参数，应结订单金额=订单金额-免充值优惠券金额。单位元 |
| coupon_fee |
Double |
N |
代金券金额<=订单金额，订单金额-代金券金额=现金支付金额,单位元 |
| ext |
String(32) |
N |
附录字段 |
| promotionDetail |
String |
N |
单品优惠活动，详细信息如下json 参考：3.2.1.1. 单品优惠活动信息（promotionDetail） |
3.2.1.1. 单品优惠活动信息（promotionDetail）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| promotion_id |
String |
Y |
券或者立减优惠 id |
| name |
String |
N |
优惠名称 |
| scope |
String |
N |
GLOBAL- 全场代金券;SINGLE- 单品优惠 |
| type |
String |
N |
COUPON- 代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致）DISCOUNT- 优惠券，不走结算资金的免充值型优惠券，（境外商户券币种与标价币种一致 |
| amount |
double |
N |
用户享受优惠的金额（优惠券面额=微信出资金额+商家出资金额+其他出资方金额 ） |
| activity_id |
String |
N |
在微信商户后台配置的批次 ID |
| wxpay_contribute |
double |
N |
特指由微信支付商户平台创建的优惠，出资金额 等于本项优惠总金额，单位为元 |
| merchant_contribute |
double |
N |
特指商户自己创建的优惠，出资金额等于本项优惠总金额，单位为元 |
| other_contribute |
double |
N |
其他出资方出资金额，单位为，单位为元 |
3.2.2、支付宝优惠信息（alipayTrxRespCouponInfo）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| total_amount |
Double |
Y |
单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| receipt_amount |
Double |
Y |
商家在交易中实际收到的款项，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| buyer_pay_amount |
Double |
N |
用户在交易中支付的金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| invoice_amount |
Double |
N |
用户在交易中支付的可开具发票的金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| point_amount |
Double |
N |
使用集分宝付款的金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| fund_bill_list |
Array |
Y |
支付金额信息 参考：3.2.2.1. 支付金额信息（AlipayTradeFundBill） |
| discount_goods_detail |
Array |
N |
本次交易支付所使用的单品券优惠的商品优惠信息 参考：3.2.2.2. 商品优惠信息（DiscountGoodsDetail） |
| voucher_detail_list |
Array |
N |
本交易支付时使用的所有优惠券信息 参考：3.2.2.3. 优惠券信息（VoucherDetail） |
| gmt_payment |
String |
Y |
交易支付时间 |
3.2.2.1. 支付金额信息（AlipayTradeFundBill）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| fund_channel_str |
String |
Y |
交易使用的资金渠道 |
| bank_code |
String |
N |
银行卡支付时的银行代码 |
| amount |
double |
Y |
该支付工具类型所使用的金额 |
| real_amount |
double |
N |
用户在交易中支付的可开具发票的金额 |
| fund_type_str |
String |
N |
渠道所使用的资金类型,目前只在资金渠 道 (fund_channel) 是 银 行 卡 渠 道(BANKCARD)的情况下才返回该信息。DEBIT_CARD:借记卡CREDIT_CARD:信用卡MIXED_CARD:借贷合一卡 |
3.2.2.2. 商品优惠信息（DiscountGoodsDetail）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| goodId |
String(32) |
Y |
商品的编号 |
| discountAmount |
Double |
Y |
单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| voucherId |
String(32) |
Y |
卷id |
3.2.2.3. 优惠券信息（VoucherDetail）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| id |
String |
Y |
券 id |
| name |
String |
Y |
券名称 |
| type_str |
String |
Y |
券类型，当前有三种类型: ALIPAY_FIX_VOUCHER - 全场代金券 ；ALIPAY_DISCOUNT_VOUCH ER- 折扣券；ALIPAY_ITEM_VOUCHER-单品优惠注：不排除将来新增其他类型 的可能，商家接入时注意兼容性避免硬编码 |
| amount |
Double |
Y |
优惠券面额，它应该会等于商家出资加上其他出资方出资，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| merchant_contribute |
Double |
N |
商家出资, 特指发起交易的商家出资金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| other_contribute |
Double |
N |
其他出资方出资金额, 可能是支付宝， 可能是品牌商， 或者其他方， 也可能是他们的一起出资，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| memo |
String |
N |
优惠券备注信息, 学生专用优惠 |
| template_id |
String |
N |
卷模板id |
| other_contribute_detail |
Array |
N |
优惠券的其他出资方明细 参考：3.2.2.3.1. 优惠券的其他出资方明细（ContributeDetail） |
| purchase_buyer_contribute |
Double |
N |
用户实际付款的金额, 如果使用的这张券是用户购买的， 则该字段代表用户在购买这张券时用户实际付款的金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| purchase_merchant_contribute |
Double |
N |
商户优惠的金额, 如果使用的这张券是用户购买的， 则该字段代表用户在购买这张券时商户优惠的金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
| purchase_ant_contribute |
Double |
N |
平台优惠的金额, 如果使用的这张券是用户购买的， 则该字段代表用户在购买这张券时平台优惠的金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
3.2.2.3.1、 优惠券的其他出资方明细（ContributeDetail）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| contribute_type |
String |
Y |
出资方类型, 如品牌商出资、支付宝平台出资等 |
| contribute_amoun |
Double |
Y |
券名称, 出资方金额，单位为RMB-Fen。取值范围为[1，1000000000]，整数。Stirng(1,10)指10位长度 |
3.2.3、银联优惠信息（couponInfo）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| amount |
String |
N |
清算金额 |
| origAmount |
Double |
Y |
订单金额 |
| ext |
String |
Y |
银联返回优惠信息原文 |
| cupQrCouponDetail |
Array |
Y |
优惠明细 参考：3.2.3.1. 优惠明细（CupQrCouponDetail） |
3.2.3.1、 优惠明细（CupQrCouponDetail）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| type |
String |
Y |
项目类型 |
| spnsrId |
String |
Y |
银联作为出资方：固定 填写 00010000,付款方作为出资：：填写 8位付款 方机 构代码 ；商户 作为出资方：填写 15 位商户代码 商户代码 |
| offstAmt |
Double |
Y |
抵消交易金额 |
| id |
String |
N |
用于票券编号等,格式自定义 |
| desc |
String |
N |
优惠活动简称 |
| addnInfo |
String |
N |
附加信息 |
3.2.4、单品优惠信息（dctGoodsInfo）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| goods_id |
String |
Y |
由半角的大小写字母、数字、中划线、下划线中的种或几种组成 |
| goods_remark |
String |
N |
goods_remark 为备注字段，按照配置原样返回，字段内容在微信后台配置券时进行设置。 |
| discount_amount |
String |
Y |
单品的总优惠金额，单位为元 |
| quantity |
int |
Y |
用户购买的数量 |
| price |
double |
Y |
单位为：元。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔 100 元的订单使用了商场发的纸质优惠券 100-50，则活动商品的单价应为原单价-50) |
| goodsDetailJson |
String |
N |
营销单品详情JSON串 |
| promotionId |
String |
N |
券id |
4、接入方返回值定义
接入方返回参数为String，不返回和非success都为失败，如果接入方处理失败，可以返回处理失败原因，以供查找问题