已更新更新时间：2024-12-25 16:25:29收藏订阅更新我的文档设置返回文档完成 后，商家/服务商可根据本文指引快速接入 周期扣款-支付并签约。说明：●周期扣款 产品仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用（传入 app_auth_token）方式，调用 api 接入。●周期扣款 产品暂不支持沙箱调试。●为保证正常调用接口，调接口之前需要先确保应用 上线 状态、应用 已绑定 且 已签约 周期扣款产品，可以使用 检查是否完成接入前的准备工作。●周期扣款 产品，接口中 product_code 字段固定传参为 cycle_pay_auth。1 支付并签约场景用户在小程序/商家app支付的同时签约协议，商家在支付接口传入签约相关参数 sdkexecute 方法拿到 response 返回值后，其传入给 app支付/小程序，完成同步支付与异步签约，通过异步通知或者查询接口确认签约结果。2 支付并签约流程图3 创建周期扣款支付订单商家调用 （app 支付 2.0）接口传入用户支付信息及周期扣款信息，创建周期扣款支付订单。3.1 示例代码3.2 部分参数说明●period_rule_params：周期管控规则参数 ，必填。○period_type：周期类型 ，枚举值为 day 和 month。周期类型使用 month 的时候，计划扣款时间 execute_time 不允许传 28 日之后的日期（可以传 28 日），以此避免有些月份可能不存在对应日期的情况。 说明：周期类型使用 day 的时候，周期数 period 不允许小于 7（可以等于7），避免间隔日期太短，扣款过于频繁，没有周期限制的意义。 ○period：必填，周期数，与 period_type 组合使用确定扣款周期，例如 period_type 为 day，period = 90，则扣款周期为 90 天。○execute_time：下次扣款的时间。非支付并签约的成功时间，必填。精确到日，格式为 yyyy-mm-dd。○single_amount：单次扣款最大金额，必填，即每次发起扣款时限制的最大金额，单位为元。商家每次发起扣款都不允许大于此金额。○total_amount：周期内允许扣款的总金额。○total_payments：总扣款次数。●total_amount：订单总金额。首次支付金额，不算在周期扣总金额里面。●product_code：周期扣款产品码固定为 cycle_pay_auth。●personal_product_code：周期扣款个人签约产品码固定为 cycle_pay_auth_p。●sign_scene：签约场景，具体参数请商家接入时根据自身行业进行判断，点击查看全部 。例如： industry|carrental（租车行业）。●external_agreement_no：商家签约号，代扣协议中标示用户的唯一签约号（确保在商家系统中唯一）。用户支持一对多，即同一个商家下，同一个用户可以有多套签约关系。通过商家外部签约号和场景参数来区分签约协议。若签约时传入了签约号及场景参数，后续查询协议和解约时也必须传入。●access_params：请按当前接入的方式进行填充，且输入值必须为文档中的参数取值范围。●channel：目前支持以下值：○ alipayapp ：支付宝客户端 h5 页面签约。○qrcode：扫码签约。○qrcodeorsms：扫码签约或者短信签约。●sign_notify_url：签约成功异步通知地址。支付后签约场景中，用户支付成功及签约成功都会触发异步通知。规则如下：○若 （app 支付 2.0）接口只设置 notify_url 则两条异步通知都会发送到该地址。○若 （app 支付 2.0）分别设置 notify_url 及 sign_notify_url 则支付成功异步通知会发送到 notify_url，签约成功异步通知会发送到 sign_notify_url。3.3 唤起支付宝客户端并签约说明3.3.1 商家 app 唤起支付并签约集成方案按照 app 支付请求支付的模式即可，可查看 客户端 demo。3.3.2 小程序唤起支付并签约将 orderstr 参数值传入 jsapi my.tradepay 即可实现唤起收银台支付并签约。4 支付成功异步通知异步通知参数说明具体请参考 。5 签约异步通知说明签约异步通知仅当用户签约成功时触发，商家以 post 方式接收签约异步通知消息。优先取接口 （app 支付 2.0）中传的 sign_notify_url ，若没有设置 sign_notify_url 则会取 notify_url，如果都没传则取 应用网关 地址（商家必须在 应用信息 中配置 应用网关）。5.1 商家验签在通知返回参数列表中除去 sign、sign_type 两个参数外，凡是通知返回回来的参数皆是待验签的参数。5.2 异步通知示例根据 status 触发条件，只有签约成功和解约成功才会返回异步，签约失败和解约失败都不会触发异步。5.3 重要参数说明●status：协议状态，枚举支持。○normal：正常。○unsign：解约。●external_agreement_no：代扣协议中标示用户的唯一签约号，商家自定义。仅签约接口传入时返回。●agreement_no：支付宝系统中用以唯一标识用户签约记录的编号。●notify_type：异步通知类型，枚举支持。○dut_user_sign：当 status = normal 表示签约成功。○dut_user_unsign：当 status = unsign 表示解约成功。●sign_scene：签约协议场景。●personal_product_code：协议产品码。●alipay_user_id（alipay_open_id）：支付宝用户唯一标识。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看。●alipay_logon_id：用户的支付宝登录账号。 6 后续扣款商家根据用户签约成功支付宝返回的协议号（agreement_no）每次主动调 （统一收单交易支付接口），完成周期扣款协议后续免密代扣操作6.1 签约成功后续扣款流程图说明：目前允许商家在约定日期及其之前5天开始扣款，如：约定扣款日为 20 号，支持商家从 15 至 20 号发起扣款。6.2 示例代码6.3 同步返回公共参数说明参数类型是否必填最大长度描述示例值codestring是~详见下文 结果码和处理方式。40004 msgstring是~返回码描述business failedsub_codestring否~子返回码agreement_not_existsub_msgstring否~子返回码描述协议不存在。可能原因：1用户已解约； 2协议号传入错误，请检查。signstring是256商家请求参数的签名串，详见 签名。dzxh8eetuahoye3w1 j poiphfdxoybfunn1 lket/v7p4zjdyojwea6 izs6hz0ydw5cp/viufu b5i0/v5wens3oyr8zr edqo6d futdlhdc e fyckiqhbxizgngpdpdf p1pis7bdhhzrszhbrq b7o4k3dxc aanfauu4v6zdwczo=code 结果码和处理方式●根据公共返回参数中的 code，这笔交易可能有四种状态：支付成功（10000），支付失败（40004），等待用户付款（10003）和未知异常（20000）。●对于 扣款失败 或 未知异常， 有如下凯发app官方网站的解决方案：○建议商家等待5分钟后，使用 （统一收单交易查询接口）查询交易状态，如果交易状态是成功，则无需特殊处理；若查询 4 次后依然返回等待用户付款，商户可以选择幂等重试代扣或通过 （统一收单交易撤销接口）发起交易撤销。结果码说明处理方式10000支付成功记录交易结果并在显示支付成功，进入后续的业务处理。40004支付失败记录交易结果并显示错误信息（display_message）。10003等待用户付款一般等待5分钟后调用交易查询接口 alipay.trade.query。 通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 trade_status ）。查询4次之后若仍然返回等待用户付款（wait_buyer_pay），商户可以选择幂等重试代扣或者发起交易撤销 alipay.trade.cancel。20000未知异常一般等待5分钟后调用交易查询接口 alipay.trade.query。 通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 trade_status ）。查询4次之后若仍然返回等待用户付款（wait_buyer_pay），商户可以选择幂等重试代扣或者发起交易撤销 alipay.trade.cancel。注意事项周期扣款场景下使用 （统一收单交易支付接口）时：●product_code：必填，产品码。固定为 cycle_pay_auth。●subject：必填，订单标题。不可使用特殊字符，如 /,=,& 等。●agreement_params：必填，代扣信息。○agreement_no：必填，支付宝系统中用以唯一标识用户签约记录的编号（用户签约成功后的协议号）。●如果不填卖家 seller_id，则默认为商家签约账号对应的支付宝用户 id。7 支付成功异步通知异步通知参数说明具体请参考 当面付异步通知说明。8 辅助功能8.1 周期扣款协议查询商家可调用 （支付宝个人代扣协议查询接口）查询用户是否完成签约操作，用户实际签约结果请以查询接口返回值为准。●通过协议号查询协议详情，此时请求参数中填入协议号（agreement_no），其它业务参数均可不填。●如果在支付宝个人协议页面签约接口接口中传递了sign_scene external_agreement_no 2 个参数，那在对应的协议查询接口中传递 personal_product_code sign_scene external_agreement_no 3 个参数即可查询到内容。●如果在支付宝个人协议页面签约接口接口中没有传递 sign_scene external_agreement_no 2 个参数，那在对应的协议查询接口中传递 personal_product_code （alipay_logon_id 、 alipay_user_id 和 alipay_open_id 3 个参数中的任何一个参数）即可查询到内容。8.2 周期扣款协议解约8.2.1 商家解约开发者可调用 （个人协议解约接口）完成协议解约。●通过协议号解约，此时请求参数中填入协议号(agreement_no)，其它业务参数均可不填。●通过 personal_product_code sign_scene external_agreement_no alipay_logon_id alipay_user_id（alipay_open_id） 来解约，入参值按照商家调 alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）中的对应值传入；如果传入 external_agreement_no，则 alipay_logon_id 与 alipay_user_id（alipay_open_id） 可不传，否则 alipay_logon_id 与 alipay_user_id（alipay_open_id） 必须传其中一个。8.2.2 用户解约用户可主动在支付宝客户端进行解约（无需商家侧接口调用），解约成功后支付宝将发送解约信息给商家应用在 中配置的 应用网关 地址。通知的内容格式请查看 （个人协议解约接口）中的异步通知格式。注意：●当用户通过支付宝 app 解约成功后，支付宝发送给商家的异步通知参数 编码方式 优先采用签约应用（appid）在开放平台上配置的编码方式，若无配置默认为 gbk 编码。●若应用类型为生活号请查看 激活开发者模式。8.2.3 解约异步通知说明解约异步通知仅当用户解约成功或商家调解约接口成功时触发。商家以 post 方式接收异步解约通知，如果是用户解约成功通知地址是 应用网关 地址（商家必须在 应用信息 中配置 应用网关）。如果是商家调 （个人协议解约接口接口）解约优先接收接口中传的 notify_url，如果没传则取 应用网关 地址。异步通知示例注意：unsign（解约）是只有解约（解约接口或者客户端解约）才会触发返回的状态，当解约后调用 （支付宝个人代扣协议查询接口）查询协议，会提示 用户协议不存在（user_agreement_not_exist），不会返回 status=unsign 的状态。9 订单支付后续●使用 （统一收单交易退款接口）完成退款。●使用 (统一收单交易撤销接口)完成撤销。●使用 （一收单交易关闭接口）完成关闭交易订单。10 延期扣款商家可调用 （周期性扣款协议执行计划修改接口）实现延期扣款。10.1 示例用户在1月1日开通了连续包月，使用了10天又另行购买了季度包，如果此时商家希望季度包立即优先生效，在季度包结束后能继续使用连续包月，那么原定的周期就被延后了，如果不做处理那么扣款时间就对不上。此时可以由商家调用推迟接口，将预计扣款时间推后季度包的时长。11 业务接口报错关于业务接口报错请查看 常见问题。
