pay (Auto Debit)
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 Auto Debit Payment, the value is fixed as AGREEMENT_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:
- 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
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.
Note: The time specified in this field must be within one minute after the payment request is sent by the merchant.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
isAuthorization Boolean
Indicates whether the request is a payment authorization.
paymentVerificationData PaymentVerificationData
Payment verification information
paymentFactor PaymentFactor
Specifies the payment scenario
settlementStrategy SettlementStrategy
The settlement strategy for the payment request
creditPayPlan CreditPayPlan
The credit payment plan information for this payment when the payment method is credit payment.
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
paymentNotifyUrl URL
The URL that is used to receive the payment result notification.
Note: Specify this field if you want to receive an asynchronous notification of the auto debit result. You can also set the URL to receive the payment result notification in Alipay Developer Center. But if the payment notification URL is specified in both the request and Alipay Developer Center, the value specified in the request takes precedence.
More information:
- Maximum length: 2048 characters
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.
More information:
- Maximum length: 64 characters
paymentId String
The unique ID that is assigned by Alipay to identify a payment.
More information:
- 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.
More information:
- 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:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
authExpiryTime Datetime
Authorization expiration time.
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+ MPP.
Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.
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
The value of this field equals to transaction amount multiplied by the value of settlementQuote, which is the actual settlement amount of this transaction for the corresponding refund amount. This field is only provided when the currency exchange is predetermined and the exchange rate is locked at the time of transaction. This field will be empty for all other cases.
settlementQuote Quote
The exchange rate between the settlement currency and payment currency.
Note: This field is empty when the value of grossSettlementAmount is null.
Request
Response
More information
This section gives additional information about other parameters. See the following list for details:
• 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.
• 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.
• paymentMethodType:
By specifying this field, it indicates that the payment is made by using the specific wallet.
• paymentMethodId:
By specifying this field, it indicates that the token generated by the contract is used for deduction.
• 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.
• 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 is then decided by the contract.
• authExpiryTime:
If the value of isAuthorization is true, a specific value is returned.
Result process logic
For different request results, different actions are to be performed. See the following list for details:
When the value of isPaymentEvaluation is false:
- If the value of result.resultStatus is
S, the payment request is successfully processed by Alipay. - If the value of result.resultStatus is F, the payment request fails.
- If the value of result.resultStatus is U, the result is unknown and payment initiator needs to check if the value of challengeActionForm, redirectActionForm, or orderCodeForm is empty:
- If the value of orderCodeForm is not empty, the merchant displays the payment information to the user by using the parameters in the form so that the user can proceed.
- If the value of challengeActionForm is not empty, the merchant initiates a challenge by using the parameters in the form to drive the payment process.
- If the value of redirectActionForm is not empty, the merchant initiates a redirection by using the parameters in the form to drive the payment process.
- If all the three fields are empty, the merchant can continue to query the payment result or wait for the notification of the asynchronous payment result.
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 | The payment is successful, no further action is needed. |
| INVALID_ACCESS_TOKEN | F | The access token is invalid. | Check whether the accessToken has expired. If the accessToken has expired, call the applyToken interface to refresh the token or re-sign the contract. |
| USER_NOT_EXIST | F | The user does not exist. | Prompt the user to check whether the user exists. |
| 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. |
| USER_STATUS_ABNORMAL | F | The user status is abnormal. | Prompt the user that the user status is abnormal. |
| NO_PAY_OPTION | F | This is not a valid payment option. | Contact Alipay Technical Support. |
| ORDER_IS_CANCELED | F | The order is canceled. | Re-place the order. |
| PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the limit. | Prompt the user to check whether the payment amount exceeds the limit. |
| PAYMENT_COUNT_EXCEED_LIMIT | F | The number of payments exceeds the limit. | Prompt the user that the number of payments exceeds the limit. |
| 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. | Call the inquiryPayment interface to query the final payment status. |
| UNKNOWN_EXCEPTION | U | An API call failed due to unknown reasons. | Call the inquiryPayment interface to query the final payment status. |
| 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. |