代扣能力

更新时间：2024-07-04 11:48:48

前置说明

当用户在平台完成签约后，会在代扣日期当天的12点，23点执行三次代扣，若三次均代扣失败，则当前周期扣款行为结束（下个周期仍会正常发起代扣），为避免用户权益断档，请开发者兼容好权益的发放

1. 周期代扣回调

1.1 接口说明

• 在平台代扣成功/失败后，快手小程序服务端会通过 HTTP POST 请求方式回调开发者提供的 HTTP 代扣回调地址。回调的内容使用小程序 secret key 进行签名，具体回调方式和重试策略见附录 (opens new window)。请注意：
• 由于网络波动等原因，可能会产生重复的通知消息，开发者需要做好幂等处理。
• 在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败并进行重试。
• 代扣回调的地址是 支付并签约接口中的 withhold_notify_url 字段，所以请务必保证该字段传输的正确性

1.2 基本信息

名称	内容
HTTP URL	开发者在支付并签约时传入的 withhold_notify_url 字段
HTTP Method	POST

1.3  平台回调内容

以下字段放置到 body json中：

{
    "data": {

        "withhold_product": "xxx_monthly_card",
        "withhold_state": "PAY_SUCCESS",
        "order_no": "121112500031787702250",    // 注意,代扣单进行退款时，传递此单号!!!
        "contract_no": "121112500031787702251", // 对于同一笔签约单，所有代扣回调此字段相同
        "withhold_no": "1231231232",            // 每一次周期周期扣款，此字段都是唯一的
        "withhold_time":1627293368719,
        "withhold_amount":100,
        "contract_type": 1,
        "current_period": 1,
        "attach": "小程序demo得"
    },
    "biz_type": "WITHHOLD",
    "message_id": "fa578923-347b-4158-9ae8-06c54d485da3",
    "app_id": "ks682576822728417112",
    "timestamp": 1627293368719
}

字段名	类型	说明
withhold_product	string	签约产品
withhold_state	string	扣款状态 (成功、失败) PAY_SUCCESS - 成功 PAY_FAILD - 失败(正常情况下，买家余额不足会流转到此状态)
order_no	string	快手小程序平台订单号
contract_no	string	快手小程序平台签约号
withhold_no	string	快手小程序平台代扣记录号
withhold_time	number	扣款完成时间
withhold_amount	number	扣款金额
contract_type	number	签约模版类型 1:周  2:月  3:季度  4:年  5:固定30天  6:固定31天
current_period	number	当前代扣周期，从1开始累加
attach	string	预下单时携带的开发者自定义信息

1.4 开发者返回内容

开发者在接收到回调消息，并正确处理后，需要返回以下内容格式，以通知小程序平台不再持续回调：

{
  "result" : 1,   //必填。 1-成功，其他-失败。失败小程序平台会尝试重推此消息
  "message_id" : "ChFvYXV0aC5hY2Nlc3NUb2tlbhJQvpR51x8In46B1sDB" //当前消息的message_id
}

如果开发者没有返回或者返回的result不等于1，则小程序平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！