更新时间：2025-07-17 14:41:57配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 后，商家/服务商可根据本文指引快速接入 预授权支付。说明：●预授权支付 仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用方式，调用 api 接入。●预授权支付 支持沙箱调试。支付流程交互流程图冻结资金当用户使用如租车、充电桩、酒店预订等服务时，用户需要先做一笔资金授权。当服务完成，扣款时，商家再调 从授权资金中扣除消费金额，剩余金额返还给用户。冻结资金需要商户根据自身业务做出合理预估，支持一次授权多次扣款，累计扣款最多不能超过冻结金额。第一步：商家下资金冻结单开发者可调用 生成资金冻结订单并获取参数串用于小程序端/商家 app 唤起收银台完成冻结。示例代码完整的 json 数据可复制 请求。重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数英文名描述out_order_no商家授权资金订单号。out_request_no商家本次资金操作的请求流水号。order_title订单标题。amount需要冻结的金额，由商家根据自身业务评估金额。product_code产品码，固定为 preauth_pay。notify_url异步通知地址，异步通知响应详情可查看文中 授权异步通知 章节，当用户授权成功时将触发异步通知返回 auth_no等授权结果信息。若未设置 notify_url 则需调用 轮询用户授权结果，当接口返回 order_status = authorized 时则用户授权成功。payee_user_id可选字段，收款账户的支付宝用户号。payee_logon_id可选字段，收款账户的支付宝登录号（email或手机号）。如果商家希望用户能够使用花呗，则用户号(payee_user_id)和登录号(payee_logon_id)两者必须传入其一。enable_pay_channels可选字段，可以指定支付渠道，如果不传，默认为签约协议的支付渠道；若需要限制支付渠道，目前仅支持余额宝（money_fund）、花呗（pcredit_pay）以及芝麻信用（creditzhima）。冻结用户花呗（pcredit_pay）额度渠道升级中，暂不支持新用户申请接入，请关注后续通知。第二步：调起用户确认页面说明：●请将支付宝客户端升级至最新版本。●若唤起支付宝收银台报错 参数异常，请关注支付宝返回给客户端的具体错误信息。app 调起用户确认页面android示例代码详情可查看 。ios示例代码可查看 。重要入参说明●paytask 对象主要为商家提供订单支付、查询功能，及获取当前开发包版本号。●获取 paytask 支付对象调用支付（支付行为需要在独立的非 ui 线程中执行）。出参获取h5 调起用户确认页面开发者可通过 ap.tradepay 接口，传入支付宝订单字符串唤起支付，用户确认后即可冻结资金。注意：该组件仅支持支付宝端内 h5 访问唤起，不支持端外 h5 访问。示例代码重要入参说明可直接传入一个字符串作为 option.orderstr 参数。option 参数说明参数英文名类型必填描述tradenostring否交易号，多个交易号请用英文分号 ; 分隔。partneridstring否商户 id。biztypestring否交易类型，默认为 trade。bizsubtypestring否交易子类型。bizcontextstring否支付额外的参数，格式为 json 字符串。orderstrstring否完整的支付参数拼接成的字符串，从服务端获取。callback 参数说明参数英文名类型描述resultcodestring支付结果状态码，详情可查看下表。resultcode 支付状态码说明resultcode描述9000订单支付成功。8000正在处理中。4000订单支付失败。6001用户中途取消。6002网络连接出错。99用户点击忘记密码导致快捷界面退出（only ios）。小程序调起用户确认页面开发者通过在小程序内调用 ，唤起预授权冻结流程（入参即接入流程中获取的 orderstr）。 注意：开发者需通过真机调试的方式调试该接口的功能，若用 ide 调试该接口则会报无效的 api 入参。示例代码注意事项●status=init，表示用户授权中，可调用 每隔 5 秒钟查询一次授权冻结的状态，如依然是用户授权中，则再等待 5 秒钟继续使用查询接口查询，直至 1 分钟后超时（推荐每隔 5 秒查询一次，共进行 12 次查询，具体根据商家业务情况决定）。说明：如超时前最后一次查询依然返回用户授权中，则立即调用 将该笔预授权冻结交易撤销。●如接口返回系统异常，先通过查询接口查询授权冻结的状态，并根据查询结果进行后续操作。●返回错误码为 system_error 时，请调用查询接口确定授权状态，并根据状态确定下一步操作。授权异步通知说明当用户使用服务会在支付宝客户端唤起冻结页用户同意协议，输入密码之后会收到授权签约异步通知，平台通过 传入的 notify_url 主动以 post 的方式推送给商家。用户授权成功异步通知样例重要参数说明参数英文名描述auth_no支付宝资金授权订单号out_order_no商家的资金授权订单号operation_id支付宝的资金操作流水号out_request_no商家资金操作流水号异步通知参数说明具体请参考 。验签方法同步接口和异步通知验签，可查看 验签流程。异步通知接收代码规范接收程序执行完后必须打印输出 success。如果商家反馈给支付宝的字符不是 success 这7个字符，服务器会不断重发通知，直到超过 24 小时 22 分钟。一般情况下，25 小时以内完成 8 次通知（通知的间隔频率一般是 4m、10m、10m、1h、2h、6h、15h）；接收程序执行完成后，该页面不能执行页面跳转。如果执行页面跳转，支付宝会接收不到 success 字符，会被支付宝服务器判定为该页面程序运行出现异常，而重发处理结果通知。示例代码冻结资金转支付当商家获得用户授权完成 线上资金冻结场景 操作后，如果业务场景需要用户进行支付，而并不只是冻结押金，则需要调用 完成扣款操作。注意：●商家在进行冻结转支付时，若扣款金额大于冻结的押金，会出现扣款失败，在第一步资金冻结时需要商家根据自身业务合理评估出冻结金额。●冻结转支付使用 为通用接口，在资金授权场景下：○授权码的参数为 auth_no 而非当面付中的 auth_code；授权码也没有 25-30 开头的限制。○资金授权过程无需传入scene 参数。示例代码重要入参说明参数英文名描述notify_url非必填，支付成功异步接收地址auth_confirm_mode非必填，预授权确认模式●当 auth_confirm_mode = complete 时无需调用解冻接口，支付宝端在扣款成功后会自动解冻剩余金额，同时该笔授权订单完成。●当 auth_confirm_mode = not_complete 时，商家收到支付成功通知后需要自行调用 将余额进行解冻。●如果需要从一笔授权中完成多笔订单支付，保持 auth_no 不变，不同订单根据 outtradeno 进行标识，此时 auth_confirm_mode 不传或者传入 not_complete；进行到最后一笔转支付时，auth_confirm_mode 传入 complete 由支付宝完成剩余金额自动解冻，或者商家自行调用解冻接口将剩余金额解冻。注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。重要出参说明●response 中的 code=10000，表示接口调用成功，支付状态以异步通知或交易查询为准。●如果未收到异步通知，可以通过交易查询接口查询最新交易状态，如果返回 trade_status = wait_buyer_pay，商家可以调用预授权转支付重新发起扣款（注意：商家订单号 out_trade_no 保持不变）。支付异步通知说明资金授权转支付通知样例重要参数说明参数英文名描述out_trade_no商家外部交易号trade_no支付宝交易号trade_status交易状态receipt_amount实收金额查看更多参数说明请参考 。解冻资金当资金授权发生之后一段时间内，由于买家或者商家等其它原因需要要解冻资金，商家可通过 将授权资金进行解冻，支付宝将在收到解冻请求并验证成功后，按解冻规则将冻结资金按原路进行解冻并返回。示例代码完整的 json 数据可复制 请求：说明：●支持全额解冻和部分解冻。●当业务流程为商家冻结用户资金并且在用户完成业务后直接转为支付场景时该接口非必须调用，可查看 资金冻结转支付场景 。解冻转支付时：○若 auth_confirm_mode = complete，无需调用解冻接口，支付宝端在扣款成功后会自动解冻剩余金额。○若 auth_confirm_mode = not_complete，在收到支付成功通知后，商家需自行调用解冻接口将余额进行解冻。资金授权解冻通知示例重要参数说明参数英文名描述operation_type资金操作类型。unfreeze：解冻。auth_no支付宝资金授权订单号。out_request_no商家资金操作流水号。其它参数可查看 。查询资金冻结操作商家可以通过资金授权操作查询接口 查询单笔明细的详细信息，细分到每一次操作，如冻结、解冻。请求示例响应示例重要出参说明response 中的 status=success 表示预授权成功；init：初始状态，表示已创建授权单，等待用户密码确认；closed：关闭状态，超时未授权，支付宝将授权单关闭后的状态。撤销资金冻结商家通过 撤销用户资金授权。注意：只有商家由于业务系统处理超时需要终止后续业务处理或者授权结果未知时可调用撤销，其它正常授权冻结的操作如需实现相同功能请调用资金授权解冻服务。提交资金授权后调用资金授权操作查询，没有明确的授权结果再调用支付宝预授权撤销。示例代码查询交易商家通过 查询单笔明细的详细信息。示例代码重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。outtradeno：为授权转支付时传入的 outtradeno。重要出参说明如果查询返回处理中 trade_ status = wait_buyer_pay 或 order success pay inprogress，商家可以调用预授权转支付重新发起扣款，需注意商家订单号 out_trade_no 保持不变。退款流程当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过 将支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。注意：交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款。支付宝退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商家订单号和设置不同的退款单号。一笔退款失败后重新提交，要采用原来的退款单号。总退款金额不能超过用户实际支付金额。示例代码退款结果查询●退款成功：退款是否成功可以根据同步响应的 fund_change 参数来判断，返回值为 y 则表示退款成功。●退款失败：根据 错误码 确认是否要重试，重试时注意 out_request_no 需保持一致。●系统异常：无法确认退款结果。○方案一：重试，重试时注意 out_request_no 需保持一致。○方案二：先调用 确认退款结果，如失败，再发起重试。对账流程目前支付宝对外的常用对账方式有两种：一种是通过在支付宝后台下载账单的方式来对账；一种是通过调用接口的方式来实现对账，下文介绍如何通过接口获取对账单下载链接。更多后台下载及账单示例图详情请可查看 。开发者可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。系统流程说明：1商家系统调用 ，传入指定日期，获得该日期账单文件的下载地址。2商家系统通过 http 方式后台访问账单下载链接，将账单 csv 文件下载到本地后自行处理。注意该下载链接仅 30 秒，在得到链接后系统需要立刻下载账单文件。示例代码响应示例重要出参说明参数英文名描述bill_download_url对账单下载地址，下载地址有效时间为 30 秒，请尽快下载。接口报错处理关于接口报错请查看 。
