Receive authorization notification

By integrating the authNotify API, the Acquiring Service Provider (ACQP) can receive authorization notifications from Alipay+ in the following three scenarios:

An authorization code is created at the Mobile Payment Provider (MPP) side.
An access token is created at the MPP side.
An access token is canceled at the MPP side due to one of the following reasons:

A user successfully unbinds the merchant platform account and the MPP platform account through the merchant platform with the cancelToken API.
A user successfully unbinds the merchant platform account and the MPP platform account through the MPP side.
The MPP has to unbind the user account directly from the back-end system.

The following sections introduce how to process the authNotify request in different scenarios.

Scenario 1: An authorization code is created

In this scenario, Alipay+ sends an authNotify request to the ACQP when an authorization code is created at the MPP side.

Processing logic

The following list provides the key information that the ACQP needs to take into consideration when handling the request parameters of the authNotify API:

authorizationNotifyType: as the notification is sent out to notify the ACQP of the auth code, the value is set as AUTHCODE_CREATED.
authCode: used by confidential and public clients to exchange for an access token. This parameter is only available when authorizationNotifyType is set as AUTHCODE_CREATED.
authState: specifies the authorization statement. The value is consistent with the one that is specified on the authState parameter of the prepare request. This parameter is only available when authorizationNotifyType is set as AUTHCODE_CREATED.
customerId: The unique ID that is assigned by the wallet to identify a user. The parameter is available when the authorization is successful.

After the ACQP successfully handles the notification request, the ACQP needs to return a response to Alipay+. Alipay+ provides a notification retry mechanism if the result.resultCode parameter in the notification response returned from the ACQP is not S. For the best practices about how to handle the notification, see Handle a notification.

Sample

Alipay+ sends an authNotify request to the ACQP.

copy
{
  "authorizationNotifyType":"AUTHCODE_CREATED",
  "authClientId": "218823863726*********",
  "referenceMerchantId": "218823863726*********",
  "authCode": "281010133AB2F588D14B43231234****",
  "authState": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
  "referenceAgreementId": "aNDJWQNNabdad****",
  "acquirerId": "102xxxxxxxxxxxx0001",
  "pspId":"102xxxxxxxxxxxx0001"
}

The ACQP returns a response to Alipay+.

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

For more information about how to use the authNotify API (such as the field description and format), see authNotify.

Scenario 2: An access token is created

In this scenario, Alipay+ sends an authNotify request to the ACQP when an access token is created at the MPP side.

Processing logic

The following list provides the key information that the ACQP needs to take into consideration when handling the request parameters of the authNotify API:

authorizationNotifyType: as the notification is sent out to notify the ACQP of the access token, the value is set as TOKEN_CREATED.
accessToken: specifies the access token from Alipay+, which is used by the auth client to initiate a payment against the user.
accessTokenExpiryTime: specifies the expiration time of the access token, after which the auth client cannot use this access token to deduct funds from the user's account.
refreshToken: used by the auth client to request a new access token when the current access token expires. With this parameter, a valid access token can be obtained continuously without any further interaction with the user.
refreshTokenExpiryTime: the expiration time of the refresh token, after which the auth client cannot use this token to retrieve a new access token.
walletForAccountBinding: the wallet that is selected by the user for account binding. Specified only if the access token is successfully created.

After the ACQP successfully handles the notification request, the ACQP needs to return a response to Alipay+. Alipay+ provides a notification retry mechanism if the result.resultCode parameter in the notification response returned from the Acquiring Service Provider is not S. For the best practices about how to handle the notification, see Handle a notification.

Sample

Alipay+ sends an authNotify request to the ACQP.

copy
{
    "authorizationNotifyType": "TOKEN_CREATED",
    "authClientId": "218823863726123456789",
    "referenceMerchantId": "218823863726123456780",
    "referenceAgreementId": "667d730b56123456789",
    "accessToken": "281010033AB2F588D14B4323863726123456789",
    "accessTokenExpiryTime": "2022-06-06T12:12:12+08:00",
    "refreshToken": "2810100334F62CBC577F468AAC123456789",
    "refreshTokenExpiryTime": "2022-06-08T12:12:12+08:00",
    "scopes": [
        "AGREEMENT_PAY",
        "USER_LOGIN_ID"
    ],
    "customerId": "278980891234567891234567891",
    "userLoginId": "62-34312736",
    "acquirerId": "1021234567891230001",
    "pspId": "1021234567891230002",
    "walletForAccountBinding": {
        "walletName": "AlipayCN",
        "walletBrandName": "AlipayCN",
        "walletLogo": {
            "logoName": "AlipayCN",
            "logoUrl": "https://www.alipayplus.com/logo/20022222xxx.png"
        }
    }
}

The ACQP returns a response to Alipay+.

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    }
}

For more information about how to use the authNotify API (such as the field description and format), see authNotify.

Scenario 3: An access token is canceled

In this scenario, Alipay+ sends an authNotify request to the ACQP when an access token is canceled at the MPP side.

Processing logic

The following list provides the key information that the ACQP needs to take into consideration when handling the request parameters of the authNotify API:

authorizationNotifyType: the value is set to TOKEN_CANCELED to indicate the access token in the request has been deactivated by the MPP. The merchant cannot use the access token for any further interactions.
accessToken: specifies the access token that needs to be revoked.
tokenCancelSource: specifies the source of the unbinding. The value is set to ACQUIRER if the account unbinding process is initiated from the merchant side. The value is set to PSP if the account unbinding process is initiated from the MPP side.

After the ACQP successfully handles the notification request, the ACQP needs to return a response to Alipay+. Alipay+ provides a notification retry mechanism if the result.resultCode parameter in the notification response returned from the ACQP is not S. For the best practices about how to handle the notification, see Handle a notification.

The ACQP also needs to sync the notification with the merchant.

Sample

Alipay+ sends an authNotify request to the ACQP if the account unbinding process is initiated from the merchant side.

copy
{
    "authorizationNotifyType": "TOKEN_CANCELED",
    "authClientId": "218xxxxxxxxx1234",
    "referenceMerchantId": "218823863726*********",
    "accessToken": "663xxxxxxxxxxxxxxxxxxxxxxxxx9DC7",
    "tokenCancelSource": "ACQUIRER",
    "acquirerId": "102xxxxxxxxxxxx0001",
    "pspId":"102xxxxxxxxxxxx0001"
}

Alipay+ sends an authNotify request to the ACQP if the account unbinding process is initiated from the merchant side.

copy
{
    "authorizationNotifyType": "TOKEN_CANCELED",
    "authClientId": "218xxxxxxxxx1234",
    "referenceMerchantId": "218823863726*********",
    "accessToken": "663xxxxxxxxxxxxxxxxxxxxxxxxx9DC7",
    "tokenCancelSource": "PSP",
    "acquirerId": "102xxxxxxxxxxxx0001",
    "pspId":"102xxxxxxxxxxxx0001"
}

The ACQP returns a response to Alipay+.

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

For more information about how to use the authNotify API (such as the field description and format), see authNotify.