蚂蚁金服支付宝开发文档——第三方应用授权

由 ✎﹏๓₯㎕ζั͡❦﹏﹏♛ 创建, 最后一次修改 2018-01-03

概述

  1. 商户对开发者进行应用授权后,开发者可以帮助商户完成相应的业务逻辑,例如代替商户发起当面付的收单请求。

  2. 授权采用标准的OAuth 2.0流程。

  3. 要进行第三方调用,开发者需要在应用中添加对应功能并获得商户授权,商户需要申请开通相应的权限(例如对于当面付,开发者只需在应用中添加“当面付”功能并获得商户授权,商户则需要开通“当面付”产品,之后开发者就可以帮助商户发起当面付的收单请求)。

TIPS:针对使用条件是“无”的功能(使用条件可在应用详情页的功能信息页查看),只需要开发者在应用中添加对应功能,并获得商户授权即可(例如“支付宝卡券”)

授权流程

蚂蚁金服支付宝开发文档

快速接入

第一步:创建应用

要在您的应用中使用支付宝开放产品的接口能力,您需要先去蚂蚁金服开放平台(open.alipay.com ),在开发者中心中创建登记您的应用,并提交审核,审核通过后会为您生成应用唯一标识(APPID),并且可以申请开通开放产品使用权限,通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南 》。

第二步:配置密钥

开发者调用接口前需要先生成RSA密钥,RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY)。生成密钥后在开放平台开发者中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境 》。

第三步:应用授权URL拼装

拼接规则:

https://openauth.alipay.com/oauth2/appToAppAuth.htm?app_id=2015101400446982&redirect_uri=http%3A%2F%2Fexample.com

TIPS:沙箱拼接规则详见关于沙箱

参数说明

参数 参数名称 类型 必填 描述 范例
app_id 开发者应用的AppId String 开发者应用的AppId 2015101400446982
redirect_uri 回调页面 String 参数需要UrlEncode http%3A%2F%2Fexample.com

TIPS:授权链接中配置的redirect_uri内容需要与应用中配置的授权回调地址完全一样,否则无法正常授权。

使用场景举例

商户使用开发者提供的应用授权链接在PC端进行应用授权

蚂蚁金服支付宝开发文档

商户使用开发者提供的应用授权链接在手机端进行应用授权

蚂蚁金服支付宝开发文档

:H5授权页只能在支付宝钱包里使用,否则会报错,如下:

蚂蚁金服支付宝开发文档

第四步:获取app_auth_code

商户授权成功后,pc或者钱包客户端会跳转至开发者定义的回调页面(即redirect_uri参数对应的url),在回调页面请求中会带上当次授权的授权码app_auth_code和开发者的app_id,示例如下:

http://example.com/doc/toAuthPage.html?app_id=2015101400446982&app_auth_code=ca34ea491e7146cc87d25fca24c4cD11

第五步:使用app_auth_code换取app_auth_token

接口名称:alipay.open.auth.token.app

开发者通过app_auth_code可以换取app_auth_token、授权商户的userId以及授权商户AppId。

注意:应用授权的app_auth_code唯一的;app_auth_code使用一次后失效,一天(从生成app_auth_code开始的24小时)未被使用自动过期; app_auth_token有效期为365天,刷新后重新计时。

请求参数说明

参数 参数名称 类型 必填 描述 范例
grant_type 授权类型 String 如果使用app_auth_code换取token,则为authorization_code,如果使用refresh_token换取新的token,则为refresh_token authorization_code
code 授权码 String 与refresh_token二选一,用户对应用授权后得到,即第一步中开发者获取到的app_auth_code值 bf67d8d5ed754af297f72cc482287X62
refresh_token 刷新令牌 String 与code二选一,可为空,刷新令牌时使用 201510BB0c409dd5758b4d939d4008a525463X62

接口请求示例: 请先阅读SDK接入说明

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayOpenAuthTokenAppRequest request = new AlipayOpenAuthTokenAppRequest();
request.setBizContent("{" +
"    \"grant_type\":\"authorization_code\"," +
"    \"code\":\"1cc19911172e4f8aaa509c8fb5d12F56\"" +
"  }");
AlipayOpenAuthTokenAppResponse response = alipayClient.execute(request);

同步响应参数说明

参数 参数名称 类型 必填 描述 范例
app_auth_token 商户授权令牌 String 通过该令牌来帮助商户发起请求,完成业务 201510BBaabdb44d8fd04607abf8d5931ec75D84
user_id 授权商户的ID String 授权者的PID 2088011177545623
auth_app_id 授权商户的AppId String 授权商户的AppId(如果有服务窗,则为服务窗的AppId) 2013111800001989
expires_in 令牌有效期 Number 交换令牌的有效期,单位秒,换算成天的话为365天 31536000
re_expires_in 刷新令牌有效期 Number 刷新令牌有效期,单位秒,换算成天的话为372天 32140800
app_refresh_token 刷新令牌时使用 String 刷新令牌后,我们会保证老的app_auth_token从刷新开始10分钟内可继续使用,请及时替换为最新token 201510BB09dece3ea7654531b66bf9f97cdceE67

同步响应结果示例

