进阶功能

接入花呗分期说明


当面付目前支持花呗分期的付款方式。要在当面付功能中使用花呗分期的付款方式,只需要开发者在对应的接口中传入对应的参数即可。


相关接口列表

接口英文名

接口中文名

alipay.trade.pay

统一收单交易支付接口

alipay.trade.create

统一收单交易创建接口

alipay.trade.precreate

统一收单线下交易预创建


标准收银台模式


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


单通道模式


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

开发者需要将花呗分期参数传入到 extend_params 中,格式如下:


"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两种,其他比例暂不支持,传入会报错。


详情可参考花呗分期支付接入说明


优惠金额


商户在支付宝配置了优惠活动或优惠券,但需要限制订单参与优惠的金额,可使用以下两个参数控制,支持交易支付接口和交易预下单接口:

参数名

参数说明

discountable_amount

可优惠金额

undiscountable_amount

不可优惠金额,无需传入,由订单总额减去可优惠金额即可获得


如果同时传入了 discountable_amount,undiscountable_amounttotal_amount 三个参数,则必须满足如下条件:total_amount(订单总金额)= discountable_amount(可打折金额)+ undiscountable_amount(不可打折金额)


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

参数名

参数说明

total_amount

订单总金额,与请求中的订单金额一致

receipt_amount

实收金额,商户实际入账的金额(扣手续费之前)

buyer_pay_amount

用户实付金额,建议打印在小票上避免退款时出现纠纷

invoice_pay_amount

开票金额,快速告知商户应该给用户开多少钱发票

上述四个金额的关系如下:

total_amount - 商户出资的优惠金额 = receipt_amount;
receipt_amount - 支付宝出资的优惠金额 = buyer_pay_amount;
buyer_pay_amount - 用户通过自有的营销工具减免的金额(例如集分宝)= invoice_amount;


案例分析

某餐厅在支付宝后台配置了商户出资的9折活动,酒水不享受折扣,同时叠加支付宝出资的立减5元活动。某用户总共消费100元,其中酒水20元,则商户系统在请求支付时,需传入undiscountable_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(需使用该账号登录),点击查看详细文档


商品信息同步


商户/系统商在调用支付接口是,可传入用户实际购买的商品信息,达到两个效果:

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

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

子参数名称

子参数说明

goods_id

商户自定义的商品编号,需要与单品活动中配置的商品编号一致。请在商户维度保持商品编号唯一,并与商品名称保持一对一关系。

goods_name

商户自定义的商品名称,请不要传入如外卖商品/打折商品等无实际意义的商品名称。如果有商品有多个规格,可在商品名称中包含,如海飞丝(350ml)。注意编码格式与调用接口指定的编码一致。

quantity

本次交易购买的商品数量

price

商品单价,单位元,商品优惠前的价格。商品单价x数量的累加金额=订单总金额(不做强行校验,但可能影响单品相关返佣)

更多信息以及完整的请求报文示例,可参考API详细文档


注意

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

onlineServer