已更新更新时间：2024-11-27 10:36:10文档更新记录 >配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 后，商家/服务商可根据本文指引快速接入 app 支付。说明：●仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用方式，调用 api 接入。●支持沙箱环境调试。●需要服务端和客户端结合请求唤起支付。1 整体交互流程图以下对重点步骤做简要说明：●第 1 步用户在商户 app 客户端/小程序中购买商品下单。●第 2 步商户订单信息由商户 app 客户端/小程序发送到服务端。●第 3 步商家服务端调用 alipay.trade.app.pay（app支付接口2.0接口）通过支付宝服务端 sdk 获取 orderstr（orderstr 中包含了订单信息和签名）。●第 4 步商家将 orderstr 发送给商户 app 客户端/小程序。●第 5 步商家在客户端/小程序发起请求，将 orderstr 发送给支付宝。●第 6 步进行支付预下单：支付宝客户端将会按照商家客户端提供的请求参数进行支付预下单。正常场景下，会唤起支付宝收银台等待用户核身；异常场景下，会返回异常信息。●第 11 步返回商家 app/小程序：用户在支付宝 app 完成支付后，会跳转回商家页面，并返回最终的支付结果（即同步通知），可查看 同步通知说明。●第 13 步支付结果异步通知，支付宝会根据步骤3 传入的异步通知地址 notify_url，发送异步通知，可查看 。除了正向支付流程外，支付宝也提供交易查询、关闭、退款、退款查询以及对账等配套 api。1.1 重要说明1首先确认已完成开通产品、创建应用、绑定产品、应用上线等步骤，详情可查看 。2构造交易数据并签名必须在商家服务端完成，商家的应用私钥绝对不能保存在商家 app 客户端中，也不能从服务端下发。3服务端生成的orderstr只是加签数据，并未请求到支付宝，只有客户端/小程序请求后，支付宝才会收到商户的订单信息。4同步返回的数据，只是一个简单的结果通知，商家确定该笔交易付款是否成功需要依赖服务端收到支付宝异步通知的结果进行判断，建议通过异步 查询方式判断避免错失异步漏失交易信息。5商家系统接收到通知以后，必须通过验签（验证通知中的 sign 参数）来确保支付通知是由支付宝发送的。建议使用支付宝提供的 sdk 来完成，详细验签规则可查看 的 异步返回结果验签。6订单创建时间：支付宝订单将在用户输入正确完整的支付密码后创建，并非唤起收银台时创建（余额不足等情况会导致交易处于订单创建等待支付状态）。7订单支付超时时间：订单创建后未支付，默认最晚付款时间为 15 天，若超过第 15 天当天 24 点订单超时关闭不可支付（超时参数设置范围 5min～15d）。8异步或查询接口返回的 trade_status（交易状态）为 trade_success 或 trade_finished 时，支付宝才会认定为买家付款成功。9判断退款成功：退款接口返回 fund_change=y 或者退款查询接口返回 refund_status=refund_success。 注意：fund_change 只表示本次接口请求是否资金变动，不是指该笔交易是否资金变动。如果第一次退款成功，返回 y，但是相同参数（如 out_request_no 不变）第二次请求则会返回 n，因此当 fund_change=n 时，建议通过退款查询接口进一步判断。1.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 支付流程2.1 服务端接入2.1.1 服务端获取 orderstr开发者可通过外部商家 app 唤起服务端 sdk ，建议调用 alipay.trade.app.pay（app支付接口2.0接口）获取 orderstr。注意：支付宝订单将在用户输入支付密码后创建，并非唤起收银台时创建。订单实际创建时间也为用户支付时间，非唤起收银台时间。2.1.2 请求示例方式一：使用支付宝sdk (推荐) 示例代码、参数说明及错误码等信息，可查看 alipay.trade.app.pay（app支付接口2.0接口）接口文档。注意：证书模式加签也需通过 alipayclient.sdkexecute(request); 方法发起请求，获取 orderstr。orderstr 示例代码：方式二：自行构建请求 (不推荐) 若开发者无法使用支付宝 sdk，可根据以下步骤自行构建请求：1请求参数组装分下列 3 步，以最后第三步获取到的请求为准。 请求参数按照 key=value&key=value 方式拼接的未签名原始字符串：2再对原始字符串进行签名，可查看 自行实现签名 。3最后对请求字符串的所有一级 value（biz_content 作为一个 value）进行 encode，编码格式按请求串中的 charset 为准，没传 charset 按 utf-8 处理，获得最终的请求字符串。2.2 客户端接入2.2.1 商家 app注意：app 支付同步通过客户端配置完成回调，return_url 设置不生效。客户端 ios 集成流程详情可点击查看 ios 集成流程。客户端 android 集成流程详情可点击查看 android 集成流程。客户端 harmony 单框架 sdk 集成流程详情可点击查看 。客户端鸿蒙 sdk 集成流程详情可点击查看 。2.2.2 支付宝小程序小程序通过调用 进行请求支付。2.3 异步通知app 支付异步通知发送到 alipay.trade.app.pay（app支付接口2.0接口）加签时入参的公共参数 notify_url 地址中，未设置该参数则不触发异步。通知参数及规则详见 异步通知说明 。2.4 支付结果查询商家可调用 ，通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no 查询对应订单支付情况。2.4.1 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。3 退款流程交易发生后的一段时间内，由于业务原因（如金额错误、用户退款或者对账不平等）需要退款时，商家可以调用 ，通过 out_trade_no（商家网站唯一订单号）或trade_no（支付宝交易号），将对应订单支付款退还给买家。支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。说明：支持全额或部分退款。3.1 接口流程3.2 退款结果●退款成功：退款是否成功可以根据同步响应的 fund_change 参数来判断，返回值为 y 则表示退款成功。●退款失败：根据 中的错误码确认是否要重试，重试时注意 out_request_no 需保持一致。●系统异常：无法确认退款结果。○方案一：重试，重试时注意 out_request_no 需保持一致。○方案二：先调用 确认退款结果，如失败，再发起重试。3.3 退款说明●退款周期：默认12 个月，即交易发生后 12 个月内可发起退款，超过 12 个月则不可发起退款。●退款方式：资金原路返回用户账号。●退款退费：默认退款时手续费不退回。●支付渠道为花呗、余额等退款即时到账。●银行卡的退款时间以银行退款时间为准，一般情况下 2 小时内可到账（若退款到卡失败，退款金额会退回用户支付宝账户余额）。●商家可以在 中退款。●退款接口会根据外部请求号 out_request_no 幂等返回，因此同一笔交易需要多次部分退款时，必须使用不同的 out_request_no。3.3.1 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。out_request_no本次退款请求流水号，部分退款时必传。refund_amount本次退款金额。3.3.2 重要出参说明参数名参数说明refund_fee该笔交易已退款的总金额。3.4 退款到银行卡通知退款存在退到银行卡场景下时，支付宝会调用 根据银行回执消息发送退款完成信息至应用网关地址。重要说明●如需触发 alipay.trade.refund.depositback.completed（收单退款冲退完成通知），需要在调用 alipay.trade.refund（统一收单交易退款接口）时，传入参数 "query_options":["deposit_back_info"]。●开发者需登录 进入对应应用详情页，在 开发设置 > 消息服务 > from 平台 中订阅 alipay.trade.refund.depositback.completed（收单退款冲退完成通知）。更多 from 平台消息详情可查看 from 蚂蚁消息服务使用。3.4.1 重要参数说明参数名参数说明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.5 查询退款结果商家/服务商可调用 查询对应out_request_no（退款请求号）的退款情况。 重要说明1退款查询接口的trade_no、out_trade_no、out_request_no必须和退款接口保持一致，否则交易号一致，out_request_no不同，只会返回10000，success，但是没有具体的退款信息。2该接口的返回10000，仅代表本次查询操作成功，不代表退款成功，当接口返回的refund_status值为refund_success时表示退款成功，否则表示退款没有执行成功。3.5.1 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明out_trade_no支付时传入的商户订单号，与 trade_no 必填一个。trade_no支付时返回的支付宝交易号，与 out_trade_no 必填一个。4 对账流程目前支付宝对外的常用对账方式有两种：●一种是通过在 下载账单的方式来对账。●一种是通过调用接口的方式来实现对账，下文介绍如何通过接口获取对账单下载链接。更多后台下载及账单示例图详情可查看 。商家可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。4.1 接口流程1商家系统调用 ，传入指定日期，获得该日期账单文件的下载地址。2商家系统通过 http 方式后台访问账单下载链接，将账单 csv 文件下载到本地后自行处理。注意该下载链接仅 30 秒，在得到链接后系统需要立刻下载账单文件。4.2 重要入参说明注意：请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。参数名参数说明bill_type固定传入 trade。bill_date需要下载的账单日期，最晚是当期日期的前一天。4.3 下载账单文件示例代码5 附录：自定义参数说明 1商家在请求参数中，自己附加的一些额外参数，请勿和支付宝系统中约定的 key（如 alipay.trade.app.pay（app支付接口2.0）等接口 公共请求参数/请求参数）重名，否则将可能导致未知的异常。 a例如以下示例中 app_id=2014072300007148**&version=1.0&biz_content 的 key 是公共请求参数，商家/服务商自己的扩展参数需要放在 biz_content 内部，例如示例中 tips 属性，很显然下面 total_amount 属性是商家按照自己的业务属性赋值的，但是由于 total_amount 同时也是支付宝关键 key ，支付宝将会认为这个 total_amount 是支付宝业务的参数应该是金额，这个最终将导致误解析。b注意：下列请求串为了展示清晰，未进行 encode 并且做了格式化处理。 2商家的请求参数中，所有的 key（支付宝关键 key 或者商家自己的 key），其对应的 value 中都不应该出现支付宝关键 key，否则该类交易将可能被支付宝拦截禁止支付。 a例如以下的请求中 "subject":"大乐透 这个辣条不错 out_trade_no=123 total_fee=123.5"，其 value 值中有支付宝关键 key 值out_trade_no、total_fee，这样的业务请求参数支付宝将会拦截。b注意：下列请求串为了展示清晰，未进行 encode 并且做了格式化处理。 3商家支付请求参数的安全注意点a请求参数的 sign 字段请务必在服务端完成签名生成（不要在客户端本地签名）。b支付请求中的 total_amount（订单金额） ，请务必依赖服务端，不要轻信客户端上行的数据（客户端本地上行数据在用户手机环境中无法确保一定安全）。
