consult

2021-12-23 04:35

POST /v1/authorizations/consult

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

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

customerBelongsTo String REQUIRED

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

TRUEMONEY: TrueMoney wallet
ALIPAY_HK: Alipay HK wallet
TNG: Touch 'n Go wallet
ALIPAY_CN: Alipay CN wallet
GCASH: Gcash wallet
DANA: Dana wallet
KAKAOPAY: KakaoPay wallet
BKASH: bKash wallet
RABBIT_LINE_PAY: Rabbit LINE Pay wallet

More information:

Maximum length: 16 characters

authClientId String

The unique ID of the authorization object to which the user grants resource access permission. For a Alipay+ MPP, 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: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

More information:

Maximum length: 64 characters

authRedirectUrl URL REQUIRED

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

scopes Array<String> REQUIRED

The authorization scope. Valid values 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"].

More information:

Maximum size: 4 elements

authState String REQUIRED

A string generated by the merchant, which represents the request.

More information:

Maximum length: 256 characters

terminalType String REQUIRED

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

WEB: The client-side terminal type is a website that is opened via a PC browser.
WAP: The client-side terminal type is an HTML page that is opened via a mobile browser.
APP: The client-side terminal type is a mobile application.
MINI_APP: The terminal type of the merchant side is a mini program on the mobile phone.

osType String

The OS type. Valid values are:

IOS: indicates the operation system is Apple's iOS.
ANDROID indicates the operation system is Google's Android.

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

osVersion String

The OS version.

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

More information:

Maximum length: 16 characters

Response parameters

result Result REQUIRED

The request result contains information such as status and error codes.

Show child parameters

authUrl URL

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

schemeUrl Url

The URL scheme that redirects users to open an app in an Android or iOS system when the target app is installed.

Note: When the value of result.resultCode is S, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

applinkUrl Url

The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. For Android, the URL is a Native App Link. For iOS, the URL is a Universal Link.

Note: When the value of result.resultCode is S, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

appIdentifier String

Android package name, which is used for Android app to open a cashier page.

Note: This field is returned when result.resultCode is S and osType is ANDROID.

More information:

Maximum length: 128 characters

normalUrl Url

The URL that redirects users to a WAP or WEB page in the default browser or the embedded WebView.

Note: When the value of result.resultCode is S, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Payment method

AlipayCN

Terminal type

APP

Integration role

Acquirer-merchant Direct-merchant

Request Body

Response

Response Body

More information

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

authRedirectUrl:
The authorization redirect URL provided by the merchant. After a successful authorization, the Alipay+ MPP or e-wallet redirects the user back to the merchant's website by using the merchant-provided redirect URL specificed in authRedirectUrl in the request. The authRedirectUrl is concatenated with the 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. The 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 or failure. Check the error manually.

Error codes

Error codes are usually classified into the following categories:

Common error codes: common for all online and in-store payment APIs.
API-specific error codes: listed in the following table.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	Obtain authUrl from the response.
CLIENT_INVALID	F	The client is invalid.	Check whether the clientId is correct.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	Check whether the HTTP method is correct.
MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.	Check whether the media type is correct.
PAYMENT_NOT_QUALIFIED	F	The merchant is not qualified to pay because the merchant is not registered, does not have a contract for auto debit payment, or is forbidden to make a payment.	Contact Alipay technical support.