consult (Cashier Payment)
Use this API to retrieve available payment methods that are supported by Alipay. Alipay automates the selection and sorting of multiple payment methods according to the user region. Then, the merchant displays available payment methods and corresponding logos to the user on the cashier page. Therefore, the user can choose the preferred payment method to pay.
By using this API, no additional development costs are needed when a new payment method is added or an existing payment method is deleted. And the merchant can provide users with more extensive 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
The payment product that is being used. The payment product(s) can be used are stipulated in the contract. For Cashier Payment, the value is fixed as CASHIER_PAYMENT.
paymentAmount Amount object REQUIRED
The payment amount that the merchant requests to receive in the order currency.
userRegion String
Used for specifying the regional information of the user. After this field is specified, the available payment method will be sorted and the payment method that is related to the specified user region will be given priority on the cashier page. For example, the user might get Alipay CN and KakaoPay as supported payment methods. However, based on the user's IP, the merchant may know that the user is in South Korea. Even though both payment methods can support the transaction, KaKaoPay is placed first. The value of this field is a 2-letter country/region code, which follows ISO 3166 Country Codes standard.
Note: Specify this field if the merchant needs to give priority to the payment method that is related to the specified region on the cashier page.
More information about this field
- Maximum length: 2 characters
allowedPspRegions Array<String>
Used to specify the regional information of the user. After this field is specified, only the payment methods that are related to the specified region will be displayed on the cashier page. For example, this field is specified as KR, KakaoPay will be displayed on the cashier page. The value of this field is a two-letter country/region code, which follows ISO 3166 Country Codes standard.
Note: Specify this field if the merchant needs to display the payment methods that are only related to the specified region on the cashier page.
More information about this field
- Maximum length: 2 characters
- Maximum size: 256 elements
env Env object REQUIRED
Information about the environment where the order is placed, such as the device information.
paymentFactor PaymentFactor object REQUIRED
The scenario that the request is used for.
merchant Merchant object
Information about the secondary merchant.
Note: Specify this field if you are an acquirer that has secondary merchants.
Response parameters
result Result object REQUIRED
Indicates whether this API is called successfully. If this API is successfully called, the payment methods can be obtained.
paymentOptions Array<PaymentOption> object REQUIRED
The list of available payment methods.
More information about this field
- Maximum size: 1 element
Request
Response
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | The API was called successfully. Obtain the payment method list and present it to the consumer. |
| MERCHANT_NOT_REGISTERED | F | The merchant is not registered. | Please register the merchant by using the registration API. Contact Alipay Technical Support if failed to call the registration API. |
| NO_PAY_OPTIONS | F | The currency is not supported for the transaction. | Check whether the currency is supported by the wallet, or check whether the wallet and currency are consistent with the contract. Contact Alipay 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. |
| PROCESS_FAIL | F | A 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. |
| 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 Alipay Technical Support. |