概述

• 商户对第三方应用授权成功之后，第三方应用可以帮助商户完成相应的业务逻辑，比如可以代替商户发起当面付的收单请求；
• 授权采用标准的OAuth 2.0流程，只有第三方应用才能够使用该授权方案；
• 第三方应用授权目前只对OpenAPI（2.0）接口有效，适用于所有的第三方应用。

注意：
要进行第三方调用，开发者需要开通相应的权限。例如对于当面付，开发者和商户都需要开通“当面付”，开发者才能帮助商户发起当面付的收单请求。

授权流程

1. 开发者申请第三方应用；
2. 应用申请成功之后，申请当前应用下的接口权限；
3. 按照规则拼接授权页面的链接，并且引导商户授权；
4. 授权成功后，在回调页面上获取app_auth_code；
5. 通过接口，将app_auth_code换取为app_auth_token；
6. 使用app_auth_token代替商户发起接口请求。

以下将从URL拼接及引导授权开始做详细介绍：

第一步：URL拼接与引导授权

url拼接规则：https://openauth.alipay.com/oauth2/appToAppAuth.htm?app_id=APPID&redirect_uri=ENCODED_URL

使用场景举例：开发者通过URL拼接方案，构造授权页面，并且引导商户授权。

url参数说明：

参数	参数名称	类型	必填	描述	范例
app_id	开发者应用的AppId	String	是	开发者第三方应用的AppId	2015101400446982
redirect_uri	回调页面	String	是	是 经过转义 的url链接（url必须以http或者https开头）	http%3A%2F%2Fexample.com

PC授权页面交互：

H5授权页面交互：

注：H5授权页只能在支付宝客户端里使用，否则会报错，如下。

第二步：获取app_auth_code

当商户授权成功后，会跳转至开发者定义的回调页面，支付宝会在回调页面请求中加入参数，包括用户授权码app_auth_code、开发者的app_id等，需要注意的是支付宝仅保证app_auth_code，app_id参数的有效性。支付宝请求开发者回调页面示例如下：

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

注意： 应用授权时，最终跳转的地址中除了code，可能会携带enctraceid参数（该参数未来会移除，请忽略，勿依赖该参数做任何业务判断）。

第三步：使用app_auth_code换取app_auth_token

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

换取授权访问令牌，开发者可通过获取到的app_auth_code换取app_auth_token和商户的userId以及AppId。app_auth_code作为换取app_auth_token的票据，每次商户授权带上的app_auth_code将不一样，app_auth_code只能使用一次，一天（从生成app_auth_code开始的24小时）未被使用自动过期。 app_auth_token有效期为365天，并且可以被无限次刷新。

接口请求示例

REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
    app_id=2014070100171525
    method=alipay.open.auth.token.app
    charset=GBK
    sign_type=RSA
    timestamp=2014-01-01 08:08:08
    sign=rXaTEfJ7WTDsP1DWRPHARW3uOr19+fzlngMCJBvbhP1XPEa9qZwGGng9oMDloABpJMT2SGeOj46+BUkqCGRO9fH90Vci3hOH01BfYnbhJz3ADK2h7gpjlponx4/sxELN6f2GXi51XKiHKnxMA9XpLLo68q+roY0M/ZFQ1UdnqeM=
    version=1.0
    biz_content={"grant_type":"authorization_code","code":"bf67d8d5ed754af297f72cc482287X62"}

// 当使用app_auth_code换取app_auth_token时，biz_content的内容如下：
{
    "grant_type": "authorization_code",
    "code": "bf67d8d5ed754af297f72cc482287X62"
}

// 当要刷新app_auth_token时，需要使用refresh_token，biz_content的内容如下：
{
    "grant_type": "refresh_token",
    "refresh_token": "201510BB0c409dd5758b4d939d4008a525463X62"
}

请求参数说明

参数	参数名称	类型	必填	描述	范例
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

同步响应结果示例

{
    "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="
}

同步响应参数说明

参数	参数名称	类型	必填	描述	范例
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一小段时间内继续可用，请及时替换为最新token	201510BB09dece3ea7654531b66bf9f97cdceE67

第四步：代替商户发起请求

获取app_auth_token后，开发者就可以帮助商户发起请求，其他参数与商户自身发起请求时保持完全一致，只是POST请求参数中增加了app_auth_token这个参数。

注意：

• 代替商户发起请求时请务必带上app_auth_token，否则支付宝将认为是本应用替自己发起的请求。app_auth_token是POST请求参数，不是biz_content的子参数。
• 代替商户发起请求时，POST公共请求参数中的app_id应填写开发者的app_id；如果业务参数biz_content中需要AppId，则应填写商户的AppId。

以服务窗修改菜单接口为例：

商户自身发起请求：

REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
    app_id=2014072300007148
    method=alipay.mobile.public.menu.add
    charset=GBK
    sign_type=RSA2
    timestamp=2014-07-24 03:07:50
    biz_content={"button":[{"actionParam":"ZFB_HFCZ","actionType":"out","name":"话费充值"},{"name":"查询","subButton":[{"actionParam":"ZFB_YECX","actionType":"out","name":"余额查询"},{"actionParam":"ZFB_LLCX","actionType":"out","name":"流量查询"},{"actionParam":"ZFB_HFCX","actionType":"out","name":"话费查询"}]},{"actionParam":"http://m.alipay.com","actionType":"link","name":"最新优惠"}]}
    sign=e9zEAe4TTQ4LPLQvETPoLGXTiURcxiAKfMVQ6Hrrsx2hmyIEGvSfAQzbLxHrhyZ48wOJXTsD4FPnt+YGdK57+fP1BCbf9rIVycfjhYCqlFhbTu9pFnZgT55W+xbAFb9y7vL0MyAxwXUXvZtQVqEwW7pURtKilbcBTEW7TAxzgro=
    version=1.0

开发者应用代替商户发起请求：

REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
    app_id=2015054598940398                 // 此处为开发者应用的AppId
    method=alipay.mobile.public.menu.add    // 接口名不变
    charset=GBK
    sign_type=RSA2
    timestamp=2014-07-24 03:07:50
    biz_content={"button":[{"actionParam":"ZFB_HFCZ","actionType":"out","name":"话费充值"},{"name":"查询","subButton":[{"actionParam":"ZFB_YECX","actionType":"out","name":"余额查询"},{"actionParam":"ZFB_LLCX","actionType":"out","name":"流量查询"},{"actionParam":"ZFB_HFCX","actionType":"out","name":"话费查询"}]},{"actionParam":"http://m.alipay.com","actionType":"link","name":"最新优惠"}]}      //业务参数不变
    sign=e9zEAe4TTQ4LPLQvETPoLGXTiURcxiAKfMVQ6Hrrsx2hmyIEGvSfAQzbLxHrhyZ48wOJXTsD4FPnt+YGdK57+fP1BCbf9rIVycfjhYCqlFhbTu9pFnZgT55W+xbAFb9y7vL0MyAxwXUXvZtQVqEwW7pURtKilbcBTEW7TAxzgro=                                       // 此处使用开发者的私钥进行加签
    version=1.0
    app_auth_token=publicpB9ea460ff5b5c468c9ccf5e967dc34963  // 此处必须带上商户授权令牌

FAQ

关于此文档暂时还没有FAQ