更新时间：2025-03-06 17:17:42配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 后，商家/服务商可根据本文指引快速接入 商家扣款-支付并签约。说明：●商家扣款 产品仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用（传入 app_auth_token）方式，调用 api 接入。●商家扣款 沙箱环境的支付并签约场景下，暂不支持沙箱调试。●支付并签约场景指用户在小程序/商家app支付的同时，完成扣款协议的签约授权。商家在支付接口传入签约相关参数 sdkexecute 方法拿到 response 返回值后，其传入给 app支付/小程序，完成同步支付与异步签约，通过异步通知或者查询接口确认签约结果。●商家扣款 产品，接口中 product_code 字段固定传参为 general_withholding。1 支付并签约流程图1.1 从商家app发起1.2 从支付宝小程序发起2 创建商家扣款支付并签约2.1 创建app支付并签约商家调用 传入用户支付信息及商家扣款信息，创建商家扣款支付订单。2.1.1 前期准备接入 app支付产品，详情查看 。2.1.2 创建交易订单商家调用 传入用户支付信息及商家扣款信息，创建商家扣款支付订单。2.1.3 示例代码2.1.4 重要参数说明●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：商家扣款产品码固定为general_withholding。●personal_product_code：商家扣款个人签约产品码固定为 cycle_pay_auth_p。●sign_scene：签约场景码，具体参数请商家完成产品签约后，根据业务场景或用户购买商品的差异性对应新增模版及场景码。 说明：登录 商家平台 > > 商家扣款 > 功能管理 > 修改 > 设置模版 可新增模版及场景码。商家在确认新增模版及场景码完成后，签约接入时需要传入模版中实际填写的场景码。场景码格式详情可查看 。●external_agreement_no：商家签约号，代扣协议中标示用户的唯一签约号（确保在商家系统中唯一）。用户支持一对多，即同一个商家下，同一个用户可以有多套签约关系。通过商家外部签约号和场景参数来区分签约协议。若签约时传入了签约号及场景参数，后续查询协议和解约时也必须传入。●access_params：请按当前接入的方式进行填充，且输入值必须为文档中的参数取值范围。●channel：目前支持以下值：○alipayapp ：支付宝客户端 h5 页面签约。○qrcode：扫码签约。○qrcodeorsms：扫码签约或者短信签约。●sign_notify_url：签约成功异步通知地址。支付后签约场景中，用户支付成功及签约成功都会触发异步通知。规则如下：○若 只设置 notify_url 则两条异步通知都会发送到该地址。○若 分别设置 notify_url 及 sign_notify_url 则支付成功异步通知会发送到 notify_url，签约成功异步通知会发送到 sign_notify_url。2.1.5 唤起支付宝客户端并签约集成方案按照app支付请求支付的模式即可，可查看 客户端 sdk&demo。2.2 创建小程序支付并签约使用步骤：1在小程序中下单，获取交易号tradeno2唤起收银台完成支付2.2.1 前期准备接入 jaspi支付产品 jsapi支付接入准备。2.2.2 创建交易订单在服务端调用 alipay.trade.create（统一收单交易创建接口），获得支付宝交易号 tradeno：示例代码部分参数说明完整入参说明可查看 alipay.trade.create（统一收单交易创建接口）文档。●subject：必填，商品的标题/交易标题/订单标题/订单关键字等。 不可使用特殊字符，例如/,=,&等。●total_amount：必填，订单总金额，单位为元，精确到小数点后两位，取值范围 [0.01,100000000]。●buyer_id（buyer_open_id）：必填，买家支付宝用户的 id，获取详情可查看 用户授权文档。●seller_id：卖家支付宝用户 id。可登录 >主账号信息>账号 id获取。●notify_url：接收的异步通知 http/https 路径地址。用户支付成功时，支付宝将向本地址发送异步通知。●product_code：在小程序场景下使用时，需传入 jsapi_pay。●agreement_sign_params：签约参数。其中，product_code 字段必填，且传入固定值 general_withholding；2.2.3 唤起收银台支付在小程序端使用 tradeno，调用 接口唤起支付宝收银台，引导用户完成支付。说明：如有资金分账需求，可选择接入 商家分账 产品。示例代码部分参数说明object 类型，参数如下：参数类型必填描述tradenostring是接入小程序jsapi支付时传入此参数。此参数为支付宝交易号，注意参数有大小写区分。successfunction否调用成功的回调函数。failfunction否调用失败的回调函数。completefunction否调用结束的回调函数（调用成功、失败都会执行）。function successsuccess 回调函数会携带一个 object 类型的对象，其属性如下：属性类型描述resultcodestring支付结果码，下表。结果码结果码描述凯发app官方网站的解决方案4无权限调用（n22104）。个人小程序应用没有开放小程序jsapi支付能力。9000订单处理成功。不建议根据 my.tradepay 接口同步返回判断是否支付成功，9000 不能判定就是支付成功，请以异步通知（notify_url）返回的 trade_status(交易状态)为 trade_success 查询订单是否支付成功实际返回的支付状态为准。8000正在处理中。支付结果未知（有可能已经支付成功）。请调用 查询商家订单列表中订单的支付状态，以查询接口实际返回的支付状态为准。4000订单处理失败。tradeno 调用 jsapi支付 时必填●检查入参字段 tradeno 是否编写正确，"no"都是大写。●tradeno 的入参数据是alipay.trade.create（统一收单交易创建接口）返回的 “trade_no”，不是 “out_trade_no”。6001用户中途取消。●请用户重新签约 / 支付。●检查 tradeno 的入参是否为正常入参，参数数据为alipay.trade.create（统一收单交易创建接口）返回的“trade_no”。●alipay.trade.create（统一收单交易创建接口）在小程序场景中 buyer_id（buyer_open_id）参数必填，且必须和前端唤起支付的支付宝账号一致。6002网络连接出错。检查网络连接后重试。6004处理结果未知（有可能已经成功）。请调用 查询商家订单列表中订单的支付状态，以查询接口实际返回的支付状态为准。订单状态查询商家可调用 ，通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no 查询对应订单支付情况。3 签约成功后扣款商家根据用户签约成功支付宝返回的协议号（agreement_no）每次主动调 ，完成后续扣款操作。注意：为保障用户体验，扣费操作不可在晚上执行，请于北京时间 7:00～22:00 期间发起扣款。3.1 扣款流程图注意：允许商家在扣款日 execute_time前 5 天开始扣款，例：约定扣款日为 20 号，支持商家从 15 至 20 号发起扣款。3.2 示例代码3.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=3.3.1 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。3.3.2 注意事项商家扣款场景下使用 时：●product_code：必填，产品码。固定为general_withholding。●subject：必填，订单标题。不可使用特殊字符，如 /,=,& 等。●agreement_params：必填，签约信息。○agreement_no：必填，支付宝系统中用以唯一标识用户签约记录的编号（用户签约成功后的协议号）。●如果不填卖家 seller_id，则默认为商家签约账号对应的支付宝用户 id。3.4 支付异步通知参数支付成功异步通知参数说明具体请查看 。3.5 签约异步通知说明签约异步通知仅当用户签约成功时触发。商家以 post 接收方式接收异步签约通知，优先接收接口 中传的 sign_notify_url，若没传则取中传的 notify_url，若前两者均没传则取应用网关 地址（商家必须在 应用信息中配置应用网关）。3.5.1 商家验签在通知返回参数列表中除去 sign、sign_type 两个参数外，凡是通知返回回来的参数皆是待验签的参数。3.5.2 异步通知示例根据 status 触发条件，只有签约成功和解约成功才会返回异步，签约失败和解约失败都不会触发异步。3.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：用户的支付宝账号对应的支付宝唯一用户号。新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看 openid配置申请。●alipay_logon_id：用户的支付宝登录账号。●next_deduct_time：周期扣协议，预计下次扣款时间。4 辅助功能4.1 商家扣款协议查询商家可调用 查询用户是否完成签约操作，用户实际签约结果请以查询接口返回值为准。●通过协议号查询协议详情，此时请求参数中填入协议号（agreement_no），其它业务参数均可不填。●如果在支付宝个人协议页面签约接口接口中传递了sign_scene external_agreement_no 2 个参数，那在对应的协议查询接口中传递personal_product_code sign_scene external_agreement_no 3 个参数即可查询到内容。●如果在支付宝个人协议页面签约接口中没有传递sign_scene external_agreement_no2 个参数，那在对应的协议查询接口中传递personal_product_code （alipay_logon_id和alipay_user_id（alipay_open_id）2 个参数中的任何一个参数）即可查询到内容。4.2 商家扣款协议解约4.2.1 商家解约开发者可调用 完成协议解约。●通过协议号解约，此时请求参数中填入协议号(agreement_no)，其它业务参数均可不填。●通过personal_product_code sign_scene external_agreement_no alipay_logon_id alipay_user_id（alipay_open_id）来解约，入参值按照商家调 中的对应值传入；如果传入 external_agreement_no，则 alipay_logon_id 与 alipay_user_id（alipay_open_id）可不传，否则 alipay_logon_id 与alipay_user_id（alipay_open_id）必须传其中一个。4.2.2 用户解约用户可主动在支付宝客户端进行解约（无需商家侧接口调用），解约成功后支付宝将发送解约信息给商家应用在 中配置的 应用网关 地址。通知的内容格式请查看 中的异步通知格式。注意：●当用户通过支付宝 app 解约成功后，支付宝发送给商家的异步通知参数编码方式优先采用签约应用（appid）在开放平台上配置的编码方式，若无配置默认为gbk编码。●若应用类型为生活号请查看生活号接入文档激活开发者模式。4.2.3 解约异步通知说明解约异步通知仅当用户解约成功或商家调解约接口成功时触发。商家以 post 方式接收异步解约通知，如果是用户解约成功通知地址是 应用网关 地址（商家必须在 应用信息 中配置 应用网关）。如果是商家调用 解约优先接收接口中传的 notify_url，如果没传则取 应用网关 地址。异步通知示例注意：unsign（解约）是只有解约（解约接口或者客户端解约）才会触发返回的状态，当解约后调用 查询协议，会提示 用户协议不存在（user_agreement_not_exist），不会返回 status=unsign 的状态。4.3 订单支付后续●使用 完成退款。●使用 完成撤销。●使用 完成关闭交易订单。4.4 延期扣款商家可调用 实现延期扣款。例：用户在 1 月 1 日开通了连续包月，使用了 10 天又另行购买了季度包，如果此时商家希望季度包立即优先生效，在季度包结束后能继续使用连续包月，那么原定的周期就被延后了，如果不做处理那么扣款时间就对不上。此时可以由商家调用推迟接口，将预计扣款时间推后季度包的时长。4.4.1 示例代码4.5 下载对账单对账单可通过 。5 接口报错接口异常信息及凯发app官方网站的解决方案，详情可查看 。
