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

pay (User-presented Mode Payment)

POST /v1/payments/pay

Use the pay API to initiate a payment to Alipay and process payment results according to the status and operation instructions returned by Alipay.  

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 the merchant can use, based on the contract between the merchant and Alipay. For User-presented Mode Payment, the value is fixed as IN_STORE_PAYMENT.

paymentRequestId String  REQUIRED

The unique ID that is 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.The merchant uses the paymentRequestId field for idempotency control. For payment requests that are initiated with the same value of paymentRequestId and reach a final status (S or F), the same result is to be returned for the request.
  • Maximum length: 64 characters

order Order object REQUIRED

Order information, such as buyer information, merchant information, order description, and order amount. 

The parameter is also used for risk control, supervision, reporting, user payment result display, and so on.

Show child parameters

paymentAmount Amount object REQUIRED

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

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. After the payment expiration time, the acquirer or merchant must terminate the order processing. A default payment expiration time is determined by the contract. If you want to use a payment expiration time that differs from the default time, specify this field. 

Note: Usually for User-Presented Mode Payment, the default payment expiration time in the contract is 10 minutes after the payment request is sent. For example, if the request is sent when the time is 2019-11-27T12:00:01+08:30, the payment expiration time is 2019-11-27T12:10:01+08:30. 

More information about this field

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

paymentNotifyUrl URL  REQUIRED

The URL that is used to receive the payment result notification

More information about this field

  • Maximum length: 2048 characters

paymentFactor PaymentFactor object 

Indicates the payment scenario.

Show child parameters

settlementStrategy SettlementStrategy object 

The settlement strategy for the payment request.

Note: Specify this field when one of the following conditions are met:

  • Multiple settlement contracts are signed and more than one settlement contract supports this transaction. In this case, use this field to specify the settlement currency so that the settlement contract to be used for this transaction can be selected from all the signed settlement contracts.
  • When the value of paymentMethodType is CONNECT_WALLET.
Show child parameters

merchantRegion String  

The country or region where the merchant or secondary merchant operates the business. The 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 about this field

  • Maximum length: 2 characters

Response parameters

result Result object REQUIRED

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

Show child parameters

paymentRequestId String  

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

More information about this field

  • Maximum length: 64 characters

paymentId String  

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

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.

Show child parameters

paymentTime Datetime  

The date and time when the payment reaches a final state of success or failure.

More information about this field

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

paymentCreateTime Datetime  

The date and time when the payment is created. 

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 the Alipay+ MPP .

Note: Alipay+ Mobile Payment Provider, is a Mobile Payment Partner participating in Alipay+ Core or other user- or issuer-facing payment service provider cooperating with a member of Ant Group to enable payments. 

Show child parameters

challengeActionForm ChallengeActionForm object 

Provides information about the challenge action when the payment result is not in a final state of success or failure.

Show child parameters

redirectActionForm RedirectActionForm object 

Information about the redirection action:

  • When the method used for user redirection is GET (method=GET), the value of redirectUrl is a complete URL that can be used for user redirection.
  • When the method used for user redirection is POST (method=POST), the value of redirectUrl is part of a complete URL where the user is to be redirected to. Other parameters needed for a complete URL is provided in the parameters field.

Note: This field is returned when the API is called successfully.   

Show child parameters

grossSettlementAmount Amount object 

Gross settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote

Note: This field is empty when the settlement currency is the same as the transaction currency.

Show child parameters

settlementQuote Quote object 

The exchange rate between the settlement currency and transaction currency at the time of the transaction, which is provided only in the locked-in rate case. 

Note: This field is empty when the settlement currency is the same as the transaction currency.

Show child parameters
API Explorer

Request

URL
Request Body

Response

Response Body

More information 

This section gives additional information about other parameters. See the following parameters for details:

productCode:
The value of this parameter is the payment product that the merchant uses for collecting payments, based on the contract between the merchant and Alipay. When the merchant can use multiple products, this parameter is required.

order:
The order parameter contains order information, such as Merchant, Goods, logistic, and purchase environment. During the payment process, the order information is mainly used by Alipay for risk control or anti-money laundering. After the payment is completed, the information is used to display consumption records, regulatory reporting, and other purposes. However, Alipay does not verify the consistency of the amount in order and the amount in the payment request. The order information is not applied in fund operations either. Use the env field if the risk control capability provided by Alipay is needed.
In this case, order.merchant.referenceMechantId, order.merchant.merchantMCC, order.merchant.store.referenceStoreId, and order.merchant.store.storeMcc are mandatory. It is recommended to specify order.env.storeTerminalRequestTime and order.env.storeTerminalId.

