场景案例&解决方案
1.背景
智慧门店接入方案核心包括支付链路系统对接、会员链路系统对接、品牌号装修三大块，其中前两部分是涉及到系统对接，本文主要介绍支付链路如何对接。
什么是智慧门店？智慧门店订单长什么样？可点击这里查看。
2. 名词解释
- POS：这里的POS系统指门店管理系统（库存、商品、收银、店员管理等），部分商家叫门店ERP。
- PAY收银系统：一般指商家的聚合收银系统，支持支付宝、微信、银联等收银的系统或机具。
- 支付宝当面付接口：支付宝开放平台接口，消费者被扫：alipay.trade.pay，消费者主扫：alipay.trade.precreate。
- TOP：Taobao open platform（淘宝开放平台）。
- 间连/直连：直连——商户和支付宝签约，钱收到商户的支付宝账户；间连——银行代理收单，商户和银行签约，钱直接收到商户在签约银行的银行账户。
3、支付链路接入方案
3.1对接智慧门店支付链路的几种场景
| 门店收银场景 | 直连/间连 | 是否可以对接智慧门店支付链路 | 对接方案 | 支付接口 |
|---|---|---|---|---|
| 不支持支付宝收银 | / | 否 | / | / |
| 百货收银 | / | 否 | / | / |
| 消费者支付宝主扫门店静态二维码 | / | 否 | / | / |
| 消费者支付宝主扫门店动态二维码直接付款 | 直连 | 是 | 主扫方案+直连 | alipay.trade.precreate |
| 间连 | 是 | 主扫方案+间连转直连 | ||
| 导购员用POS系统的把枪或者独立收银机具 |
直连 | 是 | 被扫方案+直链 | alipay.trade.pay |
| 间连 | 是 | 被扫方案+间连转直连 |
说明：
1）关于直连/间连，主扫与被扫的详细介绍，可点击这里查看。
3.2 开发者需要做什么
-
POS的工作
1）支付宝当面付接口增加商品id、门店id、商品单价、商品个数、商品名称
2）门店优惠券、购物津贴（商家出资）和红包（平台出资）的使用，收银小票需展示出资内容，订单记录优惠信息用于对账
3）逆向流程，带有门店优惠券、津贴、红包等优惠的订单退款金额由POS计算
4）逆向接口POS需传入商品信息
门店商品管理
1）门店商品的增删改查功能开发
3.3视频教程
该视频教程分两部分：
1）00:00 - 09:42 智慧门店智能支付的产品介绍
2）09:42 - 结束 智能支付的系统对接教程
3.4 系统架构图
4.系统对接
4.1对接流程
说明：
1）蓝色是商家新增要做的事情，绿色是POS开发者要做的事情，灰色是选做的事情；
2）手机淘宝的会员码和支付宝的支付码本质上是完全一样的，扫的效果也是完全一样的；
3）关于扫码识别身份的说明：
a. 扫码识别身份（可返回加密手机号）的业务场景类似消费者到店后通过报手机号的方式确认是否是会员，即报手机号识别身份，变为扫码识别身份；
b. 扫码识别身份需要系统对接，由POS将扫到的串码提供给CRM，CRM与平台发生交互确认会员身份。详细的对接介绍，可查看本文档下面的“会员码身份识别接口”的介绍。因为该功能有一定的技术对接成本，是非必做功能。
c. 流程图中，出现了两次出示支付码，第一次用于身份识别，第二次用于支付（都是同一个码），动态支付码的有效期是1分钟，如果商家选择要做身份识别+支付，方案：a）可以如流程图中扫两次，第一次识别会员，第二次才是支付；2）也可以在1分钟内通过扫一次码完成身份识别与支付。前者的好处是避免导购误操作，消费者仅仅想查查会员信息，并不想支付，是身份识别还是支付导购的行为目的非常明确。
4.2对接前期准备
4.2.1 申请应用和接口权限包
1. 支付宝开放平台——当面付接口
智慧门店支付链路中当面付接口的开发需要对接支付宝开放平台的API接口：支付宝开放平台。
2. 淘宝开放平台——门店、商品管理接口
如果需要通过API接口管理门店、门店商品信息，需要开发者申请淘宝开放平台（TOP）的应用，具体步骤如下：
1）开发者如果是第三方服务商，可使用服务商已有的应用，没有应用的可以申请一个“门店信息化”的应用，申请地址；如果是商家自研系统，可先申请“奇门”应用，申请时“奇门对接场景”选择“奇门自定义对接场景”，“对接联调服务商名称”填写阿里巴巴。
2）拿到应用后，申请接口权限包“智慧门店_PASSPORT解决方案”。
3）另外，淘宝接口的调用，需要获取商家的授权，获取授权的方式参看授权说明文档。说明：授权时长一般和应用的订购时长保持一致，一般是一年，授权时长到期前需提醒商家进行重新授权（ISV需要为商家提供授权的页面）。TOP接口的调用方法参考文档。
4.3 支付宝当面付下单接口调整
4.3.1 消费者被扫模式（导购用把枪扫消费者支付码）
接口：alipay.trade.pay
接口名称：统一收单交易支付接口
4.3.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 |
3 | 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不打折金额字段：该字段接口文档中未透出，如果使用了该字段则不能享受优惠，请知晓。场景：在商户收银的时候在收银台里面输入不打折金额，然后扫码枪扫用户，这个不打折金额就不能参与优惠。
4.3.1.2 出参说明
1. 智慧支付链路增加可优惠券、购物津贴、红包的玩法，统一有平台来判断是否可核销，具体玩法说明说下：
| 优惠类型 | 优惠类型的说明 | 是否付钱给商家 | 是否可退 | 支付宝接口返回字段 fund_bill_list.fund_channel |
|---|---|---|---|---|
| 智慧门店优惠券 | 商家出资，形式：满减券，支持全场满减，也支持指定门店指定商品(小于3000)满减 | 否 | 否 | MDISCOUNT |
| 智慧门店购物津贴 | 商家出资，形式：每满N减n，例如每满300减30，买600则减60（前提是买家手里的津贴大于60） | 否 | 是 | MDISCOUNT |
| 智慧门店红包 | 平台出资，形式：类似支付宝的鼓励金，可当钱花 | 是 | 是 | DISCOUNT |
4.3.1.3 详细的支付宝接口升级方案
支付宝当面付接口升级智慧门店的详细介绍可参看：智慧门店当面付升级指引。
4.3.2 消费者主扫模式（生成订单二维码，买家扫码）
接口：alipay.trade.precreate
接口名称：统一收单线下交易预创建
说明：
1. 字段调整参考4.3.1章节的说明。
2. 支付结果的返回信息参看，当面付异步通知-仅用于扫码支付，字段说明参看4.3.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）退款的优先级顺序：实付>红包>购物津贴>优惠券
4.5 门店管理接口
商家发布门店的操作地址：阿里.智慧门店-门店管理-管理门店
说明：
1. 发布门店由商家来操作，详细的介绍文档：智慧门店数据初始化教程。大部分商家的门店相对变动低频，人工发布到智慧门店后台即可，对于门店变化较频繁的商品，可通过接口来对接。
2. 门店管理相关接口目前采用的是奇门接口，调用方式与TOP API略有不同。对接方法详见：全渠道技术对接文档（仅需要关注门店管理部分的内容，其他内容是全渠道业务）。门店管理接口暂时不提供SDK，需自己拼接url和body。接口如下：
1）taobao.qimen.store.create
2）taobao.qimen.storecategory.get
3）taobao.qimen.store.update
4）taobao.qimen.store.delete
注：调用奇门接口前，需联系阿里小二，提供您的appkey，小二进行接口调用授权后方可调用。
4.6 门店商品管理接口
商家发布门店商品的操作地址：阿里.智慧门店-商品管理-门店商品库管理-门店商品发布
说明：
1. 智慧门店交易入参里的good_id匹配商品的规则：先在智慧门店后台商品库里找，找不到再到天猫商品库里找。
2. 如果都找不到，则该笔订单记为无效订单（无效订单不影响优惠券核销）。
3. 无论天猫商品还是智慧门店商品库商品，需确保所有商品的SKU已配置了“商家编码”，且和支付接口中传入的good_id保持一致。
4. 商家如何发布门店商品，可查看详细的视频教程：智慧门店数据初始化教程。
5. 根据以往经验，商品发布一定要用接口来管理，后期商家运营人肉成本非常高。门店商品管理API如下：
1）taobao.omniitem.item.publish (全渠道门店商品轻发布)
2）taobao.omniitem.category.get (全渠道商品轻发布类目信息)
3）taobao.omniitem.item.image.upload (全渠道商品上传图片)
4）taobao.omniitem.item.fullupdate (全渠道商品全量更新)
5）taobao.omniitem.item.delete (全渠道商品删除)
6）taobao.omniitem.item.get (获取全渠道门店商品)
7）taobao.omniitem.sku.get (获取全渠道门店商品sku)
6. 关于接口的特别说明：
1）taobao.omniitem.category.get接口返回商品叶子类目cid，后续会调整为和天猫一致的线上类目；
2）可优先实现publish接口，注意：
a.要保证商品和sku的商家编码outerid不为空且唯一；
b.商品图片仅支持url上传，且必须是图片空间的url地址，如果门店商品不好取图片，可以先上传品牌logo的统一图片；
c.如果要上传本地图片，可publish后再调用upload接口；
4.7 智慧门店签约和门店开关开启
只有签署了全渠道天梭协议的门店收款支付宝，且商家对该支付宝开启了智慧门店订单同步开关，对应的支付宝交易才会进入智慧门店交易同步的模式。需要门店支付宝所有人参与签约。详情请查看【支付链路商家接入操作说明】-【智慧门店签约与门店开关开启】。
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"));
