完成接入准备后，商家/服务商可根据本文指引快速接入 App 支付。

说明：

仅支持自研商家/服务商通过自研应用或第三方应用代调用方式，调用 API 接入。

支持沙箱环境调试。

需要服务端和客户端结合请求唤起支付。

整体交互流程图

以下对重点步骤做简要说明：

第 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。

重要说明

首先确认已完成开通产品、创建应用、绑定产品、应用上线等步骤，详情可查看接入准备。

构造交易数据并签名必须在商家服务端完成，商家的应用私钥绝对不能保存在商家 APP 客户端中，也不能从服务端下发。

服务端生成的orderStr只是加签数据，并未请求到支付宝，只有客户端/小程序请求后，支付宝才会收到商户的订单信息。

同步返回的数据，只是一个简单的结果通知，商家确定该笔交易付款是否成功需要依赖服务端收到支付宝异步通知的结果进行判断，建议通过异步+查询方式判断避免错失异步漏失交易信息。

商家系统接收到通知以后，必须通过验签（验证通知中的 sign 参数）来确保支付通知是由支付宝发送的。建议使用支付宝提供的 SDK 来完成，详细验签规则可查看异步通知验签。

订单创建时间：支付宝订单将在用户输入正确完整的支付密码后创建，并非唤起收银台时创建（余额不足等情况会导致交易处于订单创建等待支付状态）。

订单支付超时时间：订单创建后未支付，默认最晚付款时间为 15 天，若超过第 15 天当天 24 点订单超时关闭不可支付（超时参数设置范围 5min～15d）。

异步或查询接口返回的 trade_status（交易状态）为 TRADE_SUCCESS 或 TRADE_FINISHED 时，支付宝才会认定为买家付款成功。

判断退款成功：退款接口返回 fund_change=Y 或者退款查询接口返回 refund_status=REFUND_SUCCESS。
注意：fund_change 只表示本次接口请求是否资金变动，不是指该笔交易是否资金变动。如果第一次退款成功，返回 Y，但是相同参数（如 out_request_no 不变）第二次请求则会返回 N，因此当 fund_change=N 时，建议通过退款查询接口进一步判断。

交易状态流程

随着订单支付成功、退款、关闭等操作，订单交易的每一个环节 trade_status（交易状态）也不同。

交易创建成功后，用户支付成功，交易状态转为 TRADE_SUCCESS（交易成功）。

交易成功后，规定退款时间内没有退款，交易状态转为 TRADE_FINISHED（交易完成）。

交易支付成功后，交易部分退款，交易状态仍为 TRADE_SUCCESS（交易成功）。

交易成功后，交易全额退款，交易状态转为 TRADE_CLOSED（交易关闭）。

交易创建成功后，用户未付款交易超时关闭，交易状态转为 TRADE_CLOSED（交易关闭）。

交易创建成功后，用户支付成功后，若用户商品不支持退款，交易状态直接转为 TRADE_FINISHED（交易完成）。

注意：交易成功后部分退款，交易状态仍为 TRADE_SUCCESS（交易成功）。

如果一直部分退款退完所有交易金额则交易状态转为 TRADE_CLOSED（交易关闭）。

如果未退完所有交易金额，超过有效退款时间后交易状态转为 TRADE_FINISHED（交易完成）不可退款。

支付流程

服务端接入

服务端获取 orderStr

开发者可通过外部商家 App 唤起服务端 SDK ，建议调用 alipay.trade.app.pay (app支付接口2.0) 获取 orderStr。

**注意：**支付宝订单将在用户输入支付密码后创建，并非唤起收银台时创建。订单实际创建时间也为用户支付时间，非唤起收银台时间。

请求示例

方式一：使用支付宝SDK (推荐)

示例代码、参数说明及错误码等信息，可查看 alipay.trade.app.pay（app支付接口2.0）接口文档。

**注意：**证书模式加签也需通过 alipayClient.sdkExecute(request); 方法发起请求，获取 orderStr。

orderStr 示例代码：

alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=2014100900010000&biz_content=%7B%22total_amount%22%3A%220.01%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22subject%22%3A%22%E5%93%88%E5%93%88%E5%93%88%E5%93%88%E5%93%88%E5%A4%A7%E4%B9%90%E9%80%8F%22%2C%22out_trade_no%22%3A%2220220530000000011111101%22%7D&charset=utf-8&format=json&method=alipay.trade.app.pay&sign=iuO%2FTso2zr236p%2F%2FgyVoM9B7JGhyQqHHlL82siLLPI90xUruDVRt8hIOAroNid%2FTCbYUENSV4FkIZ5krrXm1qDFLHUnvtsUA3kToEojxyKilR8czZFYm6w91oxJseFZQJe0Os6IJg8oG29tYRf9TiXjB0leSwGQ3Ax8VilW2ATsne9L4A9Xah5fz7PTlKURTMYFqU166J2RH769wtTOjOb5Gs74aSdB3ymlZ486%2FGAcFwyXSvd3i8FEzsx3obLaM3oRQGQ%2Fx2jn8aL5qH3nVkGFIKA4xAUOZAaZSrj4EFw17HPFBYvcPwG55DQlmyLluh5lb4Ibi3j1ZxR4NiB0YFQ%3D%3D&sign_type=RSA2&timestamp=2022-05-30+17%3A43%3A28&version=1.0

方式二：自行构建请求 (不推荐)

若开发者无法使用支付宝 SDK，可根据以下步骤自行构建请求：

请求参数组装分下列 3 步，以最后第三步获取到的请求为准。请求参数按照 key=value&key=value 方式拼接的未签名原始字符串：

app_id=2015052600090779&biz_content={"timeout_express":"30m","product_code":"QUICK_MSECURITY_PAY","total_amount":"0.01","subject":"1","body":"我是测试数据","out_trade_no":"IQJZSRC1YMQB5HU"}&charset=utf-8&format=json&method=alipay.trade.app.pay&notify_url=http://domain.merchant.com/payment_notify&sign_type=RSA2&timestamp=2016-08-25 20:26:31&version=1.0

再对原始字符串进行签名，可查看自行实现签名。

app_id=2015052600090779&biz_content={"timeout_express":"30m","product_code":"QUICK_MSECURITY_PAY","total_amount":"0.01","subject":"1","body":"我是测试数据","out_trade_no":"IQJZSRC1YMQB5HU"}&charset=utf-8&format=json&method=alipay.trade.app.pay&notify_url=http://domain.merchant.com/payment_notify&sign_type=RSA2&timestamp=2016-08-25 20:26:31&version=1.0&sign=cYmuUnKi5QdBsoZEAbMXVMmRWjsuUj+y48A2DvWAVVBuYkiBj13CFDHu2vZQvmOfkjE0YqCUQE04kqm9Xg3tIX8tPeIGIFtsIyp/M45w1ZsDOiduBbduGfRo1XRsvAyVAv2hCrBLLrDI5Vi7uZZ77Lo5J0PpUUWwyQGt0M4cj8g=

最后对请求字符串的所有一级 value（biz_content 作为一个 value）进行 encode，编码格式按请求串中的 charset 为准，没传 charset 按 UTF-8 处理，获得最终的请求字符串。

app_id=2015052600090779&biz_content=%7B%22timeout_express%22%3A%2230m%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22total_amount%22%3A%220.01%22%2C%22subject%22%3A%221%22%2C%22body%22%3A%22%E6%88%91%E6%98%AF%E6%B5%8B%E8%AF%95%E6%95%B0%E6%8D%AE%22%2C%22out_trade_no%22%3A%22IQJZSRC1YMQB5HU%22%7D&charset=utf-8&format=json&method=alipay.trade.app.pay&notify_url=http%3A%2F%2Fdomain.merchant.com%2Fpayment_notify&sign_type=RSA2&timestamp=2016-08-25%2020%3A26%3A31&version=1.0&sign=cYmuUnKi5QdBsoZEAbMXVMmRWjsuUj%2By48A2DvWAVVBuYkiBj13CFDHu2vZQvmOfkjE0YqCUQE04kqm9Xg3tIX8tPeIGIFtsIyp%2FM45w1ZsDOiduBbduGfRo1XRsvAyVAv2hCrBLLrDI5Vi7uZZ77Lo5J0PpUUWwyQGt0M4cj8g%3D

