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

pay (Checkout Payment)

POST /v1/payments/pay

Use this API to get the cashier page address. After getting the cashier page address, you can redirect the user to the cashier page to make a payment.

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, which is stipulated in the contract. For Checkout Payment, the value is fixed as CASHIER_PAYMENT.

paymentRequestId String  REQUIRED

The unique ID assigned by a merchant to identify a payment request. Alipay uses this field for idempotence control.

More information about this field

  • This field is an API idempotency field.For payment requests that are initiated with the same value of paymentRequestId and reach a final status of S or F, the same result is to be returned for the request.
  • Maximum length: 64 characters

order Order object REQUIRED

The order information, such as buyer, merchant, goods, amount, shipping information, and purchase environment. This field is used for different purposes:

  • During the payment process, this field is mainly used by Alipay for risk control or anti-money laundering.
  • After the payment is completed, this field is used for recording and reporting purposes such as purchase tracking and regulatory reporting.
Show child parameters

paymentAmount Amount object REQUIRED

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

Show child parameters

paymentFactor PaymentFactor object 

Factors that impact the payment. This field is used to indicate the payment scenario.  

Specify this parameter when the value of paymentMethodType is CARD. 

Show child parameters

paymentMethod PaymentMethod object REQUIRED

The payment method that is used to collect the payment by the merchant or acquirer.

Show child parameters

paymentExpiryTime Datetime  

The payment expiration time is a specific time after which the payment will expire and the acquirer or merchant must terminate the order processing. 

Notes:

  • For bank transfer payments, the default payment expiration time is 48 hours after the payment request is sent. For other payment methods, the default payment expiration time is usually 14 minutes after the payment request is sent. For example, if the request is sent on 2019-11-27T12:00:01+08:30, the payment expiration time is 2019-11-27T12:14:01+08:30.
  • Specify this field if you want to use a payment expiration time that differs from the default time. For bank transfer payments, the specified payment expiration time must be less than 48 hours after the payment request is sent. For other payment categories, the specified payment expiration time must be less than 10 minutes after the payment request is sent.  

More information about this field

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

paymentRedirectUrl URL  REQUIRED

The merchant page URL that the user is redirected to after the payment is completed.

More information about this field

  • Maximum length: 2048 characters

paymentNotifyUrl URL  

The URL that is used to receive the payment result notification.

Specify this parameter if you want to receive an asynchronous notification of the payment result. You can also set the URL to receive the result notification in Alipay+ Dashboard. If the URL is specified in both the request and Alipay+ Dashboard, the value specified in the request takes precedence.

More information about this field

  • Maximum length: 2048 characters

settlementStrategy SettlementStrategy object REQUIRED

The settlement strategy for the payment request.

Show child parameters

userRegion String  

A 2-letter country or region code based on the standard of ISO 3166 Country Codes. This parameter is used to sort Alipay+ payment methods according to the user's region. For example, if ALIPAY_CN and KAKAOPAYare both on your payment method list and the user is from South Korea, KAKAOPAY will be listed first on the Alipay+ cashier page.
Note: This parameter is only for the merchant that has integrated the Alipay+ cashier page.  

More information about this field

  • Maximum length: 2 characters

creditPayPlan CreditPayPlan object 

The credit payment plan information for this payment.

Note: Specify this field if you want to support installment payment and contact Alipay technical support for details on how to offer installment payments.

Show child parameters

appId String  

The unique ID that is assigned by Alipay to identify the mini program.

Note: This field is required when terminalType is MINI_APP.

More information about this field

  • Maximum length: 32 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

env Env object REQUIRED

Information about the environment where the order is placed, such as the device 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 result of the API call.

Show child parameters

paymentRequestId String  

The unique ID that is assigned by a merchant to identify a payment request.

Note: This field is returned when resultCode is PAYMENT_IN_PROCESS.

More information about this field

  • Maximum length: 64 characters

paymentId String  

The unique ID that is assigned by Alipay to identify a payment.

Note: This field is returned when resultCode is PAYMENT_IN_PROCESS.

More information about this field

  • Maximum length: 64 characters

paymentAmount Amount object 

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

Note: This field is returned when resultCode is PAYMENT_IN_PROCESS.

Show child parameters

paymentData String  

Used by the Alipay+ client SDK to render the checkout page. This parameter is returned if the merchant app has integrated Alipay+ client SDK. After receiving the parameter, you can call the showPaymentSheet API of the Alipay+ client SDK.

More information about this field

  • Maximum length: 20000 characters

paymentCreateTime Datetime  

The date and time when the payment is created.

