Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

Authorization Consult

POST /v1/authorizations/consult

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

customerBelongsTo String  REQUIRED

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

  • TRUEMONEY 
  • ALIPAY_HK 
  • TNG 
  • ALIPAY_CN 
  • GCASH 
  • DANA 
  • KAKAOPAY
  • BKASH

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

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 List<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"].

authState String  REQUIRED

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

More information:

  • Maximum length: 256 characters

terminalType Enum  REQUIRED

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.

osType Enum  

The OS type. Possible values are:  

  • IOS 
  • 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, which contains information related to the request result, such as status and error codes.

Show child parameters

authUrl Url  

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.

API Explorer
Sample CodesRun in Sandbox

Request

URL

Payment method
ALIPAY ALIPAY
Terminal type
APP APP
Integration role
Request Body

Response

Response Body

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

CodeValueMessage
SUCCESSSSuccess
PARAM_ILLEGALFIllegal parameters exist. For example, a non-numeric input, or an invalid date.
PROCESS_FAILFA general business failure occurred. Do not retry.
KEY_NOT_FOUNDFThe key is not found.
ACCESS_DENIEDFAccess denied
REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
API_INVALIDFAPI is invalid or not active.
CLIENT_INVALIDFThe client is invalid.
SIGNATURE_INVALIDFThe signature is invalid.
METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.
MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
UNKNOWN_EXCEPTIONUAn API calling is failed, which is caused by unknown reasons.
MERCHANT_NOT_REGISTEREDFThe merchant is not registered. Please register the merchant by using the registration interface.