授权操作

第一步：创建并配置应用

创建、配置并上线第三方应用，可查看创建&配置第三方应用。

注意：

第三方应用必须上线后，才可让商家应用授权。

服务商要在授权前，在第三方应用的产品绑定列表中添加所有需要商家授权的功能（包括第三方应用授权、代开发核心 API 包）。

第二步：生成授权链接/二维码

服务商有两种方式可以生成授权链接/二维码。

控制台生成授权链接/二维码。

手动拼接授权链接。

说明：若需要携带自定义参数，则需要手动拼接授权链接。

控制台生成授权链接/二维码

服务商登录开放平台控制台，打开第三方应用详情页，选择 商家授权，点击 邀请授权商家 或 批量邀请。

若点击邀请授权商家，输入商家的支付宝账号，点击 发起授权，商家账号在支付宝 App 会受到一条消息，同时服务商也可将页面二维码和授权链接直接发给商户。

说明：邀请授权商家，服务商可指定商家进行授权邀请。

授权发起后，进入发送邀请结果通知页面。

商家登录支付宝 App 查看，收到服务商申请消息。

若点击 **批量邀请，**则弹出授权二维码和授权链接，服务商将二维码或链接发给商家，扫二维码或打开链接的商家都可选择应用进行授权。

将授权二维码或授权链接发给商家，邀请商家扫描授权二维码或打开授权链接，勾选应用进行授权。

手动拼接授权链接

手动拼接授权链接，根据商家的应用数量区分单个应用授权和指定应用授权。

单个应用授权：商家仅有一个应用需要授权。单个授权模式无法实现小程序相关接口调用，默认优先授权基础应用，若商家内没有基础应用，则系统自动生成基础应用。当商家拥有多个应用时，建议使用指定授权的方式拼接授权链接。

指定应用授权：商家有多个应用，从多个应用中选择一个。支持全权委托授权代开发模式。

指定应用授权（推荐）

注意：指定应用授权中，商家账号下必须拥有和 application_type 指定类型对应的应用，如 application_type=MOBILEAPP (移动应用)，商家必须有移动应用，否则授权页面中没有可选择的应用。platformCode 和 taskType 是固定参数，无需修改。

PC 端授权链接

https://b.alipay.com/page/message/tasksDetail?bizData=UrlEncode({"platformCode":"O","taskType":"INTERFACE_AUTH","agentOpParam":{"redirectUri":"{redirectUri}","appTypes":{appTypes},"isvAppId":"{isvAppId}","state":"{state}"}})

移动端二维码

alipays://platformapi/startapp?appId=2021003130652097&page=pages%2Fauthorize%2Findex%3FbizData%3DUrlEncode({"platformCode":"O","taskType":"INTERFACE_AUTH","agentOpParam":{"redirectUri":"{redirectUri}","appTypes":{appTypes},"isvAppId":"{isvAppId}","state":"{state}"}})

参数说明

只对 agentOpParam 参数作修改说明，链接中 startapp 指定的 appid 不可替换。

参数	类型	最大长度	必填参数	描述	示例
isvAppId	String	32	是	第三方应用 APPID。	2021000000000318
appTypes	String	/	是	对商家应用的限制类型，数组格式，支持多选，中间使用英文逗号（,）分隔，目前支持类型：MOBILEAPP（移动应用）WEBAPP（网页应用）PUBLICAPP（生活号）TINYAPP（小程序）BASEAPP（基础应用）	["TINYAPP","WEBAPP"]
redirectUri	String	/	是	回调页面地址，必须与第三方应用配置的授权回调地址一致。	https://example.com
state	String	100	否	自定义参数，便于服务商识别是哪个商家的授权信息。对应的值必须为 base64 编码。	MDAyMDIy

示例代码

单个应用授权

注意：该方式不适用于小程序应用的第三方授权，默认优先授权基础应用，若商家没有基础应用，则系统自动生成基础应用。若商家有多个应用，建议选择指定应用授权方式拼接授权链接。

拼接规则

https://openauth.alipay.com/oauth2/appToAppAuth.htm?app_id=第三方应用APPID&redirect_uri=UrlEncode(redirect_uri)&state=自定义参数值

参数说明

参数	类型	最大长度	描述	示例
app_id	String	32	第三方应用的 APPID，必填参数。	2021000000000318
redirect_uri	String	/	商家授权后的回调页面，必填参数，参数需要 UrlEncode。	http%3A%2F%2Fexample.com
state	String	100	自定义参数，可选参数，便于服务商识别是哪个商家的授权信息。对应的值必须为 base64 编码。	MDAyMDIy

第三步：商家授权

商家打开链接或者使用支付宝客户端扫描授权二维码，跳转至授权页面，选择需要授权的应用，确认授权。

