pay (Order Code Payment)
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 Order Code 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. Special characters are not supported.
Note: This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.
Maximum length: 64 characters
order Order 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.
paymentAmount Amount REQUIRED
The payment amount that the merchant requests to receive in the order currency.
payToMethod PaymentMethod
Account asset identification for merchant settlement.
paymentMethod PaymentMethod REQUIRED
The payment method that is used to collect the payment by the payment executor.
paymentExpiryTime Datetime
A specific time, after which the payment will not succeed. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30". The payment expiry time must be less than 30 minutes.
paymentRedirectUrl URL
paymentNotifyUrl URL REQUIRED
isAuthorization Boolean
paymentVerificationData PaymentVerificationData
Payment verification information
paymentFactor PaymentFactor
Specifies the payment scenario
Response parameters
result Result REQUIRED
The request result contains information such as status and error codes.
paymentRequestId String
The unique ID that is assigned by a merchant to identify a payment request. Special characters are not supported.
Maximum length: 64 characters
paymentId String
The unique ID that is assigned by Alipay to identify a payment.
Maximum length: 64 characters
paymentAmount Amount
The payment amount that the merchant requests to receive in the order currency.
paymentTime Datetime
The date and time when the payment reaches a final state of success or failure. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
paymentCreateTime Datetime
The date and time when the payment is created. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
authExpiryTime Datetime
Authorization expiration time. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".
pspCustomerInfo PspCustomerInfo
PMP customer information.
Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.
challengeActionForm ChallengeActionForm
Provides information about the challenge action when the payment result is not in a final state of success or failure.
redirectActionForm RedirectActionForm
Provides information about the redirection action.
orderCodeForm OrderCodeForm
Provides information about the order code.
grossSettlementAmount Amount
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.
settlementQuote Quote
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.
Request
Response
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.
• paymentRequestId:
The unique ID that is assigned by a merchant to identify an payment request. Alipay uses this field for idempotence control. For example, if a payment request has been successfully processed and the merchant submits a new request with the same paymentRequestId, Alipay returns the previous payment result.
• 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.
• payToMethod:
The parameter is mainly used for payee account settings. When the merchant signs the settlement contract with Alipay, the default settlement account will be specified. If the merchant needs to settle to an account that is not the default one, the merchant must specify the new settlement account.
• paymentMethod:
The value of paymentMethod is CONNECT_WALLET, indicating that Alipay collects money from the order code that was generated by Alipay.
• 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 OrderCode, indicating that Alipay needs to generate an order code in this payment.
• paymentId:
If this field is not returned in the response, you can use the paymentRequestId field to initiate inquiryPayment and cancel requests.
• authExpiryTime:
If the value of this field is true, a specific value is returned.
Result process logic
After calling a pay interface, the following results might be returned from Alipay:
- Alipay returns that result.resultStatus is
S, which indicates the merchant needs to display the payment information to the user by using the parameters in a form that the user can proceed. - Alipay returns that result.resultStatus is F, the payment request fails.
- Alipay returns that result.resultStatus is U, the merchant needs to call the pay interface again.
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 following table.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | Payment successful |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. | Use the currency that is agreed in the contract. |
| PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the limit. | Recommend to modify the payment amount. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | Change paymentRequestID and call the interface again. |
| 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. |
| 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. |