本文档介绍线下零售商家在接入智慧门店全渠道解决方案时，当面付接入改造内容。
阅读对象：计划接入智慧门店支付的商家/ISV开发人员。

1.名词解释

• ISV：(Independency Software Vendor)独立软件供应商
• 当面付直连：商户直接与支付宝签约，直接使用支付宝账号发起交易
• 当面付间连：商户直接与银行签约，通过用户渠道发起支付宝交易
• POS系统：这里指商户门店管理系统（库存、商品、收银、店员管理等）
• 支付宝当面付接口：线下场景支付宝收单接口，包括：
  消费者被扫（出示付款码，把枪扫描收款）：alipay.trade.pay
  消费者主扫（打开支付宝扫一扫，扫描订单二维码）：alipay.trade.precreate

2.整体合作流程

3.准备工作

3.1 确认当面付接入情况

由于智慧门店支付只支持当面付直连，首先需要确认接入支付宝当面付接入情况：
（1）未接入支付宝当面付直连：
对于ISV：需要新接入当面付直连能力，对接指引参考：
消费者被扫：参考条码支付接入指引
消费者主扫：参考扫码支付接入指引
对于商户：建议选择已接入当面付直连能力的ISV合作，若是自研开发，则新接入当面付直连接口

（2）间连接入的ISV/商户的需要转成直连接入，具备直连能力的直接切换，不具备的则需要新接，接入指引参考上面

（3）已接入当面付直连支付的ISV/商户，则需进行当面付升级改造

3.2 确认支付链路

若为直连接入，则确认商户支付链路类型，核实需改造内容，常见商户支付链路如下:
（1）门店POS - 支付ISV – 支付宝均通过系统接口集成

改造点：需在接口中增加门店、商品明细、操作员信息传递，打通三方系统

（2）门店POS直接接入支付宝当面付接口

改造点：需在接口中增加门店、商品明细、操作员信息传递即可，打通双方系统

（3）门店POS与支付ISV未打通（插件或者独立POS抓取金额或手输金额）

改造点：需要POS先与支付ISV打通，并在支付时传入门店及商品明细

3.3 若为间连接入，则需要转为直连接入

（1）原间连渠道服务商具备支付宝直连能力，商户直接与支付宝签约当面付，通过第三方应用授权或提供签约应用信息给到间连服务商，切换为直连接入（打通门店、商品明细），进行对接调试

（2）间连渠道不具备支付宝直连能力，寻找直连支付ISV直接对接，快速打通门店POS、支付ISV与支付宝

4.当面付改造功能列表

• 正向支付时传入在智慧门店全渠道中心已创建的门店编号和操作员（子账号）编号。
• 正向支付时传入在智慧门店全渠道中心已上传的的商品明细信息。
• 逆向退款时传入相应的商品明细信息。

4.1 正向支付传入门店/操作员编号

商家在智慧门店全渠道中心通过平台或接口创建门店后，在调用支付宝当面付支付接口alipay.trade.pay或者alipay.trade.precreate时，需传入 门店编号 store_id 参数，参数值为创建门店时录入或传入的商家原有门店编号。

商家在智慧门店全渠道中心通过平台或接口创建操作员子账号后，在调用支付宝当面付支付接口alipay.trade.pay或者alipay.trade.precreate时，需传入 操作员编号 operator_id 参数，参数值为创建操作员子账号时录入或传入的商家原有人员编号。

4.2 正向支付传入商品明细

商家在智慧门店全渠道中心通过平台或接口发布商品后，在调用支付宝当面付支付接口alipay.trade.pay或者alipay.trade.precreate时，需传入 商品明细信息 goods_detail 参数传入，注意这个参数是个数据集，包含几个子参数，以JSON列表的形式支持同时传入多个商品。

子参数名称	子参数说明	是否可空
goods_id	商户自定义的商品编号，需要与在智慧门店发布商品是传入的外部商品编号一致。	不可空
goods_name	商户自定义的商品名称，注意编码格式与调用接口指定的编码一致。	不可空
quantity	本次交易购买的商品数量	不可空
price	商品单价，单位元，商品优惠前的价格。商品单价x数量的累加金额＝订单总金额（不做强行校验）	不可空

参数样例：
"goods_detail":[ { "goods_id":"apple-01", "goods_name":"ipad", "quantity":1, "price":2000 } ]

4.3 逆向退款传入商品明细信息

门店调用支付宝当面付退款接口alipay.trade.refund时，需传入本次退货的商品明细 goods_detail 参数, 参数格式与正向支付传入的商品明细信息 goods_detail 参数一致。