客户端接入

商家 APP

注意：App 支付同步通过客户端配置完成回调，return_url 设置不生效。

客户端 iOS 集成流程

详情可点击查看客户端 iOS 集成流程。

客户端 Android 集成流程

详情可点击查看客户端 Android 集成流程。

客户端鸿蒙 SDK 集成流程

详情可点击查看鸿蒙 SDK 集成流程。

支付宝小程序

小程序通过调用 my.tradePay 进行请求支付。

// .js
my.tradePay({
  // 调用接口返回的orderStr
  orderStr: 'alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=2014100900010000&biz_content=%7B%22total_amount%22%3A%220.01%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22subject%22%3A%22%E5%93%88%E5%93%88%E5%93%88%E5%93%88%E5%93%88%E5%A4%A7%E4%B9%90%E9%80%8F%22%2C%22out_trade_no%22%3A%2220220530000000011111101%22%7D&charset=utf-8&format=json&method=alipay.trade.app.pay&sign=iuO%2FTso2zr236p%2F%2FgyVoM9B7JGhyQqHHlL82siLLPI90xUruDVRt8hIOAroNid%2FTCbYUENSV4FkIZ5krrXm1qDFLHUnvtsUA3kToEojxyKilR8czZFYm6w91oxJseFZQJe0Os6IJg8oG29tYRf9TiXjB0leSwGQ3Ax8VilW2ATsne9L4A9Xah5fz7PTlKURTMYFqU166J2RH769wtTOjOb5Gs74aSdB3ymlZ486%2FGAcFwyXSvd3i8FEzsx3obLaM3oRQGQ%2Fx2jn8aL5qH3nVkGFIKA4xAUOZAaZSrj4EFw17HPFBYvcPwG55DQlmyLluh5lb4Ibi3j1ZxR4NiB0YFQ%3D%3D&sign_type=RSA2&timestamp=2022-05-30+17%3A43%3A28&version=1.0',
  success: (res) => {
    my.alert({
    content: JSON.stringify(res),
  });
  },
  fail: (res) => {
    my.alert({
    content: JSON.stringify(res),
  });
  }
});

异步通知

App 支付异步通知发送到 alipay.trade.app.pay（app支付接口2.0）加签时入参的公共参数 notify_url 地址中，未设置该参数则不触发异步。

通知参数及规则详见异步通知说明。

支付结果查询

商家可调用 alipay.trade.query（统一收单线下交易查询接口），通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no 查询对应订单支付情况。

重要入参说明

**注意：**请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

参数名	参数说明
out_trade_no	支付时传入的商户订单号，与 trade_no 必填一个。
trade_no	支付时返回的支付宝交易号，与 out_trade_no 必填一个。

退款流程

交易发生后的一段时间内，由于业务原因（如金额错误、用户退款或者对账不平等）需要退款时，商家可以调用 alipay.trade.refund（统一收单交易退款接口），通过 out_trade_no（商家网站唯一订单号）或trade_no（支付宝交易号），将对应订单支付款退还给买家。支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。

**说明：**支持全额或部分退款。

接口流程

退款结果

退款成功：退款是否成功可以根据同步响应的 fund_change 参数来判断，返回值为 Y 则表示退款成功。

退款失败：根据错误码确认是否要重试，重试时注意 out_request_no 需保持一致。

系统异常：无法确认退款结果。

方案一：重试，重试时注意 out_request_no 需保持一致。

方案二：先调用 alipay.trade.fastpay.refund.query（统一收单交易退款查询接口）确认退款结果，如失败，再发起重试。

退款说明

**退款周期：**默认12 个月，即交易发生后 12 个月内可发起退款，超过 12 个月则不可发起退款。

**退款方式：**资金原路返回用户账号。

**退款退费：**默认退款时手续费不退回。

支付渠道为花呗、余额等退款即时到账。