Note: This field is returned when resultCode is PAYMENT_IN_PROCESS.

More information about this field

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

pspCustomerInfo PspCustomerInfo object 

The customer information of Alipay+ Mobile Payment Provider (Alipay+ MPP).

Note: This field is returned when the Alipay+ MPP can provide the related information.

Show child parameters

orderCodeForm OrderCodeForm object 

Information about the order code.

This parameter is returned when the payment method supports providing the related information.  

Show child parameters

grossSettlementAmount Amount object 

The value of this field equals to transaction amount multiplied by the value of settlementQuote. This field is returned when the currency exchange is predetermined and the exchange rate is locked at the time of transaction.

Show child parameters

settlementQuote Quote object 

The exchange rate between the settlement currency and transaction currency. This field is returned when grossSettlementAmount is returned.

Show child parameters

appIdentifier String  

Android package name, which is used by Android apps to open a cashier page.

Note: This field is returned when resultCode is PAYMENT_IN_PROCESS and terminalType is APP or WAP.

More information about this field

  • Maximum length: 128 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 resultCode is PAYMENT_IN_PROCESS, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information about this field

  • Maximum length: 2048 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 resultCode is PAYMENT_IN_PROCESS, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information about this field

  • Maximum length: 2048 characters

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

More information about this field

  • Maximum length: 2048 characters

paymentResultInfo PaymentResultInfo object 

The payment result information.

This parameter may be returned when the value of paymentMethodType is CARD.  

Show child parameters

promotionResult Array <PromotionResult> object 

Promotion result.

This parameter is generated when the buyer applies a promotion during the process of placing an order.

Show child parameters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Payment method
AlipayCN AlipayCN
Terminal type
APP APP
Integration role
Request Body

Response

Case
Successful/In-process transaction exists
Case description
If a transaction with paymentStatus of PROCESSING or SUCCESS exists, and you initiate a request with the same paymentRequestId as that of the existing transaction, the response will be the same as the response of the existing transaction. The following response is returned:
Response Body

More information

About the order field: Alipay does not verify the consistency of the amount in the order field and the amount in the payment request. The order information is not applied in fund operations either. This field is mainly used for risk control, supervision, regulatory reporting, and consumption records display. Use the env field if the risk control capability provided by Alipay is needed.

Sample for the order field

Result process logic

For different request results, different actions need to be taken. See the following list for details:

  • S: When this value is returned, the API call succeeds.
  • F: When this value is returned, the API call fails. Take actions according to the corresponding result message or call the API again with a new paymentRequestId value. If the issue persists, contact Alipay Technical Support.
  • U: When this value is returned, check the result code:
    • Result code is not PAYMENT_IN_PROCESS: The API call fails. Call this API again with a new paymentRequestId value.
    • Result code is PAYMENT_IN_PROCESS: Check whether one or more of the three URLs (appLinkUrl, normalUrl, schemeUrl) are returned:
      • one or more of the URLs returned: The transaction is created successfully. Redirect your user to the address specified by the URL to complete the payment.
      • no URLs returned: The transaction creation fails. Call the pay API again with a new paymentRequestId value. If the issue persists, contact Alipay Technical Support.

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The payment is successful, no further action is needed.

ACCESS_DENIEDFAccess is denied.

Contact Alipay Technical Support for detailed reasons.

CURRENCY_NOT_SUPPORT FThe currency is not supported.

Contact Alipay Technical Support for detailed reasons.

EXPIRED_CODEFThe payment code is expired.

The user needs to refresh the payment code.

FRAUD_REJECTFThe transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

Contact Alipay Technical Support when one of the following conditions is met:

  • You want to make an appeal. 
  • The user does not receive the refund within two weeks.  
INVALID_ACCESS_TOKENFThe 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 Alipay Technical Support for detailed reasons.

INVALID_CONTRACTFThe parameter values in the contract do not match those in the current transaction.

Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Alipay Technical Support to troubleshoot the issue.

INVALID_MERCHANT_STATUSFThe merchant status is abnormal because restrictions exist.

Contact Alipay Technical Support for detailed reasons.

INVALID_PAYMENT_CODEFThe payment code cannot be accepted by Alipay+.

Choose other payment methods. Contact Alipay Technical Support if the payment method is supported.

INVALID_PAYMENT_METHOD_META_DATAFThe payment method metadata is invalid.

Check whether payment method metadata is correct. If correct, contact Alipay Technical Support.

KEY_NOT_FOUNDFThe private key or public key of Alipay or the merchant is not found.

Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center.