子参数名称	子参数说明	是否可空
goods_id	商户自定义的商品编号，需要与在智慧门店发布商品是传入的外部商品编号一致。	不可空
quantity	本次退款的商品数量	不可空

参数样例：
"goods_detail":[ { "goods_id":"apple-01", "quantity":1 } ]

5.退款逻辑实现

使用了智慧门店优惠券订单申请退款时，由于支付宝的订单退款逻辑为先退用户实付金额，若商户允许部分商品退款，为避免用户套取优惠，建议商户分摊优惠到各个商品，计算扣除优惠部分的商品金额，再发起退款
举例：一笔订单有2个商品A和B，总金额100元，商品A为90元，商品B为10元，用户使用了满10元门店优惠券（满100可用）
用户后续若申请商品A退款，则需先计算商品A使用优惠10*(90/100)=9,商品A应退实付为90-9=81，实际发起退款的金额为81元
若商户直接拿商品金额90元发起退款，则会直接退90元实付金额给到用户，产生套优惠的情况
当然商户也可选择限制必须整单退款，不允许部分退款的策略

6.门店或分公司独立收款账号收款实现

一个品牌入驻智慧门店与一个当面付签约主账号绑定，若有需求经销商或者分区域分公司独立收款，可在签约主账号下设置门店信息绑定收款账号实现

实现流程：联系对应支付宝BD设置收款限制集（一次性提供所有收账号）或者配置白名单;
然后使用签约账号登录支付宝商家中心配置经营信息（分公司信息及门店信息配置），建立门店id与收款账号的对应关系，通过当面付接口传入的store_id判断收款账号，收款到对应支付宝账号实现
商家中心经营信息配置

7.多级经销商及导购分账需求实现

对于品牌门店非直营的商业场景，如美妆行业，大部分门店是一、二级经销商经营的，而且商品货款并非经销商买断，而是旗舰店寄售模式，消费者完成订单支付后，商家还需对订单进行分账结算给对应一、二级经销商，旗舰店以及导购（销售分佣）
针对此需求，一般建议可通过当面付完成支付后，财务通过POS系统交易记录完成对账结算，系统确认分佣比例后，使用线下的清分渠道进行清分
若强烈需求通过支付宝账号完成清分，需要在商户系统中绑定各经销商、导购实名支付宝账号，可通过支付宝用户信息授权，获取会员信息绑定支付宝账号uid
财务系统完成对账结算后，ERP系统再调用单笔转账到支付宝账号接口完成对各个经销商、导购及旗舰店的分账

8.小票透出商家优惠信息

通过处理支付成功后响应的fund_bill_list参数，可以获取本次支付使用的资金渠道信息，便于在小票中透出本次支付的实际商家优惠情况，其中：

fund_channel：交易使用的资金渠道,支付渠道列表，主要几个类型说明：

参数名称	参数说明
MDISCOUNT	商户优惠券，商户出资部分。智慧门店新增的淘宝门店优惠券将在这里透出，所有商户出资优惠券都会在这里合并返回
ALIPAYACCOUNT	支付宝账户，指消费者的支付余额、余额宝等支付渠道资金。
DISCOUNT	平台出资的优惠，比如支付宝鼓励金，商家收到的资金依然是原价。

小票具体的规范要求参考：小票规范

9.业务账单淘宝优惠字段申请

智慧门店优惠属于淘宝平台优惠及淘宝商家优惠，若要在支付宝业务对账单中体现需要单独申请，申请方式：提供签约及收款账号pid给到支付宝对应BD（业务经理），申请增加淘宝优惠和淘宝商家优惠字段增加淘宝优惠和淘宝商家优惠字段

附上业务账单下载接口: alipay.data.dataservice.bill.downloadurl.query

10.验收方式

当面付升级改造完成后，需要商户进行在线云验收，验证门店编号及商品明细是否传入

具体验收流程：商户签约账号登录云验收后台设置验收人（付款人，一般为支付ISV测试验收人），验收人按云验收指引，选择“智慧门店”产品，完成支付及退款验收查看验收结果:

.没有传入商品明细与门店编号，验收结果显示为黄线警告
.有传入商品明细与门店编号，则绿底文字提示，商品明细goods_detail还会显示具体的明细列表参数。

验收成功进行截图保存，若自助验收不成功，可加下面的智慧门店支付宝开发者大群进行人工验收
上线前提供智慧门店的实施同学@梓晗@溪行确认

11.智慧门店支付宝开发者大群

具体智慧门店当面付升级对接细节，请开发者扫码加入开发者大群咨询：

FAQ

关于此文档暂时还没有FAQ