已更新更新时间：2024-12-25 16:25:27收藏订阅更新我的文档设置返回文档完成 后，商家/服务商可根据本文指引快速接入 周期扣款-独立签约后扣款。说明：●周期扣款 产品仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用（传入 app_auth_token）方式，调用 api 接入。●周期扣款 产品暂不支持沙箱调试。●为保证正常调用接口，调接口之前需要先确保应用 上线 状态、应用 已绑定 且 已签约 周期扣款产品，可以使用 检查是否完成接入前的准备工作。●周期扣款 产品，接口中 product_code 字段固定传参为 cycle_pay_auth。1 独立签约后扣款场景用户在h5页面/小程序/商家app/pc页面中先行确认服务内容等信息完成代扣协议签约操作，后续商家根据用户代扣协议号等参数完成免密代扣，简化用户操作且方便用户自动续费。2 页面签约流程图3 创建签约协议内容商家通过调用 alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）传入周期扣款约定等相关信息创建签约协议内容。3.1 示例代码完整的 json 数据可复制 请求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：总扣款次数。●product_code：周期扣款产品码固定为 cycle_pay_auth。●personal_product_code：周期扣款个人签约产品码固定为 cycle_pay_auth_p。●sign_scene：签约场景，具体参数请商家接入时根据自身行业进行判断，点击查看全部 。例如： industry|carrental（租车行业）。●sign_validity_period：当前用户签约请求的协议有效周期。●return_url：跳转商家处理地址。则签约流程中会在上文 页面签约流程图 中的 步骤 11 跳转至此地址并在处理完成后回跳继续流程，没有传这个参数则不跳转。●notify_url：异步通知地址。●external_agreement_no：商家签约号，代扣协议中标示用户的唯一签约号（确保在商家系统中唯一）。用户支持一对多，即同一个商家下，同一个用户可以有多套签约关系。通过商家外部签约号和场景参数来区分签约协议。若签约时传入了签约号及场景参数，后续查询协议和解约时也必须传入。●access_params：请按当前接入的方式进行填充，且输入值必须为文档中的参数取值范围。扫码或者短信页面签约需要拼装 http 的请求地址访问中间页面，支付宝客户端 h5 页面签约可直接拼接 schema 的请求地址。●channel：目前支持以下值：○ alipayapp ：支付宝客户端 h5 页面签约。○qrcode：扫码签约。○qrcodeorsms：扫码签约或者短信签约。●用户实名信息参数填入 identity_params 中（包括 identity_hash）；如果商家已获得用户实名信息,需要与支付宝实名信息比对一致性，则将用户实名信息生成摘要信息填入 identity_params中 的 identity_hash。详情可查看 。 注意：此时如不需要再跳转实名授权，则 merchant_process_url 参数应不传。特殊场景才会使用，如无需要不用关注。●第三方主体类型（third_party_type），目前支持 partner 和 merchant，默认 partner，目前有 airbnb 和之前的 uber 是 merchant 类型(存在父子关系)。4 pc转二维码唤起签约说明1alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）使用alipayclient.pageexecute(request,"get")生成签约字符串。2使用二维码生成工具把签约字符串转成二维码，用户扫码签约。注意：php 语言生成的签约字符串有可能会被转义，需要 htmlspecialchars 处理之后的签约字符串生成二维码。5 小程序唤起签约说明1alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）使用 alipayclient.sdkexecute() 把生成的签约字符串使用 urlencoder 处理下再返回。 注意：小程序场景调用 alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）不需要设置 return_url，若设置 return_url 会导致开通后跳到该url，此时跳出了小程序，小程序前端接口不返回 success 回调方法。2使用小程序api接口 my.paysigncenter()。6 app内唤起起签约说明6.1 ios 接入方式6.1.1 导入说明接入客户端支付宝 sdk查看 获取 支付sdk：alipaysdk（15.8.28 ）或者 独立签约sdk：apdeductsdk。启动 ide（如 xcode），把下载的 sdk 压缩文件中以下文件拷贝到项目文件夹下，并导入到项目工程中。在需要调用 alipaysdk 的文件中，增加头文件引用。接口说明配置应用回跳 scheme在本工程 plist 文件如下位置配置用于跳转到该应用的 scheme：（此处 demo 配置的 scheme 为 afauthdemo）6.1.2 调用样例拼装 url 参数alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）使用 alipayclient.sdkexecute(request) 请求，生成的签约字符串（sign_params）如下：调用 sdk 接口唤起签约结果获取由于 ios 的 universallink 机制在某些场景下存在无法正常跳转的问题，这里需要针对 scheme 跳转与universallink 都做处理。scheme 回跳处理 调用接口调用方式universal link 回跳处理（可选）调用接口调用方式结果回调 afserviceresponse 6.1.3 universal links 配置（可选）独立签约app接入方式支持了app token 校验功能，该功能在 ios 系统下依赖 universal link 的引入，详情可查看 。6.2 android 接入方式6.2.1 导入说明接入客户端支付宝 sdk请参考 android 支付宝 sdk 集成流程 直到 运行权限 一节为止的指导，接入 含有独立签约功能的支付宝 sdk。配置应用回跳 scheme在使用支付宝 sdk 的独立签约功能时，签约业务完成后，支付宝 app 将以 intent 跳转的形式将结果传递给您的 app。为此，您需要配置一个 app 特有的 scheme 以接收业务结果。请在您 app 的 androidmanifest.xml 配置文件中增加以下配置（请将其中的 __alipaysdkdemo__ 替换为您的 app 特有的 scheme）：6.2.2 调用样例拼装参数调用 openauthtask.execute() 时的参数：上述参数中，params 参数内的 sign_params 是业务参数，拼接格式参考本文 创建签约协议内容 章节的 示例代码。 sign_params 值如下示例：结果获取android 平台在调用会传入 callback 参数，具体示例如下。在 onresult 的 resultcode 参数中可能出现的错误码（返回码）。7 页面签约同步通知说明●商家请求 alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）接口时如果传了 return_url，用户签约成功跳转到return_url，同步通知会在商家传入的 return_url 后面拼接返回。如果商家接口中未传入 return_url 则用户签约完成后不再返回商家，直接回到支付宝客户端凯发k8官方网娱乐官方首页。●有些时候会出现商家 app 在支付宝签约阶段被关闭导致无法正确收到同步结果，商家可以将同步签约结果仅作为一个签约结束的通知（忽略执行验签），实际签约是否成功，完全依赖服务端异步通知，如果商家未接入异步通知，则可通过签约查询接口获取签约结果。7.1 签约成功同步通知示例http://api.test.alipay.net/atinterface/receive_notify.htm?agreement_no=20170627457298962889&status=normal&external_logon_id=13852852877&sign_type=rsa&charset=utf-8&auth_app_id=2017060101317939&invalid_time=2017-08-27 11:40:13&personal_product_code=cycle_pay_auth_p&version=1.0&code=10000&msg=success&sign=qujnmii1svlm8hforx5fu/zz5lqomdkt+dzawwaeqdoxnakyjr0fdfzr4l7hfuff6wdr05yve2/khsadulgogwrl2w7azmqcitztvzuvevte9imm9mgtnk/7uxa+kwydzm8a3iygopitr0htghhm7cqzh5gdt8k5nidvtmyk2yy=×tamp=2017-06-27 11:40:15&sign_scene=industry|carrental&valid_time=2017-06-27 11:40:13&external_agreement_no=test212&app_id=2017060101317939&method=alipay.user.agreement.page.sign&alipay_logon_id=1382877&sign_time=2017-06-27 11:40:148 签约异步通知说明签约异步通知仅当用户签约成功时触发。商家以 post 接收方式接收异步签约通知，优先接收接口 alipay.user.agreement.page.sign（支付宝个人协议页面签约接口）中传的 notify_url，若没传则取 应用网关 地址（商家必须在 应用信息 中配置 应用网关）。8.1 商家验签在通知返回参数列表中除去 sign、sign_type 两个参数外，凡是通知返回回来的参数皆是待验签的参数。8.2 异步通知示例根据 status 触发条件，只有签约成功和解约成功才会返回异步，签约失败和解约失败都不会触发异步。8.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：用户的支付宝登录账号。 9 签约成功后续扣款商家根据用户签约成功支付宝返回的协议号（agreement_no）每次主动调 （统一收单交易支付接口），完成周期扣款协议后续免密代扣操作。9.1 扣款流程图说明：允许商家在约定日期及其之前5天开始扣款，如：约定扣款日为 20 号，支持商家从 15 至 20 号发起扣款。9.2 示例代码9.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。9.3.1 注意事项周期扣款场景下使用 （统一收单交易支付接口）时：●product_code：必填，产品码。固定为 cycle_pay_auth。●subject：必填，订单标题。不可使用特殊字符，如 /,=,& 等。●agreement_params：必填，代扣信息。○agreement_no：必填，支付宝系统中用以唯一标识用户签约记录的编号（用户签约成功后的协议号）。●如果不填卖家 seller_id，则默认为商家签约账号对应的支付宝用户 id。10 支付成功异步通知异步通知参数说明具体请参考 。11 辅助功能11.1 周期扣款协议查询商家可调用 （支付宝个人代扣协议查询接口）查询用户是否完成签约操作，用户实际签约结果请以查询接口返回值为准。●如果在支付宝个人协议页面签约接口接口中传递了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 个参数中的任何一个参数）即可查询到内容。11.2 周期扣款协议解约11.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） 必须传其中一个。11.2.2 用户解约用户可主动在支付宝客户端进行解约（无需商家侧接口调用），解约成功后支付宝将发送解约信息给商家应用在 中配置的 应用网关 地址。通知的内容格式请查看 （个人协议解约接口）中的异步通知格式。注意：●当用户通过支付宝 app 解约成功后，支付宝发送给商家的异步通知参数 编码方式 优先采用签约应用（appid）在开放平台上配置的编码方式，若无配置默认为 gbk 编码。●若应用类型为生活号请查看 激活开发者模式。11.2.3 解约异步通知说明解约异步通知仅当用户解约成功或商家调解约接口成功时触发。商家以 post 方式接收异步解约通知，如果是用户解约成功通知地址是 应用网关 地址（商家必须在 应用信息 中配置 应用网关）。如果是商家调 （个人协议解约接口）接口解约优先接收接口中传的 notify_url，如果没传则取 应用网关 地址。异步通知示例注意：unsign（解约）是只有解约（解约接口或者客户端解约）才会触发返回的状态，当解约后调用 （支付宝个人代扣协议查询接口）查询协议，会提示 用户协议不存在（user_agreement_not_exist），不会返回 status=unsign 的状态。12 订单支付后续●使用 （统一收单交易退款接口）完成退款。●使用 (统一收单交易撤销接口)完成撤销。●使用 （一收单交易关闭接口）完成关闭交易订单。13 延期扣款商家可调用 （周期性扣款协议执行计划修改接口）实现延期扣款。13.1 示例用户在1月1日开通了连续包月，使用了10天又另行购买了季度包，如果此时商家希望季度包立即优先生效，在季度包结束后能继续使用连续包月，那么原定的周期就被延后了，如果不做处理那么扣款时间就对不上。此时可以由商家调用推迟接口，将预计扣款时间推后季度包的时长。14 业务接口报错关于业务接口报错请查看 常见问题。
