consult

2024-10-25 08:31

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:

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

Notes:
Specify this field if you are an acquirer with secondary merchants.
For an Alipay+ payment methods, 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 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: 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:

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:

Maximum length: 2 characters

recurringPayment Boolean

Indicates whether the auto debit is used for recurring payments. Valid values are:

true: indicates the auto debit is for recurring payments.
false: indicates the auto debit is not for recurring payments.

Specify this parameter when the value of customerBelongsTo is PAYPAY.

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

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 SUCCESS, 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 SUCCESS, 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 SUCCESS 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 SUCCESS, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

authCodeForm AuthCodeForm

The information about the authorization QR code.

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

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 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 Antom technical support.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	The interface is called successfully. Obtain schemeUrl, applinkUrl, or normalUrl from the response.
ACCESS_DENIED	F	Access is denied.	Contact Antom Technical Support for detailed reasons.
CLIENT_FORBIDDEN_ACCESS_API	F	The client is not authorized to use this API.	Contact AntomTechnical 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 Antom Technical Support for detailed reasons.
INVALID_API	F	The called API is invalid or not active.	Contact Antom Technical Support to resolve the issue.
INVALID_CLIENT_STATUS	F	The client status is invalid.	Contact Antom 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 <span>Antom</span> Dashboard.	Check whether the private key used to sign a request matches the public key of Antom Dashboard. 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 <span>Antom</span> or the merchant is not found.	Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.	Please register the merchant by using the registration interface. Contact Antom 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.
NO_PAY_OPTIONS	F	The 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 Antom Technical Support for detailed reasons.
OAUTH_FAILED	F	OAuth process failed.	Contact Antom 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 Antom 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 Antom 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 Antom Technical Support for more details.
UNKNOWN_CLIENT	F	The client is unknown.	Contact Antom 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 Antom 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 Antom Technical Support.