支付宝 App支付请求参数说明

2018-10-26 16:46 更新

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

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

公共参数

参数 类型 是否必填 最大长度 描述 示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.trade.app.pay
format String 40 仅支持JSON JSON
charset String 10 请求使用的编码格式,如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¬ify_url=http://domain.merchant.com/payment_notify&sign_type=RSA2×tamp=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¬ify_url=http://domain.merchant.com/payment_notify&sign_type=RSA2×tamp=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_amoun

特殊说明(很重要)

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×tamp=2016-07-01 08:08:08&method=alipay.trade.app.pay¬ify_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×tamp=2016-07-01 08:08:08&method=alipay.trade.app.pay¬ify_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请务必依赖服务端,不要轻信客户端上行的数据(客户端本地上行数据在用户手机环境中无法确保一定安全)。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号