Payment (Cashier Payment)
Use this interface to initiate a payment to Alipay and process payment results according to the status and operation instructions returned by Alipay.
Request parameters
The payment product that the merchant can use, based on the contract between the merchant and Alipay. For Cashier Payment, the value is fixed as CASHIER_PAYMENT.
The unique ID that is assigned by a merchant to identify a payment request. Special characters are not supported.
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.
The order amount of the merchant that directly provides services or goods to the customer. This field is used for user consumption records display or payment results page.
The 3-letter currency code that follows the ISO 4217 standard.
Goods information
Price of goods
The 3-letter currency code that follows the ISO 4217 standard.
Shipping information
Shipping address
The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.
Information about the secondary merchant
The merchant category code, which is a four-digit number listed in ISO 18245. This field is required for the PMP.
Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.
The merchant address information
The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.
Merchant registration date, which follows the ISO 8601 standard.
Store information. This parameter is required for offline payment scenarios.
Address of the store
The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.
Information about the environment where the order is placed, such as the device information. This field is required for entry code payments.
Terminal type of which the merchant service applies to. Possible values are:
- WEB: The terminal type of the merchant side is a website.
- WAP: The terminal type of the merchant side is an H5 page on the mobile phone.
- APP: The terminal type of the merchant side is an app on the mobile phone.
Note: This field is required when productCodeType is Cashier payment.
OS type. Possible values are:
- IOS
- ANDROID
Note: This field is required when productCodeType is cashier payment and terminalType is not WEB.
Store terminal ID.
Note: This field is required for the consumer-presented mode payment and order code payment.
The time that the request is sent by the store terminal, which follows the ISO 8601 standard.
Note: This field must be accurate to milliseconds. Besides, this field is required for the consumer-presented mode payment and order code payment. If you don't have the terminal request time, use the gateway time for this field.
Extended information data. This field includes information for special use cases. For example, for orders to Alipay CN, additional information is required as captured in ChinaExtraTransInfo.
The business type. Supported values are
1: Hotel
2: Air Flight
3: Study Abroad
4: Trade
5: Other
Multiple business types are delimited with '|'.
The flightNumber. Mutiple flight numbers are delimited with '|'. when businessType=2, you should pass the value.
The flight departure time. Format as yyyy-MM-dd HH:mm. Multiple flight departure times are delimited with '|'.when businessType=2, you should pass the value.
The hotel name. Multiple hotel names are delimited with '|'. when businessType=1, you should pass the value.
The hotel check-in time. Format: yyyy-MM-dd. Timezone: UTC+8
Multiple hotel check-in times are delimited with '|'.when businessType=1, you should pass the value.
The hotel checkout time. Format: yyyy-MM-dd. Timezone: GMT +8.
Multiple hotel checkout times are delimited with '|'.when businessType=1, you should pass the value.
The school admission notice url. Mulitple URLs are delimited with '|'.when businessType=3, you should pass the value.
Goods information that includes SKU names and corresponding quantities, in the format of SKU_name^quantity. If more than one goods exists, separate values with vertical bar (|). Specify this field only when business_type is 4 (Sales of goods).when businessType=4, you should pass the value.
Total quantities of all goods in one order. Specify this field only when business_type is 4 (Sales of goods).when businessType=4, you should pass the value.
The payment amount that merchant requests to receive in the order currency.
The 3-letter currency code that follows the ISO 4217 standard.
Account asset identification for merchant settlement.
Payment method type:
- For in-store payments, the value is CONNECT_WALLET.
- For auto debit and cashier payments, possible values are:
- TRUEMONEY: TrueMoney wallet.
Note: The minimum payment amount allowed for this wallet is 1 THB. The minimum refund amount allowed for this wallet is 1 THB. - ALIPAY_HK: Alipay HK wallet.
Note: For the auto debit payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum refund amount allowed for this wallet is 0.1 HKD. - TNG: Touch'n Go wallet
Note: The minimum payment amount allowed for this wallet is 0.1 MYR. The minimum refund amount allowed for this wallet is 0.1 MYR. - ALIPAY_CN: Alipay CN wallet
- GCASH: Gcash wallet
Note: The minimum payment amount allowed for this wallet is 1 PHP. The minimum refund amount allowed for this wallet is 1 PHP. - DANA: Dana wallet
Note: The minimum payment amount allowed for this wallet is 300 IDR. The minimum refund amount allowed for this wallet is 300 IDR. - BKASH: bKash wallet
Note: The minimum payment amount allowed for this wallet is 0.01 BDT. The minimum refund amount allowed for this wallet is 0.01 BDT. - EASYPAISA: EasyPaisa wallet
Note: The minimum payment amount allowed for this wallet is 100 PKR. The minimum refund amount allowed for this wallet is 100 PKR. - KAKAOPAY: KakaoPay wallet
Note: The minimum payment amount allowed for this wallet is 50 KRW. The minimum refund amount allowed for this wallet is 50 KRW. - CONNECT_WALLET: Connect wallet
The payment method that is used to collect the payment by the payment executor.
Payment method type.
- For in-store payments, the value is CONNECT_WALLET.
- For auto debit and cashier payments, possible values are:
- TRUEMONEY: TrueMoney wallet.
Note: The minimum payment amount allowed for this wallet is 1 THB. The minimum refund amount allowed for this wallet is 1 THB. - ALIPAY_HK: Alipay HK wallet.
Note: For the auto debit payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum refund amount allowed for this wallet is 0.1 HKD. - TNG: Touch'n Go wallet
Note: The minimum payment amount allowed for this wallet is 0.1 MYR. The minimum refund amount allowed for this wallet is 0.1 MYR. - ALIPAY_CN: Alipay CN wallet
- GCASH: Gcash wallet
Note: The minimum payment amount allowed for this wallet is 1 PHP. The minimum refund amount allowed for this wallet is 1 PHP. - DANA: Dana wallet
Note: The minimum payment amount allowed for this wallet is 300 IDR. The minimum refund amount allowed for this wallet is 300 IDR. - BKASH: bKash wallet
Note: The minimum payment amount allowed for this wallet is 0.01 BDT. The minimum refund amount allowed for this wallet is 0.01 BDT. - EASYPAISA: EasyPaisa wallet
Note: The minimum payment amount allowed for this wallet is 100 PKR. The minimum refund amount allowed for this wallet is 100 PKR. - KAKAOPAY: KakaoPay wallet
Note: The minimum payment amount allowed for this wallet is 50 KRW. The minimum refund amount allowed for this wallet is 50 KRW. - CONNECT_WALLET: Connect wallet
A specific time, after which the payment will not succeed. The value follows the ISO 8601 standard.
Payment verification information
This is the requestId generated by payment site when calling the Authentication Initiation interface that is associated with this request.
Specifies the payment scenario
Indicates the payment scenario of in-store payments. Possible values of inStorePaymentScenario are:
- PaymentCode: Indicates that the user can use the payment code to pay.
- OrderCode: Indicates that the user can use the order code to pay.
- EntryCode: Indicates that the user can use the entry code to pay.
The settlement strategy for the payment request
The credit payment plan information for this payment when the payment method is credit payment.
The value of this field is PERCENTAGE, which indicates that the fee is described in percentage with 1 - 3 digits. For example, 5 means 5%, 100 means 100%.
The value of this field is in the range 0 - 100, which is determined by the sellers' liability. For example: 0 indicates the seller is not liable for any fee. 100 indicates the seller pays 100% of the fee.
Note: This field is required when the value of creditPayFeeType is PERCENTAGE.
Response parameters
The request result, which contains information related to the request result, such as status and error codes.
Result status. Possible values are:
- S:Indicates that the result status is successful.
- F:Indicates that the result status is failed.
- U:Indicates that the result status is unknown.
The payment amount that merchant requests to receive in the order currency.
The 3-letter currency code that follows the ISO 4217 standard.
The date and time when the payment reaches a final state of success or failure, which follows the ISO 8601 standard.
The date and time when the payment is created, which follows the ISO 8601 standard.
Authorization expiration time, which follows the ISO 8601 standard.
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.
The name of PMP.
Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.
The customer ID of PMP.
Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.
Provides information about the challenge action when the payment result is not in a final state of success or failure.
Type of challenge. Possible values are:
- SMS_OTP: SMS OTP verification
- PLAINTEXT_CARD_NO: Plain text card number challenge
- CARD_EXPIRE_DATE: Card expiry date challenge
Provides information about the redirection action.
The HTTP method to be used when the merchant initiates a redirection to the redirection URL. Possible values are:
- POST:Indicates that the request that is sent to the redirection address needs to be a POST request.
- GET: Indicates that the request that is sent to the redirection address needs to be a GET request.
- SCAN: Indicates that the request that is sent to the redirection address needs to be a SCAN request.
Parameteres required for the HTTP method in the key-value pair, which is empty when the method is GET.
The URL where the user is redirected to.
Provides information about the order code.
Payment method type. Possible values are:
- TRUEMONEY: TrueMoney wallet.
Note: The minimum payment amount allowed for this wallet is 1 THB. The minimum refund amount allowed for this wallet is 1 THB. - ALIPAY_HK: Alipay HK wallet.
Note: For the auto debit payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the auto debit payment, the minimum refund amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum payment amount allowed for this wallet is 0.1 HKD. For the cashier payment, the minimum refund amount allowed for this wallet is 0.1 HKD. - TNG: Touch'n Go wallet
Note: The minimum payment amount allowed for this wallet is 0.1 MYR. The minimum refund amount allowed for this wallet is 0.1 MYR. - ALIPAY_CN: Alipay CN wallet
- GCASH: Gcash wallet
Note: The minimum payment amount allowed for this wallet is 1 PHP. The minimum refund amount allowed for this wallet is 1 PHP. - DANA: Dana wallet
Note: The minimum payment amount allowed for this wallet is 300 IDR. The minimum refund amount allowed for this wallet is 300 IDR. - BKASH: bKash wallet
Note: The minimum payment amount allowed for this wallet is 0.01 BDT. The minimum refund amount allowed for this wallet is 0.01 BDT. - EASYPAISA: EasyPaisa wallet
Note: The minimum payment amount allowed for this wallet is 100 PKR. The minimum refund amount allowed for this wallet is 100 PKR. - KAKAOPAY: KakaoPay wallet
Note: The minimum payment amount allowed for this wallet is 50 KRW. The minimum refund amount allowed for this wallet is 50 KRW. - CONNECT_WALLET: Connect wallet
Details about the code
Code type. Possible values are:
- BARCODE: Indicates a bar code.
- QRCODE: Indicates a QR code.
Indicates the way to show the code. Possible values are:
- TEXT: Indicates to be directly shown on UI as text or label.
- MIDDLEIMAGE:Indicates to be shown as a middle size image.
- SMALLIMAGE: Indicates to be shown as a small size image.
- BIGIMAGE: Indicates to be shown as a big size image.
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.
The 3-letter currency code that follows the ISO 4217 standard.
The exchange rate between the settlement currency and payment currency.
Note: This field is empty when the value of grossSettlementAmount is null.
Effective time of the exchange rate, which follows the ISO 8601 standard
Expiration time of the exchange rate, which follows the ISO 8601 standard
More information
This section gives additional information about certain 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.
• 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.
• paymentMethodType:
By specifying the value of this field, it indicates that Alipay is required to return the cashier URL provided by the specified wallet.
• 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.
• paymentRedirectUrl:
The value of paymentRedirectUrl is the merchant page that the user is to be redirected to after the payment is completed. If this field is not specified, Alipay redirects the user to the default redirection address that is configured by the merchant on the Alipay platform.
• paymentNotifyUrl:
URL used to receive the payment result notification. If this parameter is not specified, the payment executor sends the result to the default address that the payment initiator assigned during the integration.
• authExpiryTime:
If the value of isAuthorization is true, a specific value is returned.
• redirectActionForm.redirectUrl:
A 302 redirection to the user's browser and the user will be redirected to the address. When the merchant redirects the user to Alipay payment page, a notification of payment result sent by Alipay needs to be monitored. Details can be found in the description of Payment Result Notification. When the method is GET, redirectUrl contains the complete URL.
Responses for different cases
If a request is submitted with the same payment request ID as a previous request, the following responses might be returned for different cases:
1. The payment amount is different from the previous request that has the same payment request ID.
The paymentRequestId already exists when initiating a new transaction. If the the request amount is inconsistent with the original one, idempotent control is triggered and REPEAT_REQ_INCONSISTENT is returned to report an error.
2. The transaction exists, and the transaction was not paid.
For the unpaid transaction, the following response is returned, which is the same as the response of the previous request with the same payment request ID.
3. The transaction exists, and the transaction was paid successfully.
If the paymentRequestId already exists and the transaction status is SUCCESS when initiating a new transaction, paymentActionForm and redirectActionForm are not returned.
4. The transaction exists, and the transaction was failed.
If the paymentRequestId already exists and the transaction status is FAIL when initiating a new transaction, PROCESS_FAIL is returned to report a error.
5. The transaction exists, and the transaction was cancelled.
If the paymentRequestId already exists and the transaction status is CANCELLED when initiating a new transaction, PROCESS_FAIL is returned to report a error.
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.
Result/Error codes
| Code | Value | Message |
|---|---|---|
| SUCCESS | S | Success |
| INVALID_CONTRACT | F | The contract is invalid. |
| INVALID_CODE | F | The code 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. |
| SIGNATURE_INVALID | 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. |
Request
Method
POST
Endpoint
v1/payments/pay
Header
Accept: application/json
URL
Domain name
Request Body