说明：打开单个应用授权的授权链接没有选择应用的步骤，直接确认授权即可。

第四步：获取 app_auth_code

商家授权成功后，商家的页面跳转至服务商定义的回调地址（即 redirect_uri 参数对应的 URL），在回调页面请求中会带上当次授权的授权码 app_auth_code 和第三方应用的 APPID，示例如下。

http://example.com/doc/toAuthPage.html?app_id=2021000000000318&source=alipay_app_auth&application_type=TINYAPP,WEBAPP&app_auth_code=P1798b23682e34d96859afa000000003

说明：应用授权回调请求包含 app_auth_code=xxx，source=alipay_app_auth 字段，可以区别于 C 端用户授权。

第五步：使用 app_auth_code 换取 app_auth_token

服务商通过回调请求，获取到 app_auth_code 参数，然后调用 alipay.open.auth.token.app（换取应用授权令牌）接口，换取 app_auth_token。

说明：

应用授权的 app_auth_code 是唯一的。app_auth_code 使用一次后失效，单个授权的有效期为一天（从生成 app_auth_code 开始的 24 小时），未被使用自动过期。批量授权的有效期为 10 分钟。

app_auth_token 在没有重新授权、取消授权或刷新授权的情况下，永久有效。

商家应用重新授权后，app_auth_token 会刷新（刷新后原 token 仍存在 5~10min 的缓存期），建议服务商通过系统链路将 app_auth_token 入库，可保障及时更新，发起代调用请求时从数据库读取该字段，以避免手动更新时影响存量线上业务。

请求参数说明

参数	类型	描述	示例
grant_type	String	换码类型，必填参数，以下值二选一。authorization_code：使用 app_auth_code 换取 app_auth_token。refresh_token：刷新 app_auth_token。	authorization_code
code	String	授权码，当 grant_type 传入 authorization_code 时，必须传入本参数。传入授权获取的 app_auth_code 值。	P1798b23682e34d96859afa000000003
refresh_token	String	刷新令牌，上次换取访问令牌时得到。本参数在 grant_type 为 authorization_code 时不填；为 refresh_token 时必填，且该值来源于此接口的返回值 app_refresh_token（即至少需要通过 grant_type=authorization_code 调用此接口一次才能获取）。	201509BBdcba1e3347de4e75ba3fed2c9abebE36

