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

consult (Checkout Payment)

POST /v1/payments/consult

Use the consult API to initiate a payment consultation request to Alipay. This request is returned to the merchant with information on the different payment methods and its corresponding amount, country, currency, rules, and configuration.

The consult API enables merchants to:

  • Provide consumers with multiple payment methods without bearing any additional costs caused by a change in these payment methods, or managing the logic of selecting and sorting these payment methods.
  • Automate the selection and sorting of multiple payment methods.

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

productCode String  REQUIRED

Represents the payment product that is being used. The payment product that can be used is stipulated in the contract. The fixed value is:

  • CASHIER_PAYMENT: Indicates that this API is used for the Cashier Payment scenario.

More information about this field

  • Maximum length: 32 characters

paymentAmount Amount object REQUIRED

The payment amount that the merchant requests to receive in the order currency.

Show child parameters

userRegion String  

The 2-letter country or region code. For more information, see ISO 3166 Country Codes standard. The payment methods will be sorted based on payment method relevance for the given user's region. 

More information about this field

  • Maximum length: 2 characters

merchantRegion String  

The country or region where the merchant operates the business. The parameter is a 2-letter country or region code that follows ISO 3166 Country Codes standard.

Some possible values are US, SG, HK, PK, JP, CN, BR, AU, and MY.  

This parameter is required when you use the Global Acquirer Gateway (GAGW) product. 

More information about this field

  • Maximum length: 2 characters

settlementStrategy SettlementStrategy object 

The settlement strategy.

Show child parameters

allowedPaymentMethodRegions Array<String>  

A list of region codes that represent the countries or regions of payment methods. The value of this parameter is a 2-letter ISO country code or GLOBAL

Specify this parameter if you want available payment methods from specific regions to be returned. For example, if you pass in GLOBAL, global cards Visa and Mastercard are returned.  

More information about this field

  • Maximum length: 6 characters

env Env object REQUIRED

Information about the environment where the order is placed, such as the device information.

Show child parameters

buyer Buyer object 

Buyer information.

Show child parameters

merchantAccountId String  

The unique ID to identify a merchant account.

Specify this parameter when you use a single client ID across multiple locations.

More information about this field

  • Maximum length: 32 characters

Response parameters

result Result object REQUIRED

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

Note: This field doesn't indicate the payment result. This field only indicates whether the consult interface is called successfully. 

Show child parameters

paymentOptions Array<PaymentOption> object 

The payment option list.

Show child parameters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Request Body

Response

Response Body

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The consultation is successful. No further action is needed.

CURRENCY_NOT_SUPPORTFThe currency is not supported.

Change the currency used in the request. If the issue persists, contact Alipay Technical Support for detailed reasons.  

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_PAY_OPTIONSFNo payment options are available.

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

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.  

SETTLE_CONTRACT_NOT_MATCHFNo matched settlement contract can be found.

Check the following for a solution: 

  1. Specify one settlement currency from the multiple currencies that the merchant signed up for. 
  2. Check if the settlement currency is specified in the settlement contracts. 
  3. The merchant didn't sign a settlement contract. 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.