Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

consult

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. See Payment methods to check the valid values.  

More information about this field

  • Maximum length: 64 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 about this field

  • 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 merchant.

More information about this field

  • 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 about this field

  • 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 about this field

  • 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. 

Specify this parameter when the value of terminalType is APP or WAP and you have this information. Providing this information makes the user's payment experience better.  

More information about this field

  • Maximum length: 16 characters

merchantRegion String  

The country or region where the merchant or secondary merchant operates the business. The parameter is a 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 the Global Acquirer Gateway (GAGW) product. 

More information about this field

  • Maximum length: 2 characters

Response parameters

result Result object REQUIRED

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

Show child parameters

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 about this field

  • 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 about this field

  • 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 about this field

  • 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 about this field

  • Maximum length: 2048 characters

authCodeForm AuthCodeForm object 

The information about the authorization QR code.

This parameter is returned when the payment method supports authorization through QR code scanning.  

Show child parameters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Payment method
AlipayCN AlipayCN
Terminal type
APP APP
Integration role
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 schemeUrl, applinkUrl, or normalUrl 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

CodeValueMessageFurther action
SUCCESSSSuccess

The interface is called successfully. Obtain schemeUrl, applinkUrl, or normalUrl from the response.

ACCESS_DENIEDFAccess is denied.

Contact Alipay Technical Support for detailed reasons. 

CLIENT_FORBIDDEN_ACCESS_APIFThe client is not authorized to use this API.

Contact Alipay Technical Support for detailed reasons.  

INVALID_ACCESS_TOKENFThe 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_APIFThe called API is invalid or not active.

Contact Alipay Technical Support to resolve the issue.  

INVALID_CLIENT_STATUSFThe client status is invalid.

Contact Alipay Technical Support for detailed reasons. 

INVALID_SIGNATUREFThe 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:

KEY_NOT_FOUNDFThe 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_REGISTEREDFThe 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_DEFFAPI is not defined.

Check whether the URL is correct. Please refer to the endpoint in the API documentation. 

NO_PAY_OPTIONSFThe payment method is not supported by this API.

Check whether the payment method is a valid value for the customerBelongsTo parameter. If the value you passed in is correct, contact Alipay Technical Support for detailed reasons. 

OAUTH_FAILEDFOAuth process failed.

Contact Alipay Technical Support for detailed reasons. 

PARAM_ILLEGALFThe 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_QUALIFIEDFThe 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_FAILFA 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_REJECTFThe request is rejected because of the risk control.

Prompt the user that the request is rejected because the risk control failed.  

SYSTEM_ERRORFA system error occurred.

Do not retry, and contact Alipay Technical Support for more details. 

UNKNOWN_CLIENTFThe client is unknown.

Contact Alipay Technical Support for detailed reasons. 

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support. 

UNKNOWN_EXCEPTIONUAn 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.