更新时间：2025-03-06 16:39:07文档更新记录 >配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 后，商家/服务商可根据本文指引快速接入当面付 付款码支付。说明：●仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用方式，调用 api 接入。●支持沙箱环境联调。●商家的收银系统需配备红外扫描枪设备或其它的扫码设备，用于获取用户付款码信息。1 接入方式在开始开发前，需要明确接入的方式或者所需物料等。应用接入方式分为两类： 方式和 方式。1.1 门店直连方式门店直连方式接入即商家收银台直接通过公网向支付宝发起收款。个人商家或者单独门店建议采用该方式接入。 1.1.1 接入流程1.2 商家/服务商后台转发方式商家/服务商后台转发方式接入即商家收银台先向商家后台发起收款请求，商家后台再将请求转发给支付宝后台。建议由多家门店的商家或大型商家这类有能力开发自有后台的商家采用。1.2.1 接入流程1.3 安全设计 支付宝为了保证交易安全采取了一系列安全手段以保证交易安全。主要采用以下安全设计策略，详情可查看 应用安全开发指南。 ●采用 https 协议传输交易数据，防止数据被截获、解密。●采用 rsa/rsa2 非对称密钥，明确交易双方的身份，保证交易主体的正确性和唯一性。●付款码定时刷新，防止被拍照。●防止截屏 (截屏后二维码失效) 。2 支付流程 开发者需要确认自己的应用在审核通过后显示 已上线，同时完成当面付功能的开通后 (可点击查询 )，才能顺利调用以下接口，否则会有缺少权限的报错。2.1 系统交互流程1买家出示钱包内付款码，商家通过扫码设备获取付款码信息，并将付款码上传到 alipay.trade.pay（统一收单交易支付接口） 请求支付。2根据返回的结果，确定支付状态，从而进行相应处理（包括必要时关闭交易）, 如图 opt 区块中所示根据付款码支付接口返回公共参数code，付款码支付存在以下四种状态：结果码描述请求成功（10000）只表示请求成功，若存在扣款异常可能发生回滚导致扣款失败，必须根据查询接口或者异步通知返回的交易状态进行判断，交易失败，建议关闭交易，更换订单号out_trade_no和买家支付渠道重新扣款。等待用户付款（10003）由于余额不足、超额等原因导致订单创建但支付未成功，等待用户付款。付款码支付由于是线下面对面支付，需尽快确认交易情况，建议通过 判断交易状态，避免单边账。未知异常（20000）未知异常，可能由于系统异常或者网络超时等问题导致接口报错，建议调用查询接口确认支付结果，详情可查看 。支付失败（40001- 40006）业务出现未知错误或者系统异常，需要重新检查参数，重新发起支付。详情可查看 。2.2 交易状态流程随着订单支付成功、退款、关闭等操作，订单交易的每一个环节 trade_status（交易状态）不同。1交易创建成功后，用户支付成功，交易状态转为 trade_success（交易成功）。2交易成功后，规定退款时间内没有退款，交易状态转为 trade_finished（交易完成）。3交易支付成功后，交易部分退款，交易状态为 trade_success（交易成功）。4交易成功后，交易全额退款，交易状态转为 trade_closed（交易关闭）。5交易创建成功后，用户未付款交易超时关闭，交易状态转为 trade_closed（交易关闭）。6交易创建成功后，用户支付成功后，若用户商品不支持退款，交易状态直接转为 trade_finished（交易完成）。注意：交易成功后部分退款，交易状态仍为 trade_success（交易成功），如果一直部分退款退完所有交易金额则交易状态转为 trade_closed（交易关闭），如果未退完所有交易金额，超过有效退款时间后交易状态转为 trade_finished（交易完成）不可退款。2.3 支付商家系统将用户付款码与订单信息一起通过 alipay.trade.pay（统一收单交易支付接口）请求到支付宝，并从接口同步返回中获取支付结果。重要说明1用户付款码建议做好设计预留工作○原因：由于业务发展需要，支付宝可能会在后续业务中对用户付款码做升级处理。付款码将由原来的 28 开头扩充到 25-30 开头，长度由原来的 16-18 位扩充到 16-24 位。未来随着移动支付产业的发展，用户付款码可能会有所加长，建议商家和服务商做好设计预留工作。○建议方案：如果商家和服务商在对接当面付付款码支付接口时，有对支付宝付款码做码段和长度的限制，请务必完成相关升级。2当面付涉及返佣必传sys_service_provider_id，详见 。3付款码支付不存在同步跳转，支付后只会触发异步通知。2.3.1 示例代码 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no商户订单号，需保证在商家系统中唯一。scene支付场景，付款码支付场景固定为 bar_code。auth_code用户付款码，实际字符串长度以开发者获取的付款码长度为准。●付款码使用一次即失效，即使支付失败也需刷新。●调试场景，若无扫码枪/扫码枪不可用，可通过 指引获取用户付款码。subject商品的标题/交易标题/订单标题/订单关键字等。不可使用特殊字符，如 /,=,& 等。store_id商家门店编号。total_amount订单金额。timeout_express交易超时时间。重要出参说明参数名参数说明trade_no支付宝交易号。code网关返回码，详情可查看 公共错误码 。支付接口需注意如下值：●10000：只表示请求成功，若存在扣款异常可能发生回滚导致扣款失败，必须根据查询接口或者异步通知返回的交易状态进行判断，交易失败，建议关闭交易，更换订单号out_trade_no和买家支付渠道重新扣款。●40004：支付失败。建议记录交易结果并在客户端显示错误信息（display_message）。●10003：等待用户付款。建议发起轮询流程：等待 5 秒后调用 （统一收单交易查询接口）。 通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 trade_status ），如果仍然返回等待用户付款（wait_buyer_pay），则再次等待 5 秒后继续查询，直到返回确切的支付结果（成功 trade_success 或 已撤销关闭trade_closed），或是超出轮询时间。在最后一次查询仍然返回等待用户付款的情况下，必须立即调用接口 alipay.trade.cancel（统一收单交易撤销接口）将这笔交易撤销，避免用户继续支付。●20000：未知异常。建议调用查询接口确认支付结果，详情可查看 。2.4 查询交易商家可调用接口 （统一收单交易查询接口），通过商家网站唯一订单号 out_trade_no 或支付宝交易号trade_no 查询对应订单支付情况。2.4.1 示例代码重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。2.5 撤销交易支付交易返回失败或支付系统超时（交易状态不明确），商家可调用接口 alipay.trade.cancel（统一收单交易撤销接口）通过商家网站唯一订单号 out_trade_no 或支付宝交易号trade_no 撤销交易。重要说明：●如果此订单用户支付失败，支付宝将关闭此订单，用户无法继续支付。●如果此订单用户支付成功，支付宝将退还订单资金给用户，交易状态变为 trade_closed（交易关闭）。●仅发生支付系统超时或者支付结果未知时可调用本接口撤销交易，其它正常支付的单如需实现相同功能请调用接口 alipay.trade.refund（统一收单交易退款接口）。2.5.1 示例代码重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。重要出参说明参数名参数说明retry_flag是否需要重试，y/n。action本次撤销触发的交易动作。●close：关闭交易，无退款 。●refund：产生了退款。3 退款流程3.1 退款当交易发生之后一段时间内，由于业务原因（如金额错误，用户退款或者对账不平等等）需要退款时，商家可以调用接口 alipay.trade.refund（统一收单交易退款接口）通过商家网站唯一订单号 out_trade_no 或支付宝交易号trade_no，将对应订单支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。支持全额或部分退款。3.1.1 调用流程3.1.2 退款结果●退款成功：退款是否成功可以根据同步响应的 fund_change 参数来判断，返回值为 y 则表示退款成功。●退款失败：根据 错误码 确认是否要重试，重试时注意 out_request_no 需保持一致。●系统异常：无法确认退款结果。○方案一：重试，重试时注意 out_request_no 需保持一致。○方案二：先调用 （统一收单交易退款查询接口）确认退款结果，如失败，再发起重试。3.1.3 退款说明●退款周期：以签约协议为准，默认12个月，即交易发生后12个月内可发起退款，超期不可退款。●退款方式：资金原路返回用户账号。●退款退费：默认退款时手续费退回。●退款时效：支付渠道为花呗、余额等退款即时到账。银行卡的退款时间以银行退款时间为准，一般情况下 2 小时内可到账（若退款到卡失败，退款金额会退回用户支付宝账户余额）。●商家可以在 中退款。●退款接口会根据外部请求号 out_request_no 幂等返回，因此同一笔交易需要多次部分退款时，必须使用不同的 out_request_no。3.1.4 示例代码重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。out_request_no本次退款请求流水号，部分退款时必传。refund_amount本次退款金额。重要出参说明参数名参数说明refund_fee该笔交易已退款的总金额。3.1.5 退款到银行卡通知退款存在退到银行卡场景下时，支付宝会调用 alipay.trade.refund.depositback.completed（收单退款冲退完成通知）根据银行回执消息发送退款完成信息至应用网关地址。重要说明：●如需触发 alipay.trade.refund.depositback.completed（收单退款冲退完成通知），需要在调用 alipay.trade.refund（统一收单交易退款接口）时，传入参数 "query_options":["deposit_back_info"]。●开发者需登录 进入对应应用详情页，在 开发设置 > from 平台 中订阅 alipay.trade.refund.depositback.completed（收单退款冲退完成通知）。更多 from 蚂蚁消息详情可点击查看 from蚂蚁消息。消息示例重要参数说明参数名参数说明trade_no支付宝交易订单号。dback_status银行卡冲退状态。●s - 成功。●f - 失败，银行卡冲退失败，资金自动转入用户支付宝余额。dback_amount银行卡冲退金额。bank_ack_time银行响应时间，格式为 yyyy-mm-dd hh:mm:ss。est_bank_receipt_time预估银行入账时间，格式为 yyyy-mm-dd hh:mm:ss。3.2 查询退款结果商家/服务商可调用 alipay.trade.fastpay.refund.query（统一收单交易退款查询接口）查询对应out_request_no（退款请求号）的退款情况。 重要说明：1退款查询接口的trade_no、out_trade_no、out_request_no必须和退款接口保持一致，否则交易号一致，out_request_no不同，只会返回10000，success，但是没有具体的退款信息。2该接口的返回10000，仅代表本次查询操作成功，不代表退款成功，当接口返回的refund_status值为refund_success时表示退款成功，否则表示退款没有执行成功。3.2.1 重要入参说明参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。out_request_no请求退款接口时，传入的退款请求号，如果在退款请求时未传入，则该值为创建交易时的商户订单号4 对账流程目前支付宝对外的常用对账方式有两种：●一种是通过在 商家平台 > 下载账单的方式来对账。●一种是通过调用接口的方式来实现对账，下文介绍如何通过接口获取对账单下载链接。更多后台下载及账单示例图详情可查看 。商家可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。4.1 系统交互流程1商家系统调用 ，传入指定日期，获得该日期账单文件的下载地址。2商家系统通过 http 方式后台访问账单下载链接，将账单 csv 文件下载到本地后自行处理。注意该下载链接仅 30 秒，在得到链接后系统需要立刻下载账单文件。4.2 示例代码4.2.1 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明bill_type固定传入 trade。bill_date需要下载的账单日期，最晚是当期日期的前一天。4.2.2 重要出参说明参数名参数说明bill_download_url账单文件下载地址，有效时长：30 秒。4.2.3 下载账单文件示例代码
