接入指南-扩展功能

花呗分期功能接入

当面付支持 花呗分期 的付款方式，商户在满足 花呗准入 的前提下，才能够使用花呗分期进行收款，准入后有标准收银台与单通道两种模式可选。详情可参考 花呗分期支付接入说明。

要在当面付功能中使用花呗分期的付款方式，商户只需要在对应的接口中传入对应的参数即可。

花呗分期接口列表

标准收银台模式

支付宝标准收银台展示花呗分期渠道（仅支持用户承担手续费），无需额外签约花呗分期，且无需进行额外的花呗分期参数的透传开发工作，可以直接在支付宝标准收银台中展示出花呗分期渠道。

单通道模式

商家可以根据需要，将花呗分期资金渠道前置或者与其他付款方式并列，实现花呗分期单通道模式。该方式下，如果当前花呗分期渠道无法支付成功，则可以继续使用其他支付渠道进行付款。

商户需要将花呗分期参数传入到 extend_params 中，格式如下：

xxxxxxxxxx

"extend_params" :{ "hb_fq_num" : "3" , "hb_fq_seller_percent" : "100" }

​

• hb_fq_num 代表花呗分期数，仅支持传入 3、6、12，其他期数暂不支持，传入会报错。

• hb_fq_seller_percent 代表卖家承担收费比例，商家承担手续费传入 100，用户承担手续费传入 0，仅支持传入 100、0 两种，其他比例暂不支持，传入会报错。

优惠金额

限制订单参与优惠的金额

商户在支付宝已配置优惠活动或优惠券，如需要限制订单参与优惠的金额，可使用以下参数控制，支持交易支付接口和交易预下单接口。

获取优惠情况下的各级金额

此外，在支付接口和查询接口返回的支付结果中，可根据以下参数获取有优惠情况下的支付宝计算好的各级金额。

各级金额关系

• total_amount - 商户出资的优惠金额 = receipt_amount。

• receipt_amount - 支付宝出资的优惠金额 = buyer_pay_amount。

• buyer_pay_amount - 用户通过自有的营销工具减免的金额（例如集分宝）= invoice_amount。

案例分析

某餐厅在支付宝后台配置了商户出资的 9 折活动，酒水不享受折扣，同时叠加支付宝出资的立减 5 元活动。某用户总共消费 100 元，其中酒水 20 元，则商户系统在请求支付时，需传入 discountable_amount = 20。此时商户实收金额为 (100-20)*0.9 + 20 = 92 元，用户实付金额为 92 - 5 = 87 元，由于用户又使用了自己账户等值 2 元的集分宝，因此开票金额为 87 - 2 = 85 元。

指定收款支付宝账号

对于部分大型集团型或加盟型商户，如有 一个签约账号+多个收款账号 的需求，通过 条码支付 的交易支付接口 alipay.trade.pay 和 扫码支付 的交易预下单接口 alipay.trade.precreate 中的参数 seller_id 来指定收款账号。 默认情况下，当面付只允许收款至签约账号。如果使用指定收款账号的功能，需要使用商户签约账号登录 商家中心 配置收款账号列表，详情请参见 添加收款账户 。

注意：seller_id 传入的是收款账号的 user_id（支付宝内部 ID，2088 开头的 16 位数字），而不是登录 ID（邮箱或手机号）。商户可通过静默模式的用户信息授权流程获得支付宝账号的 user_id（需使用该账号登录），详情请参见 获取会员信息。

商品信息同步

商户/系统服务商（ISV） 在调用支付接口时，可传入用户实际购买的商品信息，达到两个效果：

1. 用户支付完成后，可在支付宝手机客户端的账单中看到这些商品信息，起到 电子小票 的作用；

