履约期周期灵活代扣(履约期按期扣费能力)
商家可以根据业务需求,调用 zhima.credit.pe.zmgo.settle.apply(芝麻GO结算申请接口)进行履约期周期灵活代扣。
接口调用时序图
-
场景 1:用户在当前期内完成任务。
在本期的履约时间内,用户完成相应任务,商户还未发起本期代扣,则商家可以发起 0 元结算。
-
场景 2:用户在当前期指定时间内未完成任务,通过结算方式完成任务
-
场景 3:用户在当前期指定时间内未完成任务,通过结算方式一直没扣到钱,后有在运营商侧完成任务
商家已经发起了本期代扣任务,但并未收到成功消息,此时用户在商家侧完成本期任务,则商家必须回传本期在网任务,并调用当前接口把本期周期灵活代扣计划关闭,action_type=SETTLE_TO_CLOSE。
-
场景 4:用户在当前期指定时间内未完成任务,通过结算方式一直没扣到钱,后有在运营商侧完成任务,同时支付宝扣款成功
代扣规则
扣款频次规则
芝麻 GO 目前只支持 自然月 时间扣款。
接入周期性代扣功能前,请先联系支付宝技术支持在芝麻 GO 模板中正确配置代扣规则。
代扣发起规则
周期灵活代扣由商家根据自身业务特点,自行选择时机发起,每期周期灵活扣结算都需要商家发起。商家发起周期灵活扣结算申请受理成功后,商家需等待结算成功消息。在 8:00~22:00 期间,商户可以 30 分钟重复发起再次结算申请,直到该接口返回受理成功结果。其它时间,芝麻 GO 系统会把商家发起周期灵活代扣的请求托管起来。
注意:商家发起下一期周期灵活代扣请求时,必须把本期的周期灵活代扣处理完结(成功/关闭),否则无法获取下期周期灵活代扣计划号。
接口调用参数详述
此场景下调用 zhima.credit.pe.zmgo.settle.apply(芝麻GO结算申请接口)需特别注意以下几点:
- 每期扣款相关注意点:
商户调用结算受理接口 zhima.credit.pe.zmgo.settle.apply。发起请求后,重试请求时,请不要替换金额 pay_amount 及外部请求号 out_request_no。其中withhold_plan_no 为必填项。 - 首期扣款相关注意点:
履约期按期扣费接口的相关入参来源于签约成功消息 zhima.credit.pe.zmgo.sign.notify,具体如下:
-
- 履约期按期扣费接口入参 pay_amount 以当前金额以商户实际情况为准,但需满足 0 <=pay_amount <= original_price(该值来源:首期开通成功消息 zhima.credit.pe.zmgo.sign.notify(芝麻GO业务签约变更商户通知接口)返回参数 original_price)。
- 履约期按期扣费接口入参 withhold_plan_no= 签约成功消息中的 withhold_plan_no。
- 履约期按期扣费商户发起的结算申请时间需要在 planned_trigger_time~time_out_time(从签约成功消息中获得)范围内。无法提前发起,也不能超过这个时间。
- 后续期数扣款相关注意点:
后续每一期扣款入参的部分参数来源于上一期的结算成功消息(zhima.credit.pe.zmgo.settle.notify),具体如下:
-
- 履约期按期扣费接口入参 pay_amount 当前金额以商户实际情况为准,但需满足 0 <=pay_amount <= original_price(该值来源:zhima.credit.pe.zmgo.settle.notify(芝麻GO业务结算变更商户通知)next_original_price)。
- 履约期按期扣费接口入参 withhold_plan_no =上一期的结算成功消息 next_withhold_plan_no。
- 履约期按期扣费商户发起的结算申请时间需要在next_planned_trigger_time~next_time_out_time(从上一期的结算成功消息中获得)范围内。无法提前发起,也不能超过这个时间。
-
结算转关单注意点:
需满足几个前提条件: -
运营商已经调用过结算申请接口。
-
-
- pay_amount>0。
满足以上两点的情况下,关单时调用此接口,入参 pay_amount 跟发起受理时金额保持一致,action_type=SETTLE_TO_CLOSE(结算转关单效果等于 0 元结算,调用后,后续不可再重复发起本期结算)。
- pay_amount>0。
-
周期灵活扣代扣结果通知
每一期代扣完成后,支付宝端通过 zhima.credit.pe.zmgo.settle.notify(芝麻 GO 业务结算变更商户通知接口)把代扣金额、支付宝交易号等信息汇总发送一个代扣成功/最终失败消息给到商户。通过 withhold_biz_type=ZMGO_CYCLE_FLEX_WITHHOLD_DEDUCT 识别当前消息是否为周期灵活扣扣款结果通知。
- 若代扣成功,支付宝将立刻发送成功通知给到商户
- 若代扣结果未收到,商户可以在每天 8:00~22:00 期间,每隔 30 分钟重复发起再次结算申请,直到该接口返回受理成功结果。
注意:代扣成功通知和结算成功通知共用一个消息通知方法,同时通过 cycle_withhold 字段区分是周期灵活扣代扣通知还是结算通知。
消息示例
具体消息属性、响应值可查看 zhima.credit.pe.zmgo.settle.notify(芝麻 GO 业务结算变更商户通知接口)文档。
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"withhold_plan_no":"ZMGO_WHD2021010910020603000000006002","trade_no":"20201212203423423420210110014004","agreement_id":"ZMGO_AGR2021012910020604010000000001","agreement_status":"Y","out_request_no":"63c0efbf3c62cf03ede783257ed66de8","rest_freeze_amount":"100.00","pay_amount":"100.00","alipay_user_id":"2088101117955611","partner_id":"2088101117955612","biz_time":"2021-01-29 11:35:59","pay_aisle_data":"API","trans_status":"Y","biz_type":"EASY_MEMBER","product_version":"zhimGoV2"
}
&msg_method=zhima.credit.pe.zmgo.settle.notify&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==