更新时间：2025-04-14 20:11:46收藏订阅更新我的文档设置返回文档完成 后，商家/服务商可根据本文指引快速集成 订单码支付 产品。说明：●订单码支付 仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用方式，调用 api 接入。●订单码支付 支持沙箱环境调试，详情可查看 。1 接入方式订单码支付适合有各类自助终端的商家，用户在自助终端通过扫码完成支付。订单码支付采用 商家/系统服务商后台转发 方式接入，商家先预下单到商家后台，再请求到支付宝。1.1 接入流程支付宝为了保证交易安全采取了一系列安全手段以保证交易安全。主要采用以下安全设计策略，详情可点击了解 应用安全开发指南 。●采用 https 协议传输交易数据，防止数据被截获、解密。●采用 rsa/rsa2 非对称密钥，明确交易双方的身份，保证交易主体的正确性和唯一性。2 支付流程2.1 系统交互流程1商家系统调用，获得该订单的二维码串 qr_code，开发者需要利用二维码生成工具获得最终的订单二维码图片。2发起轮询获得支付结果：等待 5 秒后调用 ，通过支付时传入的商户订单号（out_trade_no）查询支付结果（返回参数 trade_status）。a如果仍然返回等待用户付款（wait_buyer_pay），则再次等待 5 秒后继续查询，直到返回确切的支付结果（成功 trade_success 或 已撤销关闭 trade_closed），或是超出轮询时间。b在最后一次查询仍然返回等待用户付款的情况下，必须立即调用 将这笔交易撤销，避免用户继续支付。3除了主动轮询，当订单支付成功时，商家也可以通过设置异步通知（notify_url）来获得支付宝服务端返回的支付结果，详情可查看 ，注意一定要对异步通知验签，确保通知是支付宝发出的。注意：如商家由于客观原因（如无公网服务器接受支付宝请求等）无法接受异步支付通知，则忽略上图中的步骤 3.4 和 3.4.1。更多注意事项可点击查看 。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 下单商家可调用 传入订单商品及金额的信息，支付宝将返回支付二维码字符串，商家需利用二维码生成工具将二维码字符串转换为二维码用于用户扫码支付。重要说明：1接口请求成功后返回 qr_code 开始计时，有效期 2 小时。2涉及返佣必传 sys_service_provider_id。3扫码支付不存在同步跳转，支付后只会触发异步通知。2.3.1 示例代码2.3.2 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。请求参数说明out_trade_no商户订单号，需要保证商家系统不重复。total_amount订单金额。subject商品的标题/交易标题/订单标题/订单关键字等。不可使用特殊字符，如 /，=，& 等。product_code产品码，固定传：qr_code_offline。2.3.3 重要出参说明请求参数说明qr_code订单二维码（有效时间 2 小时）以字符串的格式返回，开发者需要自己使用工具根据内容生成二维码图片。2.4 查询交易商家可调用 ，通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no 查询对应订单支付情况。2.4.1 示例代码2.4.2 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。请求参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。2.5 撤销交易支付交易返回失败或支付系统超时，商家可调用 通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no 撤销交易。重要说明●如果此订单用户支付失败，支付宝将关闭此订单，用户无法继续支付。●如果此订单用户支付成功，支付宝将退还订单资金给用户，交易状态变为trade_close（交易关闭）。●仅发生支付系统超时或者支付结果未知时可调用本接口撤销交易，其它正常支付的单如需实现相同功能请调用 。2.5.1 示例代码 2.5.2 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。请求参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。2.5.3 重要出参说明请求参数说明retry_flag是否需要重试，枚举支持：●y：撤销不成功，需要重新调用接口。●n：撤销不成功，不需要重新调用接口。action本次撤销触发的交易动作。●close：关闭交易，无退款 。●refund：产生了退款。3 退款流程当交易发生之后一段时间内，由于业务原因（如金额错误，用户退款或者对账不平等等）需要退款时，商家可以调用 通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no，将对应订单支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。支持全额或部分退款。3.1 系统交互流程3.2 退款说明●支付渠道为花呗、余额等退款即时到账。●银行卡的退款时间以银行退款时间为准，一般情况下 2 小时内可到账。●商家可以在 商家平台 > 对账中心 > 中退款。●退款是否成功可以根据同步响应的 fund_change 参数来判断，返回值为 y 则表示退款成功。●退款接口会根据外部请求号 out_request_no 幂等返回，因此同一笔交易需要多次部分退款时，必须使用不同的 out_request_no 。3.2.1 示例代码重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。请求参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。out_request_no本次退款请求流水号，部分退款时必传。refund_amount本次退款金额。重要出参说明请求参数说明refund_fee该笔交易已退款的总金额。3.2.2 退款到银行卡通知退款存在退到银行卡场景下时，支付宝会调用 根据银行回执消息发送退款完成信息至应用网关地址。 重要说明：●如需触发 ，需要在调用 时，传入参数 "query_options":["deposit_back_info"]。●开发者需登录 进入对应应用详情页，在 开发设置 > from 平台 中订阅 。更多消息服务中 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。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 下载账单文件示例代码