Sample for the order field

paymentMethod:
The value of paymentMethod is CONNECT_WALLET, indicating that Alipay collects money from the user's payment code that was generated by Alipay.

paymentMethodId:
The unique identifier of the user's payment asset, which can be obtained by using the applyToken interface. For User-Presented Mode payments, this field is required and can be used by the merchant to decide which payment service should be called to process the payment. See Payment Code Specification for more information.

paymentExpiryTime:
The payment executor must ensure that the payment will not succeed after the expiration time. If this parameter is not specified in the request, the expiration time is then decided by the payment executor.

paymentFactor:
The value of paymentFactor.inStorePaymentScenario is PaymentCode, indicating that the payment code is used for payment. 

Payment code specifications

An Alipay payment code is a number that is between 16 to 24 digits and starts with a number ranging from 25 to 30.

For user-presented code payments, use the following rules to determine which payment service is to be called:

  • If an Alipay payment code is used for payment, the merchant needs to route the payment to Alipay.
  • If a non-Alipay payment code is used for payment, the merchant needs to route the payment to the corresponding payment provider of the non-Alipay payment code.
  • If a merchant that is integrated with Alipay has integrated with other local wallets that provide payment codes conforming to Alipay payment code rule, for example, the Macao Wallet, or the PayPay wallet, the merchant needs to route the payment to the local wallet system when payment codes from such local wallets are used, or to route the payment to Alipay when Alipay payment codes are used. To determine the payment code belongs to Alipay or the local wallet, use the following rules: 

Asia

Payment code rule

Payment service

Length

First two digits

Special rule

24

25 - 30

The fourth, fifth, and sixth digits are 8, 0, and 1.

PayPay

16~24

25 - 30

/

Alipay

Payment code rule

Payment service

Length

First two digits

Special rule

16~24

25 - 30

The fourth, fifth, and sixth digits are 0, 0, and 3.

Macao Wallet

16~24

25 - 30

/

Alipay

Payment code rule

PaymentService

Length

First two digits

Special rule

16~24

25 - 30

-

Alipay

Payment code rule

PaymentService

Length

First two digits

Special rule

16~24

25 - 30

-

Alipay

Result process logic

After calling a pay interface, the following results might be returned from Alipay or no result is received by the merchant:

  • Alipay returns that result.resultStatus is S, which indicates the transaction succeeds and the money is deducted successfully.
  • Alipay returns that result.resultStatus is F, the merchant needs to take further actions according to the error message in result.resultCode.
  • Alipay returns that result.resultStatus is U, the merchant needs to use the inquiryPayment interface to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of 3 seconds.
  • If no asynchronous notification and payment result are returned from Alipay within 5 seconds after the payment request is sent, the merchant needs to use the inquiryPayment interface to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of 3 seconds.
  • When calling the inquiryPayment interfaces, if no payment result can be obtained after the inquiry requests being sent more than the maximum number of times, the merchant needs to call the cancel interface to cancel the transaction. If being out of the cancellable period, the merchant cannot use the cancel interface to cancel the transaction. The merchant can call the refund interface to make a refund instead. 

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. 

INVALID_APIFThe called API is invalid or not active.

Contact Alipay Technical Support to resolve the issue.  

CLIENT_INVALIDFThe client ID is invalid. Alipay has restrictions on client ID.

Check whether clientId is correct, or 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. 

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_SIGNATUREFThe signature is not validated. The private key used to sign a request does not match the public key of Alipay Developer Center.

Check whether the private key used to sign a request matches the public key of Alipay Developer Center. The following signature references are useful:

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. 

MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

Check whether the media type is correct and use a media type that is accepted by Alipay. 

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. 

METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method. Only the POST method is supported.

Ensure the HTTP method is POST. 

NO_INTERFACE_DEFFAPI is not defined.

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

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

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 request you initiated has the same paymentRequestId as that of the existed transaction, which is closed.

Use a new paymentRequestId to initiate the payment again. 

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

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

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 request is rejected because of the risk control.

Prompt the user that the request is rejected because the risk control failed.  

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. 

USER_NOT_EXISTFThe user does not exist on the wallet side.

Contact Alipay Technical Support for detailed reasons. 

USER_PAYMENT_VERIFICATION_FAILEDFThe user is restricted from payment on the wallet side.

User verification failed, such as OTP or PIN verification. Re-place an order. 

USER_STATUS_ABNORMALFThe user status is abnormal on the wallet side.

Contact Alipay Technical Support to know the specific reasons. 

PAYMENT_IN_PROCESSUThe payment is being processed.

Wait for the asynchronous notification or call the inquiryPayment interface to query the final status of the order. 

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.