2. 如果商户在支付宝创建了单品优惠活动，则支付时必须传入商品信息，当传入的商品信息与单品活动中的配置的商品匹配上时，支付宝就会自动根据活动的优惠规则减免付款金额。 注意：商品信息通过条码支付的交易支付接口 alipay.trade.pay 和扫码支付的交易预下单接口 alipay.trade.precreate 中 goods_detail 参数传入，此参数为数据集，包含几个子参数，以 JSON 列表的形式支持同时传入多个商品。

   
   

   子参数名称	子参数说明
   goods_id	商户自定义的商品编号，需要与单品活动中配置的商品编号一致。请在商户维度保持商品编号唯一，并与商品名称保持一对一关系。
   goods_name	商户自定义的商品名称，请不要传入如外卖商品/打折商品等无实际意义的商品名称。如果有商品有多个规格，可在商品名称中包含，如海飞丝（350ml）。注意编码格式与调用接口指定的编码一致。
   quantity	本次交易购买的商品数量。
   price	商品单价。单位元，商品优惠前的价格。 商品单价 x 数量的累加金额＝订单总金额（不做强行校验，但可能影响单品相关返佣）

   更多信息以及完整的请求报文示例，请参见 API 列表。

注意：请传入的商品信息遵守以上规范，商品信息的不规范可能影响与单品相关的返佣和单品运营活动。

多门店应用

使用 alipay.trade.pay(统一收单交易支付接口) 时，需注意以下参数的取值：

• store_id：商户自己定义的门店号。如果商户通过门店创建接口或在商家中心开店，则需要与开店时传入的 store_id（或配置的外部门店号）保持一致，与 alipay_store_id 至少上传一个。

  注意：该参数仅支持字母、数字和英文符号，不支持中文。

• alipay_store_id：支付宝门店号。即商户通过接口开店时接口返回的 shop_id，可以在商家中心查询到。当同时传入 store_id 和 alipay_store_id 时，必须保证两者是匹配的，否则会报错。

小票规范

门店收银系统打印的收银小票内容

必须包含内容

• 商户订单号或支付宝交易号，最好增加条形码展示。

• 支付宝支付标识。

• 日期和时间。

建议包含内容

• 商户实收金额，返回参数中的 receipt_amount。

• 开票金额，返回参数中的 invoice_amount。

• 用户支付宝账号，返回参数中的 buyer_logon_id，已脱敏。

小票示例

返佣

ISV 帮助商户接入支付能力时候可以获取交易的返佣。 返佣技术接入只需在 API 中传入返佣 ISV ID，商户即可获取返佣。

为了确保得到返佣，需要返佣的 ISV 请确保传入正确的返佣参数。建议 ISV 接入的所有订单都加入 sys_service_provider_id 参数，并检查参数是否正确，ISV 如果传入错误的参数将无法获得返佣。可在 开放平台 查看返佣明细。

接入沙箱

支付能力直接涉及到交易与资金，为了方便开放者调试支付能力，开放平台已经准备好沙箱环境，包括沙箱环境账号和沙箱版支付宝钱包，这样商户就可以在沙箱环境调试了。详情请参见 如何接入沙箱 并 接入沙箱环境。

当面付沙箱接入的注意点如下：

• 在沙箱调通接口后，必须在线上进行测试与验收，所有返回码及业务逻辑以线上为准。

• 当面付只支持余额支付，不支持银行卡、余额宝等其他支付方式。

• 当面付不支持优惠核销。

• 扫码支付中的扫码以及条码支付中的付款码请使用沙箱版钱包测试：进入 控制台 > 沙箱环境 > 沙箱工具。

• 查询对账单下载地址，仅测试该接口在沙箱环境中是否可以成功下载对账单，下载的 CSV 对账单仅为账单模板(数据为空)，实际数据请使用生产环境。

接口调用结果码说明

监控应用

应用上线后还可以在 支付宝开放平台 查看应用运行情况以及交易状态。详情请参见 云监控。

自助工具

如果需要验证当前接入质量是否符合我们所罗列的标准规范，商户/ISV 可以访问 商户自助监控平台 查看 集成健康度。