MERCHANT_KYB_NOT_QUALIFIEDFThe payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction.

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_INTERFACE_DEFFAPI is not defined.

Check whether the URL is correct. Please refer to the endpoint in the API documentation.

NO_PAY_OPTIONSFNo payment options are available.

Contact Antom Technical Support for detailed reasons.

ORDER_IS_CANCELEDFThe request you initiated has the same paymentRequestId as the previously paid transaction, which is canceled.

Use a new paymentRequestId to initiate the payment again.

ORDER_IS_CLOSEDFThe paymentRequestId of your request is already used for a transaction, which is closed.

Use a new paymentRequestId to initiate a payment.

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.

PAYMENT_AMOUNT_EXCEED_LIMITFThe payment amount is greater than the maximum amount allowed by the contract or payment method.

Check whether the payment amount exceeds the limit or use a lower amount and try again. Contact Alipay technical support to know the specific limitation.

PAYMENT_COUNT_EXCEED_LIMITFThe maximum number of payments exceeds the limit that is specified by the payment method.

Contact Alipay Technical Support to know the specific limitation.

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 for detailed reasons.

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.

REPEAT_REQ_INCONSISTENTFThe amount or currency is different from the previous request.

Ensure all the fields in the requests are the same or use a new paymentRequestId to initiate the payment again.

RISK_REJECTFThe transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

If the user does not receive the refund within two weeks, contact Alipay Technical Support. 

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.
SYSTEM_ERRORFA system error occurred.

Do not retry, and contact Alipay Technical Support for more details.

USER_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the user payment limit.

Create a new payment by using an amount less than or equal to the account's available balance, or contact Alipay Technical Support.

USER_BALANCE_NOT_ENOUGHFThe payment cannot be completed because the user balance in the corresponding payment method is not enough.

Please top up the account or choose other payment methods.

USER_KYC_NOT_QUALIFIEDFThe payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information).

Complete the KYC verification first.

PAYMENT_IN_PROCESSUThe payment is being processed.

Get any of the URLs (appLinkUrl, normalUrl, schemeUrl) and open the cashier page. If no URL is returned, call the pay API again with a new paymentRequestId value. If the issue persists, contact Alipay Technical Support.

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

Call the interface again to resolve the issue. If not resolved, 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.

USER_NOT_EXISTFThe user does not exist on the wallet side.

Contact Alipay Technical Support for detailed reasons.

ORDER_NOT_EXISTFThe order does not exist.

Check whether paymentId is correct.

ORDER_STATUS_INVALIDFThe transaction cannot be further processed because the order status is invalid.

Check the order status of the transaction or contact Alipay Technical Support for detailed reasons.   

USER_PAYMENT_VERIFICATION_FAILEDFUser fails to pass the payment verification in the methods like OTP, PIN, and so on.

Contact Alipay Technical Support to know the specific reasons.

USER_STATUS_ABNORMALFThe user status is abnormal on the wallet side.

Contact Alipay Technical Support to know the specific reasons.

VERIFY_TIMES_EXCEED_LIMITFThe current verification code failed to pass the payment verification too many times.

The user must get a new verification code.

VERIFY_UNMATCHEDFThe verification code is invalid.

The user must get a new verification code.

AUTHENTICATION_REQUIREDF3D Secure authentication is required.

Reinitiate the payment and redirect the user to perform 3D Secure authentication. 

SELECTED_CARD_BRAND_NOT_AVAILABLEFThe card brand that the user selected to pay is not available.

The card brand that the user selected to pay is not available. 

PAYMENT_PROHIBITEDFThe payment cannot be processed because the goods are prohibited from sale in the country.

You are not allowed to appeal against this transaction. 

INVALID_EXPIRATION_DATEFThe value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is invalid.

Check whether the value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is correct:

  • If not correct, pass in the correct value.
  • If correct, contact Alipay Technical Support for detailed reasons.
INVALID_CARD_NUMBERFThe number of the card used for the transaction is invalid.

Check whether the value of paymentMethod.paymentMethodMetaData.cardno is correct:

  • If not correct, pass in the correct value and try again.
  • If correct, this card is not supported by the transaction, use another card to pay the transaction.
CARD_NOT_SUPPORTEDFThe card used for the transaction is not supported.

Use another card to pay the transaction.

DO_NOT_HONORFThe payment is declined by the issuing bank.

Retry the payment using a different card or contact the issuing bank.

INVALID_AMOUNTFThe transaction was declined by the issuing bank due to various reasons. For example, the specified amount is invalid or exceeds the maximum amount limit.

Contact Alipay Technical Support for detailed reasons.