pay (Cashier Payment)

2021-12-27 07:52

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. The payment product that can be used 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. Alipay uses this field for idempotence control.

More information:

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 REQUIRED

Information about the order information, such as buyer, merchant, goods, amount, shipping information, and purchase environment. This field is used for different purposes during or after the payment:

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

Show child parameters

paymentAmount Amount REQUIRED

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

Show child parameters

paymentMethod PaymentMethod 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:

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:

Maximum length: 2048 characters

paymentNotifyUrl URL REQUIRED

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

More information:

Maximum length: 2048 characters

settlementStrategy SettlementStrategy REQUIRED

The settlement strategy for the payment request.

Show child parameters

creditPayPlan CreditPayPlan

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:

Maximum length: 32 characters

Response parameters

result Result 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:

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:

Maximum length: 64 characters

paymentAmount Amount

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:

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

pspCustomerInfo PspCustomerInfo

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

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

Information about the order code.

Note: This field is returned when Alipay+ MPP supports providing the related information.

Show child parameters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Method

POST

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.

Returned result code

Result codes are returned to reflect the API calling result. The result codes that reflect the error occurred when calling the API are called error codes. Error codes are usually classified into the following categories:

Common error codes: common for all online and in-store payment APIs.
API-specific error codes: listed in the Result/Error codes section.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	The payment is successful, no further action is needed.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.	Use the currency that is agreed in the contract.
USER_BALANCE_NOT_ENOUGH	F	The user balance is not enough for the payment.	Prompt the user that the balance is insufficient.
ORDER_IS_CANCELED	F	The order is canceled.	Re-place the order.
PAYMENT_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the limit.	Check whether the payment amount exceeds the limit. Contact Alipay technical support to know the speciific limitation.
PAYMENT_COUNT_EXCEED_LIMIT	F	The number of payments exceeds the limit.	Prompt the user that the number of payments exceeds the limit. Contact Alipay technical support to know the speciific limitation.
REPEAT_REQ_INCONSISTENT	F	Repeated requests are inconsistent.	Use a unique paymentRequestId to initiate the payment again.
USER_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the user payment limit.	Prompt the user to check the payment amount.
CLIENT_INVALID	F	The client is invalid.	Check whether the clientId is correct.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	Check whether the HTTP method is correct.
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.
PAYMENT_IN_PROCESS	U	The payment is being processed.	Obtain paymentUrl from the response.
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.
ORDER_NOT_EXIST	F	The order does not exist.	Check whether paymentRequestId is correct.
ORDER_IS_CLOSED	F	The order is closed, which might be caused by payment expiration.	Re-place the order.
USER_KYC_NOT_QUALIFIED	F	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).	Prompt the user to complete KYC.