{
    "alipay_open_auth_token_app_response": {
        "code": "10000",
        "msg": "Success",
        "app_auth_token": "201510BBb507dc9f5efe41a0b98ae22f01519X62",
        "app_refresh_token": "201510BB0c409dd5758b4d939d4008a525463X62",
        "auth_app_id": "2013111800001989",
        "expires_in": 31536000,
        "re_expires_in": 32140800,
        "user_id": "2088011177545623"
    },
    "sign": "TR5xJkWX65vRjwnNNic5n228DFuXGFOCW4isWxx5iLN8EuHoU2OTOeh1SOzRredhnJ6G9eOXFMxHWl7066KQqtyxVq2PvW9jm94QOuvx3TZu7yFcEhiGvAuDSZXcZ0sw4TyQU9+/cvo0JKt4m1M91/Quq+QLOf+NSwJWaiJFZ9k="
}

注意:

  1. 在授权过程中,建议在拼接授权url的时候,开发者可增加自己的一个自定义信息,便于知道是哪个商户授权。
  2. 开发者代替商户发起请求时请务必带上app_auth_token,否则支付宝将认为是本应用替自己发起的请求。请注意app_auth_tokenPOST请求参数,不是biz_content的子参数;在SDK中带上app_auth_token代码示例
    request.putOtherTextParam("app_auth_token", "201611BB888ae9acd6e44fec9940d09201abfE16");
  3. 开发者代替商户发起请求时,POST公共请求参数中的app_id应填写开发者的app_id;如果业务参数biz_content中需要AppId,则应填写商户的AppId。

查询授权信息

接口名称:alipay.open.auth.token.app.query

当商户把服务窗、店铺等接口的权限授权给ISV之后,支付宝会给ISV颁发一个app_auth_token。如若授权成功之后,ISV想知道用户的授权信息,如授权者、授权接口列表等信息,可以调用本接口查询某个app_auth_token对应的授权信息。

请求参数说明

参数 参数名称 类型 必填 描述 范例
app_auth_token 商户授权令牌 String 通过该令牌来帮助商户发起请求,完成业务 201510BBaabdb44d8fd04607abf8d5931ec75D84

接口请求示例: 请先阅读SDK接入说明

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayOpenAuthTokenAppQueryRequest request = new AlipayOpenAuthTokenAppQueryRequest();
request.setBizContent("{" +
"    \"app_auth_token\":\"201509BBeff9351ad1874306903e96b91d248A36\"" +
"  }");
AlipayOpenAuthTokenAppQueryResponse response = alipayClient.execute(request);

同步响应参数说明

参数 参数名称 类型 必填 描述 范例
user_id 授权商户的ID String 授权者的PID 2088011177545623
auth_app_id 授权商户的AppId String 授权商户的AppId(如果有服务窗,则为服务窗的AppId) 2013111800001989
expires_in 令牌有效期 Number 交换令牌的有效期,单位秒,换算成天的话为365天 31536000
auth_methods 授权接口列表 String 当前app_auth_token的授权接口列表 "alipay.open.auth.token.app.query","alipay.system.oauth.token","alipay.open.auth.token.app"
auth_start 授权生效时间 Date 当前app_auth_token的授权生效时间 2015-11-03 01:59:57
auth_end 授权失效时间 Date 当前app_auth_token的授权失效时间 2016-11-03 01:59:57
status 状态 String valid:有效状态;invalid:无效状态 valid

同步响应结果示例

{
"alipay_open_auth_token_app_query_response":{
"auth_app_id":"2013121100055554",
"auth_end":"2016-11-03 01:59:57",
"auth_methods":[
"\"alipay.open.auth.token.app.query\"",
"\"alipay.system.oauth.token\"",
"\"alipay.open.auth.token.app\""
],
"auth_start":"2015-11-03 01:59:57",
"code":"10000",
"expires_in":31536000,
"msg":"Success",
"status":"valid",
"user_id":"2088102150527498"
}
}

SDK接入说明

1、下载服务端SDK 为了帮助开发者调用开放接口,我们提供了开放平台服务端SDK ,包含JAVA、PHP和.NET三个语言版本,封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。

各语言版本服务端SDK详细使用说明,请参考《服务端SDK说明 》。

2、接口调用配置

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

关键参数说明:

配置参数 示例值解释 获取方式/示例值
URL 支付宝网关(固定) https://openapi.alipay.com/gateway.do
APPID APPID 即创建应用后生成 获取见上面创建应用并获取APPID
APP_PRIVATE_KEY 开发者私钥,由开发者自己生成 获取详见上面配置密钥
FORMAT 参数返回格式,只支持json json(固定)
CHARSET 编码集,支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 获取详见上面配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2

3.接口调用

接口调用示例大致分为3步:

  1. 拼装业务参数
  2. 将参数发送给开放平台服务端
  3. 获取开放平台服务端返回值,并进行具体业务处理

关于沙箱

如何接入沙箱

沙箱是开放平台提供给开发者用户调试接口的环境,具体操作步骤见沙箱接入指南

第三方应用授权沙箱接入注意点

1、第三方应用授权支持沙箱接入;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;

2、第三方应用授权的拼接规则为:https://openauth.alipaydev.com/oauth2/appToAppAuth.htm?app_id=APPID&redirect_uri=REDIRECT_URI

3、授权时使用商户账号进行授权,不要使用买家账号授权;

授权API列表

序号 接口英文名 接口中文名 API文档
1 alipay.open.auth.token.app 换取应用授权令牌接口 查看文档
2 alipay.open.auth.token.app.query 查询某个应用授权AppAuthToken的授权信息接口 查看文档

本接口及文档资料由开放平台提供。您使用本接口,需要遵守开放平台相关协议及开放平台要求。

W3Cschool学编程上微课-边学边练
二维码
建议反馈
二维码