全部文档
开发文档 / App支付 /
/

请求参数说明

更新时间：2019-12-05

接口功能：外部商户App唤起快捷 SDK 创建订单并支付。


请求参数是商户在与支付宝进行数据交互时，提供给支付宝的请求数据，以便支付宝根据这些数据进一步处理。


公共参数

参数

类型

是否必填

最大长度

描述

示例值

app_id

String

是

32

支付宝分配给开发者的应用ID

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

商户请求参数的签名串，详见签名

详见示例

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

是

-

业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档



业务参数


参数

类型

是否必填

最大长度

描述

示例值

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。
注：若为空，则默认为15d。

90m

total_amount

String

是

9

订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]

9.00

product_code

String

是

64

销售产品码，商家和支付宝签约的产品码，为固定值 QUICK_MSECURITY_PAY

QUICK_MSECURITY_PAY

goods_type

String

否

2

商品主类型：0—虚拟类商品；1—实物类商品
注：虚拟类商品不支持使用花呗渠道

0

passback_params

String

否

512

公用回传参数，如果请求时传递了该参数，则返回给商户时会回传该参数。支付宝会在异步通知时将该参数原样返回。本参数必须进行 UrlEncode 之后才可以发送给支付宝

merchantBizType%3d3C%26merchantBizNo%3d2016010101111

promo_params

String

否

512

优惠参数
注：仅与支付宝协商后可用

{"storeIdType":"1"}

extend_params

String

否


业务扩展参数，详见下表的 业务扩展参数说明

{"sys_service_provider_id":"2088511833207846"}

enable_pay_channels

String

否

128

可用渠道，用户只能在指定渠道范围内支付
当有多个渠道时用“,”分隔
注：与 disable_pay_channels 互斥

pcredit,moneyFund,debitCardExpress

disable_pay_channels

String

否

128

禁用渠道，用户不可用指定渠道支付
当有多个渠道时用“,”分隔
注：与 enable_pay_channels 互斥

pcredit,moneyFund,debitCardExpress

store_id

String

否

32

商户门店编号。该参数用于请求参数中以区分各门店，非必传项。

NJ_001

ext_user_info

ExtUserInfo

否


外部指定买家，详见外部用户ExtUserInfo参数说明




业务扩展参数说明


参数

类型

是否必填

最大长度

描述

示例值

sys_service_provider_id

String

否

64

系统商编号，该参数作为系统商返佣数据提取的依据，请填写系统商签约协议的PID

2088511833207846

needBuyerRealnamed

String

否

1

是否发起实名校验
T：发起
F：不发起

T

TRANS_MEMO

String

否

128

账务备注
注：该字段显示在离线账单的账务备注中

促销

hb_fq_num

String

否

5

花呗分期数（目前仅支持3、6、12）
注：使用该参数需要仔细阅读“花呗分期接入文档”

3

hb_fq_seller_percent

String

否

3

卖家承担收费比例，商家承担手续费传入100，用户承担手续费传入0，仅支持传入100、0两种，其他比例暂不支持
注：使用该参数需要仔细阅读“花呗分期接入文档”

100



渠道说明


渠道名称

说明

balance

余额

moneyFund

余额宝

coupon

红包

pcredit

花呗

pcreditpayInstallment

花呗分期

creditCard

信用卡

creditCardExpress

信用卡快捷

creditCardCartoon

信用卡卡通

credit_group

信用支付类型（包含信用卡卡通、信用卡快捷、花呗、花呗分期）

debitCardExpress

借记卡快捷

mcard

商户预存卡

pcard

个人预存卡

promotion

优惠（包含实时优惠+商户优惠）

voucher

营销券

point

积分

mdiscount

商户优惠

bankPay

网银

外部用户ExtUserInfo参数说明

参数

类型

是否必填

最大长度

示例值

描述

name

String

否

16

李明

姓名


注： need_check_info=T时该参数才有效

mobile

String

否

20

16587658765

手机号


注：该参数暂不校验

cert_type

String

否

32

IDENTITY_CARD

身份证：IDENTITY_CARD、护照：PASSPORT、军官证：OFFICER_CARD、士兵证：SOLDIER_CARD、户口本：HOKOU等。如有其它类型需要支持，请与蚂蚁金服工作人员联系。


注： need_check_info=T时该参数才有效

cert_no

String

否

64

362334768769238881

证件号


注：need_check_info=T时该参数才有效

min_age

String

否

3

18

允许的最小买家年龄，买家年龄必须大于等于所传数值


注：

1. need_check_info=T时该参数才有效

2. min_age为整数，必须大于等于0

fix_buyer

String

否

8

F

是否强制校验付款人身份信息


T:强制校验，F：不强制

need_check_info

String

否

1

F

是否强制校验身份信息


T:强制校验，F：不强制

请求示例


请求参数组装分下列3步，以最后第三步获取到的请求为准
1.请求参数按照 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


2.再对原始字符串进行签名，参考签名规则：


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 处理，获得最终的请求字符串：


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


特殊说明（很重要）


1.商户在请求参数中，自己附属的一些额外参数，不要和支付宝系统中约定的 key（下表中 公共请求参数\请求参数）重名，否则将可能导致未知的异常。
比如以下示例中 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":"测试一笔支付"
  }


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


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

onlineServer