consult

2022-08-04 11:04

POST /v1/authorizations/consult

Use this API to get the user authorization. After this API is called successfully, you can get the authorization URL and redirect users to the authorization URL to agree to authorize. After the user agrees to authorize, the wallet redirects the user back to a redirection URL that is reconstructed with values of authRedirectUrl, authCode, and authState. For example, the redirection URL might be https://www.merchant.com/authorizationResult?authCode=3AB2F588D14B43238637264FCA5AAF35&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7.

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 wallet that the user uses. Valid values are:

TRUEMONEY: TrueMoney wallet
ALIPAY_HK: AlipayHK wallet
TNG: Touch 'n Go eWallet
ALIPAY_CN: AlipayCN wallet
GCASH: GCash wallet
DANA: DANA wallet
KAKAOPAY: KakaoPay wallet
BKASH: bKash wallet
RABBIT_LINE_PAY: Rabbit LINE Pay wallet
BOOST: Boost eWallet

More information:

Maximum length: 16 characters

authClientId String

The unique ID of the secondary merchant to which the user grants resource access permission. The value is specified by the acquirer and needs to be registered in Alipay.

Notes:

Specify this field if you are an acquirer with secondary merchants.
For an Alipay+ MPP, the value of this field is the same as the value of the referenceMerchantId field in the pay (Auto Debit) interface.

More information:

Maximum length: 64 characters

authRedirectUrl URL REQUIRED

The redirection URL that the user is redirected to after the user agrees to authorize. This value is provided by the secondary merchant.

More information:

Maximum length: 1024 characters

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, and other user information.
AGREEMENT_PAY: Indicates that the user agrees to authorize for auto debit so that the merchant can use the access token to automatically deduct money from the user's account.

More information:

Maximum size: 4 elements

authState String REQUIRED

The unique ID generated by the merchant to represent the consult request. The consistency of this field and that in the redirection URL when the user agrees to authorize needs to be guaranteed.

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 web 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 , WAP or MINI_APP.

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

merchantRegion String

The country or region where the merchant or secondary merchant operates the business. The 2-letter country/region code that follows ISO 3166 Country Codes standard. Only US, JP, PK, SG are supported now.

Note: This field is required when you use Alipay Global Gateway (GGW) product.

More information:

Maximum length: 2 characters

Response parameters

result Result REQUIRED

Indicates whether this API is called successfully. If this API is successfully called, the authorization URL can be obtained.

Show child parameters

authUrl URL

The authorization URL that the user is redirected to, to agree to authorize.

Notes:

This field is returned only when this API is called successfully (result.resultStatus is S).
The value of authUrl can be different for each wallet or terminal type according to the value of terminalType, osType, and osVersion.

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 terminalType is APP or WAP.

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

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 URL is successfully obtained by the authUrl field in the response. The merchant can redirect the user to this URL to agree to authorize for granting corresponding resource access permission.
If the value of result.resultStatus is U, the API calling status is unknown. You can call this API again to retry the process.
If the value of result.resultStatus is F, the authorization URL is failed to be obtained. Generally, this case is caused by system defects or system failure. Check the error codes and take the corresponding actions or contact Alipay technical support.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	The interface is called successfully. Obtain authUrl from the response.
ACCESS_DENIED	F	Access is denied.	Contact Alipay Technical Support for detailed reasons.
CLIENT_FORBIDDEN_ACCESS_API	F	The client is not authorized to use this API.	Contact Alipay Technical Support for detailed reasons.
INVALID_ACCESS_TOKEN	F	The access token is expired, revoked, or does not exist.	Check whether accessToken is correct. If not correct, pass in the correct value. If correct, contact Alipay Technical Support for detailed reasons.
INVALID_API	F	The called API is invalid or not active.	Contact Alipay Technical Support to resolve the issue.
INVALID_CLIENT_STATUS	F	The client status is invalid.	Contact Alipay Technical Support for detailed reasons.
INVALID_SIGNATURE	F	The signature is not validated. The private key used to sign a request does not match the public key of Alipay Developer Center.	Check whether the private key used to sign a request matches the public key of Alipay Developer Center. The following signature references are useful: The signature field in a request header How to calculate a signature
KEY_NOT_FOUND	F	The private key or public key of Alipay or the merchant is not found.	Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.	Please register the merchant by using the registration interface. Contact Alipay Technical Support if failed to call the registration interface.
NO_INTERFACE_DEF	F	API is not defined.	Check whether the URL is correct. Please refer to the endpoint in the API documentation.
OAUTH_FAILED	F	OAuth process failed.	Contact Alipay Technical Support for detailed reasons.
PARAM_ILLEGAL	F	The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.	Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.
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 for detailed reasons.
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue.
RISK_REJECT	F	The request is rejected because of the risk control.	Prompt the user that the request is rejected because the risk control failed.
SYSTEM_ERROR	F	A system error occurred.	Do not retry, and contact Alipay Technical Support for more details.
UNKNOWN_CLIENT	F	The client is unknown.	Contact Alipay Technical Support for detailed reasons.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.