请求示例

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayOpenAuthTokenApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayOpenAuthTokenApiApp {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayOpenAuthTokenApi api = new AlipayOpenAuthTokenApi();
        AlipayOpenAuthTokenAppModel data = new AlipayOpenAuthTokenAppModel();
        data.setCode("1cc19911172e4f8aaa509c8fb5d12F56");
        data.setGrantType("authorization_code或者refresh_token");
        data.setRefreshToken("201509BBdcba1e3347de4e75ba3fed2c9abebE36");
        try {
            AlipayOpenAuthTokenAppResponseModel response = api.app(data);
        } catch (ApiException e) {
            AlipayOpenAuthTokenAppDefaultResponse errorObject = (AlipayOpenAuthTokenAppDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应参数说明

参数	描述	示例
user_id	商家的 UID。	2088102150527498
auth_app_id	商家应用的 APPID。	2021002120000002
app_auth_token	应用授权令牌。	202201BB6891c77a23d9450c930e3edc0000003
app_refresh_token	刷新的新令牌。	202201BB27bcdfc7db37443ea4cf1203b0000029
expires_in	令牌有效时间，该字段已作废，app_auth_token 在没有重新授权、取消授权或刷新授权的情况下，永久有效。	31536000
re_expires_in	刷新令牌的有效时间（从接口调用时间作为起始时间），单位为秒。	32140800

响应示例

{
    "alipay_open_auth_token_app_response": {
        "code": "10000",
        "msg": "Success",
        "user_id": "2088102150000008",
        "auth_app_id": "2021002120000002",
        "app_auth_token": "202201BB6891c77a23d9450c930e3edc0000003",
        "app_refresh_token": "202201BB6891c77a23d9450c930e3edc0000003",
        "expires_in": 31536000,
        "re_expires_in": 32140800
    },
    "sign": "***"
}

若商家授权指定应用，则返回该应用的授权结果信息，如下所示。

{
  "alipay_open_auth_token_app_response":
  {
    "code":"10000",
    "msg":"Success",
    "tokens":
    [
        {
                "app_auth_token":"201712BB_D0804adb2e743078d1822d536956X34",
                "app_refresh_token":"201712BB_d5b15d53f7b4fd5aa649f176ca97X34",
                "auth_app_id": "2017120501354689",
                "expires_in": 31536000,
                "re_expires_in": 32140800,
                "user_id": "2088*******"
        }
      ]
  }, 
    "sign":"***"
}

第六步：代商家应用调用接口

服务商获取 app_auth_token 后，需调用支付宝开放接口时传入 app_auth_token 值，即代表本次调用请求是第三方应用代商家的应用发起的，可查看代商家调用接口说明。

说明：若第三方应用中有接入需签约的产品，则需要商家完成相关签约，才可正常运行业务，签约可分为商家自己签约或服务商代商家发起签约申请，可查看商家签约。

刷新授权

若存在自身业务员安全需求，可刷新 app_auth_token，获取新的授权令牌。

注意：请谨慎操作，刷新授权令牌会导致之前的令牌失效，需在 re_expires_in 显示时间内，完成替换业务中旧的 app_auth_token，否则旧的 app_auth_token 失效后，会影响线上业务。

通过 alipay.open.auth.token.app（换取应用授权令牌接口）刷新授权令牌 app_auth_token。

参数说明

参数	类型	描述	示例
grant_type	String	换码类型，必填参数，以下值二选一。authorization_code：使用 app_auth_code 换取 app_auth_token。refresh_token：刷新 app_auth_token。	app_auth_token
refresh_token	String	刷新令牌，当 grant_type 传入 refresh_token 时，必须传入本参数。传入上次换取授权时返回的 app_refresh_token 值。	202201BB6891c77a23d9450c930e3edc00000013

请求示例

grant_type=refresh_token 时请求示例。

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayOpenAuthTokenApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayOpenAuthTokenApiApp {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayOpenAuthTokenApi api = new AlipayOpenAuthTokenApi();
        AlipayOpenAuthTokenAppModel data = new AlipayOpenAuthTokenAppModel();
        data.setCode("1cc19911172e4f8aaa509c8fb5d12F56");
        data.setGrantType("authorization_code或者refresh_token");
        data.setRefreshToken("201509BBdcba1e3347de4e75ba3fed2c9abebE36");
        try {
            AlipayOpenAuthTokenAppResponseModel response = api.app(data);
        } catch (ApiException e) {
            AlipayOpenAuthTokenAppDefaultResponse errorObject = (AlipayOpenAuthTokenAppDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
  "alipay_open_auth_token_app_response": {
    "code": "10000",
    "msg": "Success",
    "app_auth_token": "202201BB2ea9f4a51fb6413d99e2a13c00000029",
    "app_refresh_token": "202201BB2f852040998c415d946f367000000X29",
    "auth_app_id": "2021002122000000",
    "expires_in": 31536000,
    "re_expires_in": 32140800,
    "user_id": "2088531800000001"
  },
  "sign": "******"
}

参数说明可查看上文 第五步 的响应参数说明。

查询授权商家信息

调用接口查询

服务商调用 alipay.open.auth.token.app.query（查询某个应用授权 AppAuthToken 的授权信息）接口，传入 app_auth_token，可查询到该 app_auth_token 对应的商家及商家应用信息。

应用详情页查询

授权第三方应用后，服务商可在第三方应用详情页，选择 商家授权 > 授权 token 中，获得该模板授权的 app_auth_token。

解除授权

说明：商家可取消授权，服务商无法取消授权。

商家进入应用授权和代扣页面，选择 第三方应用授权。点击第三方应用右上角 取消授权。

服务商可在第三方应用详情页的 开发设置 > 消息服务 > From 平台 页签订阅 alipay.open.auth.appauth.cancelled（第三方应用授权取消消息）通知，便于服务商第一时间知道商家应用取消授权的动态，详情可查看 From 蚂蚁消息。

接入指南

授权操作#

第一步：创建并配置应用#

第二步：生成授权链接/二维码#

控制台生成授权链接/二维码#

手动拼接授权链接#

指定应用授权（推荐）#

单个应用授权#

第三步：商家授权#

第四步：获取 app_auth_code#

第五步：使用 app_auth_code 换取 app_auth_token#

请求参数说明#

请求示例#

响应参数说明#

响应示例#

第六步：代商家应用调用接口#

刷新授权#

参数说明#

请求示例#

响应示例#

查询授权商家信息#

调用接口查询#

应用详情页查询#

解除授权#

授权操作

第一步：创建并配置应用

第二步：生成授权链接/二维码

控制台生成授权链接/二维码

手动拼接授权链接

指定应用授权（推荐）

单个应用授权

第三步：商家授权

第四步：获取 app_auth_code

第五步：使用 app_auth_code 换取 app_auth_token

请求参数说明

请求示例

响应参数说明

响应示例

第六步：代商家应用调用接口

刷新授权

参数说明

请求示例

响应示例

查询授权商家信息

调用接口查询

应用详情页查询

解除授权