**接口功能：**外部商户 App 通过调用 [@alipay.trade.app.pay（app支付接口2.0接口）(API#alipay.trade.app.pay#api_url)](/API#alipay.trade.app.pay#api_url)接口唤起快捷 SDK 创建订单并支付。<br />**注意：**开发者在接入 **APP 支付** 功能时，调用支付接口时的参数和示例代码请以此文档为准。由于 alipay.trade.app.pay 接口还用于其它功能，可能会存在部分参数说明的冲突，如 product_code 等。<br />请求参数是商户在与支付宝进行数据交互时，提供给支付宝的请求数据，以便支付宝根据这些数据进一步处理。
<a name="8xlTG"></a>
# 公共参数
| **参数** | **类型** | **是否必填** | **最大长度** | **描述** | **示例值** |
| --- | --- | --- | --- | --- | --- |
| app_id | String | 是 | 32 | 支付宝分配给开发者的应用 APPID。 | 2014072300007148 |
| method | String | 是 | 128 | 接口名称 | alipay.trade.app.pay |
| format | String | 否 | 40 | 仅支持 JSON | JSON |
| charset | String | 是 | 10 | 请求使用的编码格式，App 支付建议使用 utf-8 格式，如使用gbk,gb2312 等格式会有“系统繁忙，请稍后再试”的报错 | utf-8 |
| sign_type | String | 是 | 10 | 商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 | RSA2 |
| sign | String | 是 | 256 | 商户请求参数的签名串，可查看 [签名](https://opendocs.alipay.com/common/02khjm)。 | 详情可查看示例 |
| timestamp | String | 是 | 19 | 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"。 | 2014-07-24 03:07:50 |
| version | String | 是 | 3 | 调用的接口版本，固定为：1.0。 | 1.0 |
| notify_url | String | 是 | 256 | 支付宝服务器主动通知商户服务器里指定的页面 HTTP/HTTPS 路径，建议商户使用 HTTPS。 | `https://api.xx.com/receive_notify.htm` |
| biz_content | String | 是 | - | 业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档 | - |

<a name="ZN5qf"></a>
# 请求参数
| **参数** | **类型** | **是否必填** | **最大长度** | **描述** | **示例值** |
| --- | --- | --- | --- | --- | --- |
| body | String | 否 | 128 | 对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。 | Iphone6 16G |
| subject | String | 是 | 256 | 商品的标题/交易标题/订单标题/订单关键字等。 | 大乐透 |
| out_trade_no | String | 是 | 64 | 商户网站唯一订单号 | 70501111111S001111119 |
| timeout_express | String | 否 | 6 | 该笔订单允许的最晚付款时间，逾期将关闭交易。取值范围：1m～15d。m-分钟，h-小时，d-天，1c-当天（1c-当天的情况下，无论交易何时创建，都在0点关闭）。 该参数数值不接受小数点， 如 1.5h，可转换为 90m。<br />**注意：**若为空，则默认为15d。 | 90m |
| total_amount | String | 是 | 9 | 订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] | 9.00 |
| product_code | String | 是 | 64 | 销售产品码，商家和支付宝签约的产品码，APP支付功能中该值固定为： QUICK_MSECURITY_PAY | QUICK_MSECURITY_PAY |
| goods_type | String | 否 | 2 | 商品主类型。<br />- 0：虚拟类商品。<br />- 1：实物类商品。<br />
**注意：**虚拟类商品不支持使用花呗渠道 | 0 |
| goods_detail | GoodsDetail[]  | 否 |  | 订单包含的商品列表信息，JSON 格式，其它说明可查看商品明细说明。<br />详情可查看 [@alipay.trade.app.pay（app支付接口2.0接口）(API#alipay.trade.app.pay#api_url)](/API#alipay.trade.app.pay#api_url)。 |  |
| passback_params | String | 否 | 512 | 公用回传参数，如果请求时传递了该参数，则返回给商户时会回传该参数。支付宝会在异步通知时将该参数原样返回。本参数必须进行 UrlEncode 之后才可以发送给支付宝。 | merchantBizType%3d3C%26merchantBizNo%3d2016010101111 |
| promo_params | String | 否 | 512 | 优惠参数。<br />**注意：**仅与支付宝协商后可用。 | {"storeIdType":"1"} |
| extend_params | String | 否 |  | 业务扩展参数，可查看下表的 **业务扩展参数(extend_params)说明。** | {"sys_service_provider_id":"2088511833207846"} |
| enable_pay_channels | String | 否 | 128 | 可用渠道，用户只能在指定渠道范围内支付 当有多个渠道时用“,”分隔。<br />**注意：**与 disable_pay_channels 互斥，可用支付渠道可查看下方 **渠道说明**。 | pcredit,moneyFund,debitCardExpress |
| disable_pay_channels | String | 否 | 128 | 禁用渠道，用户不可用指定渠道支付 当有多个渠道时用“,”分隔。<br />**注意：**与 enable_pay_channels 互斥，可用支付渠道可查看下方 **渠道说明**。 | pcredit,moneyFund,debitCardExpress |
| store_id | String | 否 | 32 | 商户门店编号。该参数用于请求参数中以区分各门店，非必传项。 | NJ_001 |
| ext_user_info | ExtUserInfo | 否 |  | 外部指定买家，可查看 **外部指定买家(ext_user_info)参数说明**。 |  |

<a name="juCLE"></a>
## 业务扩展参数（extend_params）说明
| 参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| sys_service_provider_id | String | 否 | 64 | 系统商编号，该参数作为系统商返佣数据提取的依据，请填写系统商签约协议的PID | 2088511833207846 |
| needBuyerRealnamed | String | 否 | 1 | 是否发起实名校验。<br />- T：发起。<br />- F：不发起。<br /> | T |
| TRANS_MEMO | String | 否 | 128 | 账务备注。<br />**注意**：该字段显示在离线账单的账务备注中 | 促销 |
| hb_fq_num | String | 否 | 5 | 花呗分期数（目前仅支持 3、6、12） 。<br />**注意**：使用该参数需要仔细阅读 [花呗分期接入文档](https://opendocs.alipay.com/open/01ug57?pathHash=6a1eac03)。 | 3 |
| hb_fq_seller_percent | String | 否 | 3 | 卖家承担收费比例，商家承担手续费传入 100，用户承担手续费传入 0，仅支持传入100、0 两种，其它比例暂不支持。<br />**注意：**使用该参数需要仔细阅读 [花呗分期接入文档](https://opendocs.alipay.com/open/01ug57?pathHash=6a1eac03)。 | 100 |

<a name="6ZIXL"></a>
## 渠道说明
| **渠道名称** | **说明** |
| --- | --- |
| balance | 余额 |
| moneyFund | 余额宝 |
| coupon | 红包 |
| pcredit | 花呗 |
| pcreditpayInstallment | 花呗分期 |
| creditCard | 信用卡 |
| creditCardExpress | 信用卡快捷 |
| creditCardCartoon | 信用卡卡通 |
| credit_group | 信用支付类型（包含信用卡卡通、信用卡快捷、花呗、花呗分期） |
| debitCardExpress | 借记卡快捷 |
| mcard | 商户预存卡 |
| pcard | 个人预存卡 |
| promotion | 优惠（包含实时优惠+商户优惠） |
| voucher | 营销券 |
| point | 积分 |
| mdiscount | 商户优惠 |
| bankPay | 网银 |

<a name="YOS98"></a>
### 外部指定买家(ext_user_info)参数说明
| **参数** | **类型** | **是否必填** | **最大长度** | **描述** | **示例值** |
| --- | --- | --- | --- | --- | --- |
| name | String | 否 | 16 | 姓名<br />**注意**： need_check_info=T时该参数才有效 | 李明 |
| mobile | String | 否 | 20 | 手机号<br />**注意**：该参数暂不校验 | 16587658765 |
| cert_type | String | 否 | 32 | 身份证：IDENTITY_CARD、护照：PASSPORT、军官证：OFFICER_CARD、士兵证：SOLDIER_CARD、户口本：HOKOU等。如有其它类型需要支持，请与技术支持联系。<br />**注意**： need_check_info=T时该参数才有效 | IDENTITY_CARD |
| cert_no | String | 否 | 64 | 证件号。<br />**注意**：need_check_info=T时该参数才有效 | 362334768769238881 |
| min_age | String | 否 | 3 | 允许的最小买家年龄，买家年龄必须大于等于所传数值。<br />**注意**：<br />- need_check_info=T 时该参数才有效。<br />- min_age为整数，必须大于等于 0。<br /> | 18 |
| fix_buyer | String | 否 | 8 | 是否强制校验付款人身份信息<br />T:强制校验，F：不强制 | F |
| need_check_info | String | 否 | 1 | 是否强制校验身份信息<br />T:强制校验，F：不强制 | F |

<a name="P4mLG"></a>
# 请求示例
请求参数组装分下列 3 步，以最后第三步获取到的请求为准。 

1. 请求参数按照 `key=value&key=value` 方式拼接的未签名原始字符串：
```javascript
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
```

2. 再对原始字符串进行签名，可查看 [签名规则](https://opendocs.alipay.com/common/02khjm)：
```javascript
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=
```

3. 最后对请求字符串的所有一级 value（biz_content 作为一个 value）进行 encode，编码格式按请求串中的 charset 为准，没传 charset 按 UTF-8 处理，获得最终的请求字符串：
```javascript
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
```
<a name="vbQJa"></a>
# 特殊说明（很重要）

1. 商户在请求参数中，自己附属的一些额外参数，不要和支付宝系统中约定的 key（下表中 公共请求参数\请求参数）重名，否则将可能导致未知的异常。 例如以下示例中 `app_id=2014072300007148**&version=1.0&biz_content` 的 key 是公共请求参数，业务方自己的扩展参数需要放在 `biz_content` 内部，例如示例中 tips 属性,很显然下面 total_amount 属性是商户按照自己的业务属性赋值的，但是由于 total_amount 也是支付宝关键 key，支付宝将会认为这个 total_amount 是支付宝业务的参数应该是金额，这个最终将导致误解析。下列请求串为了展示清晰，未进行 encode 并且做了格式化处理，下同。
```javascript
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":"测试一笔支付"
   }
```

2. 商户的请求参数中，所有的 key（支付宝关键 key 或者商户自己的 key），其对应的 value 中都不应该出现支付宝关键 key，否则该类交易将可能被支付宝拦截禁止支付。 例如以下的请求中"subject":“大乐透 这个辣条不错 out_trade_no=123 total_fee=123.5”，其 value 值中有支付宝关键 key "`out_trade_no`"、"`total_fee`"，这样的业务请求参数支付宝将会拦截。
```javascript
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"
   }
```

3. 商户支付请求参数的安全注意点： 
   1. 请求参数的 sign 字段请务必在服务端完成签名生成（**不要在客户端本地签名**）；
   2. 支付请求中的订单金额 total_amount，**请务必依赖服务端，不要轻信客户端上行的数据**（客户端本地上行数据在用户手机环境中无法确保一定安全）。