pay (Cashier Payment)

2022-05-20 10:40

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 Cashier Payment, the value is fixed as CASHIER_PAYMENT.

paymentRequestId String REQUIRED

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

More information about this field

This field is an API idempotency field.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

The order information, such as buyer, merchant, goods, amount, shipping, 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

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. A default payment expiration time is determined in the contract.

Notes:

Specify this field if you want to use a payment expiration time that differs from the default time. The specified payment expiration time must be less than 10 minutes after the payment request is sent and must follow the correct format.
Usually for Cashier Payment, the default payment expiration time in the contract is 14 minutes after the payment request is sent. For example, the request is sent on 2019-11-27T12:00:01+08:30, the payment expiration time is 2019-11-27T12:14: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".

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 REQUIRED

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

More information about this field

Maximum length: 2048 characters

settlementStrategy SettlementStrategy object REQUIRED

The settlement strategy for the payment request.

Show child parameters

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

Note: This field is required when terminalType is MINI_APP.

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

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 Partners (Alipay+ MPP).

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

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 resultCode is PAYMENT_IN_PROCESS.

Show child parameters

orderCodeForm OrderCodeForm object

Information about the order code.

Note: This field is returned when Alipay+ MPP 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 payment currency. This field is returned when grossSettlementAmount is returned.

Show child parameters

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

More information about this field

Maximum length: 2048 characters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Payment method

AlipayCN

Terminal type

APP

Integration role

Acquirer-merchant Direct-merchant

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:

U: When this value is returned, check whether PAYMENT_IN_PROCESS is the result code:

Result code is not PAYMENT_IN_PROCESS: it means the API calling failed. You need to call this interface again with a new paymentRequestId.
Result code is PAYMENT_IN_PROCESS, continue to check whether redirectActionForm.redirectUrl is returned in the response:

redirectUrl returned: it means the transaction is created successfully. You need to redirect your user to the address specified by rediectUrl to complete the payment.
redirectUrl not returned: it is possible that the payment is already completed. You need to call the inquiryPayment API or wait for the asynchronous notification to check the payment result. If you do so and get the information that the payment is completed successfully, you can proceed with other tasks. If the payment is not completed successfully, you need to call the pay API again with a new paymentRequestId. If the response remains the same, contact Alipay Technical Support.

F: When this value is returned, it means the API calling failed. The corresponding result message provides details about the failure and you can take the suggested actions. Or, you can call this interface again with a new paymentRequestId. If the response remains the same, contact Alipay Technical Support.

Result/Error codes

Code	Value	Message	Further action
ACCESS_DENIED	F	Access is denied.	Contact Alipay Technical Support for detailed reasons.
API_INVALID	F	The API name or API call format is used incorrectly.	Check whether the API name, HTTP method, or request format is correct when sending the request.
CLIENT_INVALID	F	The client ID is invalid. Alipay has restrictions on client ID.	Check whether the client ID is correct, or contact Alipay Technical Support for detailed reasons.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.	Contact Alipay Technical Support for detailed reasons.
INCORRECT_BLIKCODE	F	The blik code is invalid.	Check whether the blik code is correct. If correct, contact Alipay Technical Support.
INVALID_CONTRACT	F	The 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_STATUS	F	The merchant status is abnormal because restrictions exist.	Contact Alipay Technical Support for detailed reasons.
INVALID_PAYMENT_METHOD_META_DATA	F	The payment method metadata is invalid.	Check whether payment method metadata is correct. If correct, contact Alipay Technical Support.
INVALID_SIGNATURE	F	The 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: The signature field in a request header How to calculate a signature
KEY_NOT_FOUND	F	The 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_ACCEPTABLE	F	The 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_QUALIFIED	F	The 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_REGISTERED	F	The 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_SUPPORTED	F	The server does not implement the requested HTTP method. Only the POST method is supported.	Ensure the HTTP method is POST.
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 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_CANCELED	F	The 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_CLOSED	F	The 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_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_AMOUNT_EXCEED_LIMIT	F	The 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_LIMIT	F	The maximum number of payments exceeds the limit that is specified by the wallet.	Contact Alipay Technical Support to know the specific limitation.
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 Alipay 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 Alipay Technical Support to troubleshoot the issue.
REPEAT_REQ_INCONSISTENT	F	The 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_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 Alipay Technical Support for more details.
USER_AMOUNT_EXCEED_LIMIT	F	The 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_ENOUGH	F	The 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_QUALIFIED	F	The 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_PROCESS	U	The payment is being processed.	The request you initiated has the same paymentRequestId as that of the existed transaction, which might be a successful or in-process transaction. Check whether redirectActionForm.redirectUrl is returned in the response. If returned, redirect the user to the address specified by rediectUrl to complete the payment. If not, the payment might already be completed. See Result process logic for details.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Alipay 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 Alipay Technical Support.