Introduction

• A merchant can authorize a third-party application / service provider. After that, the third-party vendor could help the merchant to complete the corresponding business logic on behalf of the merchant, such as payment request.
• The authorization adopts the standard OAuth 2.0 process. Only the authorized application can use it.
• The authorization for third-party application works only for OpenAPI 2.0 interface. It works for all third-party applications.

Note:
For the third-party to make a call, the third-party needs to have the corresponding permissions. Take Offline payment as exmaple, both the third-party and the merchant need to have permissions on Offline Payment solution such that the third-party vendor could issue payment request on behalf of the merchant.

Authorization flow

1) The developer applies for third party application.
2) Once approved, apply for the permission of the APIs under the current solution/application.
3) Construct the URL of the Authorization page, and direct the merchant to authorize.
4) Once the authorization is approved, acquire the app_auth_code from the page specified return page.
5) Change the app_auth_code to app_auth_token by calling API call.
6) Calling API call on behalf of the merchant with app_auth_token.

The following are detailed steps：

Step 1

URL construction and authorization redirect
URL construction rule：https://openauth.alipay.com/oauth2/appToAppAuth.htm?app_id=APPID&redirect_uri=ENCODED_URL
Use case：The third party vendor constructs the URL and the authorization page, and directs the merchant to authorize.
URL parameters:

Figure 1-4 PC Authorization page UI:

Figure 1-5 H5 Authorization page UI:

Notes:
H5 Authorization page could only be used in the Alipay Wallet client. Otherwise it will report error as the following.

Step 2 Acquire app_auth_code

When the authorization succeeds, it will be redirected to the redirect page specified by the developer. Alipay will add parameters in the response, such as app_auth_code、app_id etc. Please be aware that Alipay only guarantee the validity of app_auth_code，app_id. The sample for the redirect_uri is as following:

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

Step 3 Acquire app_auth_token with app_auth_code

API：alipay.open.auth.token.app
Call the API to get the app_auth_token, with the app_auth_code and the merchant′s userId and AppID. The app_auth_code will differ each time. The app_auth_code could be used only once, and used within 1 day. app_auth_token could be used within 365 days and refreshed unlimitedly.

• API call example

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=RSA2
    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"}
 
// biz_content when acquiring the app_auth_token
{
    "grant_type": "authorization_code",
    "code": "bf67d8d5ed754af297f72cc482287X62"
}
 
// when refreshing app_auth_token, biz_content is as following：
{
    "grant_type": "refresh_token",
    "refresh_token": "201510BB0c409dd5758b4d939d4008a525463X62"
}

Table 1-5 Request parameters:

• Response of synchronous return example

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

• Table 1-6 Synchronous response parameters

Step 4 Send request on behalf of the merchant

After acquired app_auth_token, the developer could send the request on behalf of the merchant. The other parameters would be the same as the values in merchant’s request. There is only one extra parameter “app_auth_token” in the POST payload.

Notes:

• The app_auth_token is require for thrid party API call. Otherwise Alipay will decide that it is the application’s request for itself. app_auth_token is a paramter in the POST, not the parameter in biz_content.
• When send reuest for the merchant, the app_id in the common parameter should be the app_id of the developer. The app_id in biz_content should be the merchant’s app_id, if there is one.

For example：

The merchant sends the request:
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

The developer sends the request for the merchant:
REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
    app_id=2015054598940398                 // developer’s 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=                                       // signed with the developer’s private key
    version=1.0
    app_auth_token=publicpB9ea460ff5b5c468c9ccf5e967dc34963  // the merchant’s auth token

FAQ