智慧门店
支付链路对接
1. 支付链路接入方案
1.1 对接智慧门店支付链路的几种场景
| 门店收银场景 | 直连/间连 | 是否可以对接智慧门店支付链路 | 对接方案 | 支付接口 |
|---|---|---|---|---|
| 不支持支付宝收银 | / | 否 | / | / |
| 百货收银 | / | 否 | / | / |
| 消费者支付宝主扫门店静态二维码 | / | 否 | / | / |
| 消费者支付宝主扫门店动态二维码直接付款 | 直连 | 是 | 主扫方案+直连 | alipay.trade.precreate |
| 间连 | 是 | 主扫方案+间连转直连 | ||
| 导购员用POS系统的把枪或者独立收银机具 |
直连 | 是 | 被扫方案+直链 | alipay.trade.pay |
| 间连 | 是 | 被扫方案+间连转直连 |
说明：
1）关于直连/间连，主扫与被扫的详细介绍，可点击这里查看。
2. 开发者需要做什么
2.1 POS的工作
- 支付宝当面付接口增加商品id、门店id、商品单价、商品个数、商品名称
- 门店优惠券、购物津贴（商家出资）和红包（平台出资）的使用，收银小票需展示出资内容，订单记录优惠信息用于对账
- 逆向流程，带有门店优惠券、津贴、红包等优惠的订单退款金额由POS计算
- 逆向接口POS需传入商品信息
2.2 门店商品管理
- 门店商品的增删改查功能开发
2.3 整体对接排期计划建议
3. 系统架构图
4.系统对接
4.1对接流程
说明：
1）蓝色是商家新增要做的事情，绿色是POS开发者要做的事情，灰色是选做的事情；
2）手机淘宝的会员码和支付宝的支付码本质上是完全一样的，扫的效果也是完全一样的；
3）关于扫码识别身份的说明：
a. 扫码识别身份（可返回加密手机号）的业务场景类似消费者到店后通过报手机号的方式确认是否是会员，即报手机号识别身份，变为扫码识别身份；
b. 扫码识别身份需要系统对接，由POS将扫到的串码提供给CRM，CRM与平台发生交互确认会员身份。详细的对接介绍，可查看本文档下面的“会员码身份识别接口”的介绍。因为该功能有一定的技术对接成本，是非必做功能。
c. 流程图中，出现了两次出示支付码，第一次用于身份识别，第二次用于支付（都是同一个码），动态支付码的有效期是1分钟，如果商家选择要做身份识别+支付，方案：a）可以如流程图中扫两次，第一次识别会员，第二次才是支付；2）也可以在1分钟内通过扫一次码完成身份识别与支付。前者的好处是避免导购误操作，消费者仅仅想查查会员信息，并不想支付，是身份识别还是支付导购的行为目的非常明确。
4.2 支付宝当面付下单接口调整
4.2.1 消费者被扫模式（导购用把枪扫消费者支付码）
接口：alipay.trade.pay
接口名称：统一收单交易支付接口
4.2.1.1 入参说明
1. 智慧门店支付链路前提条件是门店具备支付宝当面付收银能力。该接口属支付宝开放平台API。
2. 入参增加5个字段：
| 子参数名称 | 子参数说明 | 是否可空 |
|---|---|---|
| store_id | 商家门店编码，对应智慧门店后台的门店自用编码 | 不可空 |
| goods_id | 商户自定义的商品编号，需要与在智慧门店发布商品传入的SKU外部商品编号一致 | 不可空 |
| goods_name | 商户自定义的商品名称，注意编码格式与调用接口指定的编码一致 | 不可空 |
| quantity | 本次交易购买该商品的数量 | 不可空 |
| price | 商品单价，单位元，商品优惠前的价格。商品单价x数量的累加金额＝订单总金额（不做强行校验） | 不可空 |
3. 关于total_amount、quantity和price
| 场景 | total_amount | 商品A | 商品B | 智慧门店订单展示 | ||||
|---|---|---|---|---|---|---|---|---|
| / | / | price | quantity | price | quantity | 商品A的总金额 | 商品B的总金额 | 填充商品 |
| 场景一： total_amount=∑price*quantity |
10 | 3 | 2 | 4 | 1 | 6 | 4 | / |
| 场景二： total_amount<∑price*quantity |
8 | 3 | 2 | 4 | 1 | 8*6/(6+4)=4.8 | 8*4/(6+4)=3.2 | / |
| 场景三： total_amount>∑price*quantity |
12 | 3 | 2 | 4 | 1 | 6 | 4 | 2 |
4. 关于合单：对于相同的商品不同的价格(比如第一件100，第二件半价)，POS可以自己合并传quantity=2，price=75，也可以POS传两条商品记录，相同的good_id不同price，平台来合并。如果POS未传price字段，平台根据商品吊牌价通过订单总价进行按商品价格比例均摊。
5. 对于undiscountable_amount不打折金额字段：该字段接口文档中未透出，如果使用了该字段则不能享受优惠，请知晓。场景：在商户收银的时候在收银台里面输入不打折金额，然后扫码枪扫用户，这个不打折金额就不能参与优惠。
6. 关于支付宝的无可打折金额问题：支付宝不可打折金额仅在支付宝侧生效，但对于智慧门店优惠券不会生效。举例：订单金额100，支付接口中不可打折金额undiscountable_amount=10，如果在支付宝侧有张100减10的券，那是使用不了的，因为可打折金额是90(订单金额-不可打折金额)，没达到券的门槛。而智慧门店订单是根据消费者实付金额来判断是否满足门槛，如果有张100-10的券，那是可以使用的。请商户注意，避免出现资损！
4.2.1.2 出参说明
1. 智慧支付链路增加可优惠券、购物津贴、红包的玩法，统一有平台来判断是否可核销，具体玩法说明说下：
| 优惠类型 | 优惠类型的说明 | 是否付钱给商家 | 是否可退 | 支付宝接口返回字段 fund_bill_list.fund_channel |
|---|---|---|---|---|
| 智慧门店优惠券 | 商家出资，形式：满减券，支持全场满减，也支持指定门店指定商品(小于3000)满减 | 否 | 否 | MDISCOUNT |
| 智慧门店购物津贴 | 商家出资，形式：每满N减n，例如每满300减30，买600则减60（前提是买家手里的津贴大于60） | 否 | 是 | MDISCOUNT |
| 智慧门店红包 | 平台出资，形式：类似支付宝的鼓励金，可当钱花 | 是 | 是 | DISCOUNT |
4.2.1.3 详细的支付宝接口升级方案
支付宝当面付接口升级智慧门店的补充介绍可参看：智慧门店当面付升级指引。
4.2.2 消费者主扫模式（生成订单二维码，买家扫码）
接口：alipay.trade.precreate
接口名称：统一收单线下交易预创建
说明：
1. 字段调整参考4.2.1章节的说明。
2. 支付结果的返回信息参看，当面付异步通知-仅用于扫码支付，字段说明参看4.2.1章节。
4.4 支付宝退款接口的调整
接口：alipay.trade.refund
接口名称：统一收单交易退款接口
说明：
1. 退款接口先前是没有商品信息字段的，该项目新增了商品信息字段，建议回传，避免后续业务场景需要再做二次开发。
2. 智慧门店增加了优惠场景，带有智慧门店优惠的订单的退款，退款金额需要POS做计算后退回。建议走整单退，如果选择支持部分，退款金额出现资损由商家自己承担：
1）整单退：传入订单总金额（total_amount）即可，平台会判断哪些出资渠道可原路退，哪些券是可退，哪些券不能退，参看上面的券类型表格；
2）部分退：举例，订单应收total_amount=100，商品A价格60元，商品B价格40元，使用优惠券10元，买家实付90元。解决方案：
方案一：买家想退商品A，则POS退款金额填写60元，平台退60元，如果消费者想再退商品B，则POS退款金额填写40元，平台判断可退最大金额退款，即100-10-60=30，最终退给消费者30元。该方案处理相对简单，缺点是仅退第一件可能存在资损。
方案二：根据优惠金额POS做单品价格均摊后告知支付宝退款多少，退商品A则退款(100-10)*60/(60+40)=54，退商品B则退款(100-10)*40/(60+40)=36。
方案三：整单退后重新下单。
3. 退款的可退金额规则：
假设场景如下：正向交易下单，购买两件商品分别是商品A97元和商品B3元，应收金额100元，买家有8元津贴、10元优惠券和5元红包，消费者实付77元，智慧门店优惠券不可退、红包和津贴可退。
| 退款方式 | 退款金额 refund_amount |
买家支付宝 原路退款 |
优惠券退回 | 红包退回金额 | 购物津贴 |
|---|---|---|---|---|---|
| 整单退 | 100 | 77 | 不退 | 5 | 8 |
| 部分退-津贴满足则可退 | 97 | 77 | 不退 | 5 | 8 |
| 部分退-津贴不足则不退 | 89 | 77 | 不退 | 5 | 0 |
| 部分退-红包可拆分退 | 80 | 77 | 不退 | 3 | 0 |
| 部分退-不足实付随意退 | 60 | 60 | 不退 | 0 | 0 |
| 超额退 | 101 | 不可退 | 不可退 | 不可退 | 不可退 |
注：
1）退款的优先级顺序：实付>红包>购物津贴>优惠券
5.其他
5.1 支付宝相关问题开发者大群
具体智慧门店当面付升级对接细节，请开发者扫码加入开发者大群咨询，特别说明：用钉钉扫描，钉钉账号需要与支付宝账号对应一致的手机号。
5.2 智慧门店订单是否会推送到聚石塔？
为了避免对ERP系统的影响，平台目前暂不通过消息推送、TMC消息和订单详情API（taobao.trade.fullinfo.get）开放门店订单，但是通过taobao.trades.sold.get、taobao.trades.sold.increment.get获取订单列表时，可以拉取到门店订单的列表，但通过订单号去调用fullinfo.get无法获取到订单详情。
对于有在调用taobao.trades.sold.get、taobao.trades.sold.increment.get的商家，解决方案：两个接口中分别增加is_o2o_passport字段，返回值：true、null；如果返回true,则表示此订单为passport订单。isv在调用taobao.trades.sold.get、taobao.trades.sold.increment.get两个接口，监测is_o2o_passport字段是否为true，若为true，则屏蔽该订单，若为null，则正常处理。注意订单类型选择o2o_offlinetrade（O2O交易）。
5.3 会员码身份识别接口
tmall.mei.crm.member.getbypaycode，该接口是会员通接口，前提条件是授权的账号已经入驻会员通，POS扫码识别消费者身份的对接方案有三种，商家根据自己的情况选择最合适的方案：
1. 每笔交易前POS用会员身份标识字段去CRM查询会员信息：该场景只需要门店POS将会员码串号发给CRM，由CRM调用该接口查询返回会员信息给POS。
2. POS与CRM没有实时同步，哪一方有变更后再同步给对方以保证数据同步，该场景需要POS本地查询会员信息，POS通过会员码串号调用该接口获取加密手机号进行身份识别。需要POS服务商从商家那里拿到会员通商家密钥（商家如果不知道如何拿可以咨询CRM）。
3. 商家没有CRM只用POS来管理会员：该场景需要POS服务商另外申请会员通应用，拿到手机号加密算法，进行身份识别，即POS替代了CRM的工作。
出于安全考虑，消费者手机号在特定情况下仅能提供加密手机号，如何识别这个人的身份？ISV可以通过使用相同加密算法，进行双向加密后匹配密文，如果可以匹配上则可以推导出明文手机号，如果匹配不上，则说明是会员库里没有的新用户。会员数据库设计示意如下：
平台为每个已入驻会员通的品牌商家分配一个密钥，并使用MD5做两次加密，加密结果为 MD5(MD5("tmall"+$content+$key))，加密后的字符串为 32 位小写。tmall 为固定字符 串，key 为手机号加密密钥(会员中心开发者后台、测试平台可见)、content为需要加密的内容(这里是 moblie)。
代码示例：DigestUtils.md5Hex(DigestUtils.md5Hex("tmall" + "15089990091"+ "abcd"));
另外，会员码与支付宝的付款码相同，目前是19位，付款码以25～30开头，但建议商家系统能支持长度到24位，付款码不断增加。
