pay (Entry 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.
Request parameters
productCode String REQUIRED
The payment product that the merchant can use, based on the contract between the merchant and Alipay. For Entry Code Payment, the value is fixed as IN_STORE_PAYMENT.
paymentRequestId String REQUIRED
More information:
- 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, and the user payment result display, and so on.
paymentAmount Amount REQUIRED
The payment amount that 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. 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, which contains information related to the request result, such as status and error codes.
paymentRequestId String
More information:
- Maximum length: 64 characters
paymentId String
More information:
- Maximum length: 64 characters
paymentAmount Amount
The payment amount that 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, which follows the ISO 8601 standard.
paymentCreateTime Datetime
The date and time when the payment is created, which follows the ISO 8601 standard.
authExpiryTime Datetime
Authorization expiration time, which follows the ISO 8601 standard.
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 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 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 certain 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 for display of consumption records, regulatory reporting, and some 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 setting. 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 code that was generated by Alipay.
• paymentExpiryTime:
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 EntryCode, indicating that Alipay needs to generate a redirection URL 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 initiate a redirection by using the parameters in a form to drive the payment process. - 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.
Result/Error codes
| Code | Value | Message |
|---|---|---|
| SUCCESS | S | Success |
| INVALID_CONTRACT | F | The contract is invalid. |
| INVALID_ACCESS_TOKEN | F | The access token is invalid. |
| USER_NOT_EXIST | F | The user does not exist. |
| CURRENCY_NOT_SUPPORT | F | The currency is not supported. |
| USER_BALANCE_NOT_ENOUGH | F | The user balance is not enough for the payment. |
| USER_STATUS_ABNORMAL | F | The user status is abnormal. |
| NO_PAY_OPTION | F | This is not a valid payment option. |
| ORDER_IS_CANCELED | F | The order is canceled. |
| EXPIRED_CODE | F | The code is expired. |
| PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the limit. |
| PAYMENT_COUNT_EXCEED_LIMIT | F | The number of payments exceeds the limit. |
| REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. |
| PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. |
| USER_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the user payment limit. |
| RISK_REJECT | F | The request is rejected because of the risk control. |
| PROCESS_FAIL | F | A general business failure occurred. Do not retry. |
| KEY_NOT_FOUND | F | The key is not found. |
| ACCESS_DENIED | F | Access denied |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
| API_INVALID | F | API is invalid or not active. |
| CLIENT_INVALID | F | The client is invalid. |
| INVALID_SIGNATURE | F | The signature is invalid. |
| METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. |
| MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
| PAYMENT_IN_PROCESS | U | The payment is being processed. |
| UNKNOWN_EXCEPTION | U | An API calling is failed, which is caused by unknown reasons. |
| PAYMENT_NOT_QUALIFIED | F | The merchant is not qualified to pay because the merchant is not registered, does not have contract for auto debit payment, or is forbidden to make a payment. |
| ORDER_NOT_EXIST | F | The order does not exist. |
| ORDER_IS_CLOSED | F | The order is closed, which might be caused by payment expiration. |
| MERCHANT_NOT_REGISTERED | F | The merchant is not registered. Please register the merchant by using the registration interface. |