银行卡的退款时间以银行退款时间为准，一般情况下 2 小时内可到账（若退款到卡失败，退款金额会退回用户支付宝账户余额）。

商家可以在商家平台 > 对账中心 > 交易订单中退款。

退款接口会根据外部请求号 out_request_no 幂等返回，因此同一笔交易需要多次部分退款时，必须使用不同的 out_request_no。

重要入参说明

**注意：**请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

参数名	参数说明
out_trade_no	支付时传入的商户订单号，与 trade_no 必填一个。
trade_no	支付时返回的支付宝交易号，与 out_trade_no 必填一个。
out_request_no	本次退款请求流水号，部分退款时必传。
refund_amount	本次退款金额。

重要出参说明

参数名	参数说明
refund_fee	该笔交易已退款的总金额。

退款到银行卡通知

退款存在退到银行卡场景下时，支付宝会调用 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。

查询退款结果

商家/服务商可调用 alipay.trade.fastpay.refund.query（统一收单交易退款查询接口）查询对应out_request_no（退款请求号）的退款情况。

重要说明

退款查询接口的trade_no、out_trade_no、out_request_no必须和退款接口保持一致，否则交易号一致，out_request_no不同，只会返回10000，success，但是没有具体的退款信息。

该接口的返回10000，仅代表本次查询操作成功，不代表退款成功，当接口返回的refund_status值为REFUND_SUCCESS时表示退款成功，否则表示退款没有执行成功。

重要入参说明

**注意：**请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

参数名	参数说明
out_trade_no	支付时传入的商户订单号，与 trade_no 必填一个。
trade_no	支付时返回的支付宝交易号，与 out_trade_no 必填一个。

对账流程

目前支付宝对外的常用对账方式有两种：

一种是通过在商家平台 > 对账中心下载账单的方式来对账。

一种是通过调用接口的方式来实现对账，下文介绍如何通过接口获取对账单下载链接。更多后台下载及账单示例图详情可查看对账说明。

商家可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。

接口流程

商家系统调用 alipay.data.dataservice.bill.downloadurl.query（查询对账单下载地址接口），传入指定日期，获得该日期账单文件的下载地址。

商家系统通过 HTTP 方式后台访问账单下载链接，将账单 csv 文件下载到本地后自行处理。注意该下载链接仅 30 秒，在得到链接后系统需要立刻下载账单文件。

重要入参说明

**注意：**请严格按照接口文档中的参数入参，传入非接口文档中的参数是无效的，并且可能会导致请求被拦截或其它异常。

参数名	参数说明
bill_type	固定传入 trade。
bill_date	需要下载的账单日期，最晚是当期日期的前一天。

下载账单文件示例代码

