Authorization Consult

2021-01-28 02:31

Use this interface to initiate an authorization consult of the authorization verification URL for an authorization that occurs at Alipay, and route to PMP to authorize the user according to the information in the request.

Request parameters

customerBelongsToString(16)Required

The e-wallet that the customer uses. Possible values are:

TRUEMONEY
ALIPAY_HK
TNG
ALIPAY_CN
GCASH
DANA
KAKAOPAY

authClientIdString(64)Optional

The unique ID of the authorization object to which the user grants resource access permission. For a PMP, this is the unique ID for secondary merchants, or the referenceMerchantId. The value is provided by the merchant and needs to be registered in Alipay.

Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

authRedirectUrlUrlRequired

The first part of the URL that the user is redirected to. The value is provided by the auth client.

scopesList<Enum>Required

The authorization scope. Possible values for the Enum section are:

BASE_USER_INFO: indicates that the unique user ID can be obtained.
USER_INFO: indicates that the complete user information can be obtained, for example, user name, avatar.
AGREEMENT_PAY: indicates a withholding authorization. The auth client can use the token to withhold the user's assets.

For example, the value of this field can be ["BASE_USER_INFO", "AGREEMENT_PAY"].

authStateString(256)Required

A string generated by the merchant, which represents the request. This field will be used in later process for validation.

terminalTypeEnumRequired

Terminal type of which the merchant service applies to. Possible values are:

WEB: The terminal type of the merchant side is a website.
WAP: The terminal type of the merchant side is an H5 page on the mobile phone.
APP: The terminal type of the merchant side is an app on the mobile phone.

osTypeEnumOptional

The OS type. Possible values are:

IOS
ANDROID

Note: This field is required when terminalType is APP or WAP.

osVersionString(16)Optional

The OS version.

Note: This field is required when the value of terminalType is APP or WAP.

Response parameters

resultResultRequired

The request result, which contains information related to the request result, such as status and error codes.

resultCodeString(16)Required

Result code

resultStatusEnumRequired

Result status. Possible values are:

S: indicates that the result status is successful.
F: indicates that the result status is failed.
U: indicates that the result status is unknown.

resultMessageString(64)Optional

Result message

authUrlUrlOptional

The authorization URL that the auth client is redirected to, through which the user completes the authorization verification. This field is returned only when result.resultStatus is S.

More information

This section gives additional information about certain parameters. See the following list for details:

authRedirectUrl:
The authorization Redirect URL provided by the merchant. After a successful authorization, the PMP or e-Wallet redirects the user back to the merchant website by using the merchant provided redirect URL specificed in authRedirectUrl in the request, the authRedirectUrl is concatenated with authCode and authState. For example:
https://www.merchant.com/authorizationResult?authCode=3AB2F588D14B43238637264FCA5AAF35&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7
authCode:
The authorization code used by the merchant to obtain accessToken.
authState:
Merchant is recommended to validate the consistency of authState in authRedirectUrl and that in the authorization consult request.
authUrl:
Returned when the authorization consult is successful. Users are redirected to this URL to complete the authorization. authUrl can be different for each wallet or terminal type according to the value of terminalType, osType, and osVersion.

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the authorization consult is successful. User can then complete the authorization in the returned authUrl.
If the value of result.resultStatus is U, the result is unknown. Retry the process.
If the value of result.resultStatus is F, the consult fails. Generally this is caused by system defects/failure. Check the error manually.

Result/Error codes

Code	Value	Message
SUCCESS	S	Success
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
PROCESS_FAIL	F	A general business failure occurred. Do not retry.
KEY_NOT_FOUND	F	The key is not found.
ACCESS_DENIED	F	Access denied
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.
API_INVALID	F	API is invalid or not active.
CLIENT_INVALID	F	The client is invalid.
SIGNATURE_INVALID	F	The signature is invalid.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.
MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.
UNKNOWN_EXCEPTION	U	An API calling is failed, which is caused by unknown reasons.