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

      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 StringRequired

      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 

      More information about this field:

      • Maximum length: 16 characters
      authClientId StringOptional

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

      • Maximum length: 64 characters
      authRedirectUrl URLRequired

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

      scopes StringRequired

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

      • Maximum size: 4 elements
      authState StringRequired

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

      More information about this field:

      • Maximum length: 256 characters
      terminalType StringRequired

      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 StringOptional

      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 StringOptional

      The OS version.  

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

      More information about this field:

      • Maximum length: 16 characters

      Response parameters

      result ResultRequired

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

      resultCode StringRequired

      Result code

      More information about this field:

      • Maximum length: 64 characters
      resultStatus StringRequired

      Result status. Valid values are:  

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

      Result message

      More information about this field:

      • Maximum length: 256 characters
      authUrl URLOptional

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

      CodeValueMessageFurther action
      SUCCESSSSuccess

      Obtain authUrl from the response.

      CLIENT_INVALIDFThe client is invalid.

      Check whether the clientId is correct.

      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

      Check whether the HTTP method is correct.

      MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

      Check whether the media type is correct.

      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.

      Request/Response Code

      Request

      Method

      POST

      Endpoint

      /v1/authorizations/consult

      Header

      Accept: application/json

      URL

      Domain name

      Request Body
      Request parameters
      ALIPAY
      ALIPAY_HK
      GCASH
      DANA
      KAKAO_PAY
      APP
      H5
      DESKTOP
      Acquirer-merchant
      Direct-merchant
      Response Body
      Body content