//将接口返回的对账单下载地址传入urlStr
String urlStr = "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&userId=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X";
//指定希望保存的文件路径
String filePath = "/Users/fund_bill_20160405.csv.zip";
URL url = null;
HttpURLConnection httpUrlConnection = null;
InputStream fis = null;
FileOutputStream fos = null;
try {
    url = new URL(urlStr);
    httpUrlConnection = (HttpURLConnection) url.openConnection();
    httpUrlConnection.setConnectTimeout(5 * 1000);
    httpUrlConnection.setDoInput(true);
    httpUrlConnection.setDoOutput(true);
    httpUrlConnection.setUseCaches(false);
    httpUrlConnection.setRequestMethod("GET");
    httpUrlConnection.setRequestProperty("CHARSET", "UTF-8");
    httpUrlConnection.connect();
    fis = httpUrlConnection.getInputStream();
    byte[] temp = new byte[1024];
    int b;
    fos = new FileOutputStream(new File(filePath));
    while ((b = fis.read(temp)) != -1) {
        fos.write(temp, 0, b);
        fos.flush();
    }
} catch (MalformedURLException e) {
    e.printStackTrace();
} catch (IOException e) {
    e.printStackTrace();
} finally {
    try {
        if(fis!=null) fis.close();
        if(fos!=null) fos.close();
        if(httpUrlConnection!=null) httpUrlConnection.disconnect();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

附录：自定义参数说明

商家在请求参数中，自己附属的一些额外参数，请勿和支付宝系统中约定的 key（如 alipay.trade.app.pay（app支付接口2.0）等接口 公共请求参数/请求参数）重名，否则将可能导致未知的异常。

例如以下示例中 app_id=2014072300007148**&version=1.0&biz_content 的 key 是公共请求参数，商家/服务商自己的扩展参数需要放在 biz_content 内部，例如示例中 tips 属性，很显然下面 total_amount 属性是商家按照自己的业务属性赋值的，但是由于 total_amount 同时也是支付宝关键 key ，支付宝将会认为这个 total_amount 是支付宝业务的参数应该是金额，这个最终将导致误解析。

**注意：**下列请求串为了展示清晰，未进行 encode 并且做了格式化处理。

app_id=2014072300007148&charset=UTF-8&version=1.0&timestamp=2016-07-01 08:08:08&method=alipay.trade.app.pay&notify_url=https://api.**.com/pay_receive_notify.html&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content=
{
  "body":"对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。",
  "subject":"大乐透",
  "out_trade_no":"70501111111S001111119",
  "timeout_express":"90m",
  "total_amount":"一共花费了10元",
  "product_code":"QUICK_MSECURITY_PAY",
  "tips":"测试一笔支付"
  }

商家的请求参数中，所有的 key（支付宝关键 key 或者商家自己的 key），其对应的 value 中都不应该出现支付宝关键 key，否则该类交易将可能被支付宝拦截禁止支付。

例如以下的请求中 "subject":"大乐透这个辣条不错 out_trade_no=123 total_fee=123.5"，其 value 值中有支付宝关键 key 值out_trade_no、total_fee，这样的业务请求参数支付宝将会拦截。

**注意：**下列请求串为了展示清晰，未进行 encode 并且做了格式化处理。

app_id=2014072300007148&charset=UTF-8&version=1.0&timestamp=2016-07-01 08:08:08&method=alipay.trade.app.pay&notify_url=https://api.**.com/pay_receive_notify.htm&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content=
  {
    "body":"对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。",
    "subject":"大乐透 这个辣条不错 out_trade_no=123 total_fee=123.5",
    "out_trade_no":"70501111111S001111119",
    "timeout_express":"90m",
    "total_amount":10.0,
    "product_code":"QUICK_MSECURITY_PAY"
  }

商家支付请求参数的安全注意点

请求参数的 sign 字段请务必在服务端完成签名生成（不要在客户端本地签名）。

支付请求中的 total_amount（订单金额），请务必依赖服务端，不要轻信客户端上行的数据（客户端本地上行数据在用户手机环境中无法确保一定安全）。

APP 支付快速接入

整体交互流程图#

重要说明#

交易状态流程#

支付流程#

服务端接入#

服务端获取 orderStr#

请求示例#

方式一：使用支付宝SDK (推荐)#

方式二：自行构建请求 (不推荐)#

客户端接入#

商家 APP#

客户端 iOS 集成流程#

客户端 Android 集成流程#

客户端鸿蒙 SDK 集成流程#

支付宝小程序#

异步通知#

支付结果查询#

重要入参说明#

退款流程#

接口流程#

退款结果#

退款说明#

重要入参说明#

重要出参说明#

退款到银行卡通知#

重要参数说明#

查询退款结果#

重要入参说明#

对账流程#

接口流程#

重要入参说明#

下载账单文件示例代码#

附录：自定义参数说明#

整体交互流程图

重要说明

交易状态流程

支付流程

服务端接入

服务端获取 orderStr

请求示例

方式一：使用支付宝SDK (推荐)

方式二：自行构建请求 (不推荐)

客户端接入

商家 APP

客户端 iOS 集成流程

客户端 Android 集成流程

客户端鸿蒙 SDK 集成流程

支付宝小程序

异步通知

支付结果查询

重要入参说明

退款流程

接口流程

退款结果

退款说明

重要入参说明

重要出参说明

退款到银行卡通知

重要参数说明

查询退款结果

重要入参说明

对账流程

接口流程

重要入参说明

下载账单文件示例代码

附录：自定义参数说明