alipay.trade.pay
Call the alipay.trade.pay interface to create a Alipay payment order and complete the payment with the pre-authorized funds.
Request
Service address
Environment | HTTPS request URL |
Production environment | |
Test environment |
Request parameters
Parameter | Description |
Basic parameter | |
app_id String (32) | The unique ID that is assigned by Alipay to identify an application. Example: |
method String (128) | Interface name Example: |
format String (40) | Only JSON is supported. Example: |
charset String (10) | The charset with which the request data is encoded. GBK and UTF-8 are supported. Example: |
sign_type String (10) | Signature type. RSA and RSA2 are supported. Use uppercase. Example: |
sign String (344) | Signature value |
timestamp String (19) | The time when the merchant server sends the request. The format is yyyy-mm-dd hh:mm:ss. Example: |
version String (3) | The API version. The value is fixed as 1.0. Example: |
notify_url String (256) | The URL for receiving asynchronous notifications after the pre-auth is completed. Example: |
app_auth_token String (40) | To query authorization information. Example: Note: After a merchant authorizes an ISV to use certain APIs, Alipay will assign an app_auth_token to the ISV. The ISV can use this interface to query the authorization information such as the authorizer and authorized APIs corresponding to the app_auth_token. For more details, see Overview of the app authorization (in Mandarin). |
biz_content String | Collection of request parameters. The maximum length is not limited. Except for common parameters, all other request parameters must be passed in to this parameter. |
Business parameter | |
out_trade_no String (64) | The unique transaction ID that is assigned by the merchant. Example: |
total_amount Price (11) | The total amount Example: |
product_code String (32) | The product code of the Alipay product that you use. The value for this field is Example: |
auth_no String (32) | Payment authorization code Example: |
subject String (100) | The description of the transaction. Note: The value of this field is displayed to customers. Example: |
buyer_id String (32) | The payee's unique Alipay user ID, which is composed of 16 digits and begins with 2088. Example: |
seller_id String (32) | The unique partner ID assigned by Alipay. The partner ID is composed of 16 digits and begins with 2088. Example: |
auth_confirm_mode String (32) | Status of the pre-auth. Example: |
store_id String (32) | Store ID of the merchant Example: |
terminal_id String (32) | Terminal ID of the merchant Example: |
timeout_express String (5) | The period before pre-auth timeout. The value of this field is 15m by default. The value of this field ranges from 1m to 15d. Note: The following abbreviations are used to present units of time:
Example: |
trans_currency String (8) | Pricing currency Example: |
settle_currency String (8) | Merchant settlement currency Example: |
sub_merchant SubMerchant | The sub-merchant information. See sub-merchant for details. Example: |
extend_params ExtendParams | The additional parameters. See extend_params for details. Example: |
trade_information String (6000) | The trade industry Information. See trade_information for details. Example: |
sub-merchant
Parameter | Description |
merchant_id | The sub-merchant ID. The ID must be uploaded to Alipay in advance via any of the following 2 ways:
|
merchant_name | Sub-merchant name |
merchant_type | The type of the sub-merchants. Possible values include:
Example: |
extend_params
Parameter | Description |
sys_service_provider_id | The system service provider ID, which is used to extract commission return data. The value of this field is the PID that the system service providers use when they sign the agreement with Alipay. Example: |
trade_information
Parameter | Description |
business_type String | The business type. The following five types are supported:
Note: "Others" includes all other business types that do not fall into the first four categories. For example, mobile data service recharge, or airport pick up service. If more than one type is involved, separate the type values with a vertical bar (|). Example: |
hotel_name String | The hotel name that consists of numbers, letters, spaces, and special characters including: < > ( ) [ ] / \ - , . If more than one hotel name exists, separate the values with a vertical bar (|). Specify this field only when business_type is Example: |
check_in_time Date | The check-in time. The format is yyyy-mm-dd, and the timezone is GMT+8. Specify this field only when business_type is Example: |
check_out_time Date | The check-out time. The format is yyyy-mm-dd, and the timezone is GMT+8. Specify this field only when business_type is
|
flight_number String | The flight number. If a flight transfer exists, separate the flight numbers with a vertical bar (|). Specify this field only when business_type is Example: |
departure_time Date | The departure time. The format is yyyy-mm-dd hh:mm, and the timezone is GMT+8. If flight transfer exists, separate the time values with a vertical bar (|). Specify this field only when business_type is Example: |
admission_notice_url String | The admission notice URL. If business_type is Example: |
goods_info String | The goods information that includes SKU names and corresponding quantities. The format is SKU_name^quantity. If more than one type of goods exist, separate the values with a vertical bar (|). Specify this field only when business_type is Example: |
total_quantity Number | The total quantities of all goods in one order. Specify this field only when business_type is Example: |
other_business_type String | If business_type is Example: |
Response
Synchronous response
Parameter | Description |
Basic parameter | |
code String (16) | The gateway return code, which indicates whether the request is accepted by Alipay gateway. Example: |
msg String (32) | Description of the gateway return code Example: |
sub_code String (16) | Processing result of the request Example: |
sub_msg String (64) | Description of the processing result of the request |
sign String (344) | The sign value. See Signature for details. |
Business parameter | |
trade_no String(64) | The serial number assigned by Alipay to identify a trade in the Alipay system. Example: |
out_trade_no String (64) | The unique transaction ID that is assigned by the partner. Example: |
buyer_logon_id String(100) | Buyer's Alipay login ID Example: |
buyer_user_id String (32) | Buyer's unique Alipay user ID Example: |
buyer_user_type String (18) | Buyer type Example: |
total_amount Price (11) | Total amount Example: |
point_amount Price (11) | Total amount paid with user points Example: |
trans_currency String (8) | The transaction currency. Use uppercase. Example: |
settle_currency String (8) | The settlement currency. Use uppercase. Example: |
settle_amount Price (11) | Settlement amount Example: |
pay_currency String (8) | Payment currency Example: |
pay_amount Price (11) | Transaction amount Example: |
settle_trans_rate String (11) | The exchange rate between the settlement currency and the transaction currency. Example: |
trans_pay_rate String (11) | The exchange rate between the transaction currency and the payment currency. Example: |
gmt_payment Date | Payment time Example: |
Asynchronous response
Parameter | Description |
app_id String (64) | The unique ID that is assigned by Alipay to identify an application. |
trade_no String (64) | The serial number assigned by Alipay to identify a trade in the Alipay system. |
out_trade_no String (64) | The unique transaction ID that is assigned by the partner. |
out_biz_no String (64) | Business number in partner system |
buyer_logon_id String (100) | Buyer logon ID |
buyer_id String (32) | Buyer UID |
seller_id String (32) | Partner ID |
seller_email String (100) | Partner email |
total_amount Price (11) | Total transaction amount |
trans_currency String (8) | Transaction currency |
settle_currency String (8) | Settlement currency |
settle_amount Price (11) | Settlement amount |
pay_currency String (8) | Payment currency |
pay_amount Price (11) | Payment amount |
settle_trans_rate String (11) | The exchange rate between settlement currency and the transaction currency. |
trans_pay_rate String (11) | The exchange rate transaction currency and the payment currency. |
trade_status String (20) | The trade status. Possible values include:
|
subject String (100) | Transaction description |
body String (100) | General information of the transaction |
gmt_create Date | Transaction creation time |
gmt_payment Date | Transaction payment time |
gmt_refund Date | Transaction refund time |
gmt_close Date | Transaction completion time |
unfreeze_amount Price (11) | After the pre-auth is completed, the remaining amount is returned to the buyer. |
Notification trigger condition
Trigger condition name | Description | Note |
tradeStatus.TRADE_CLOSED | Trade closed | false (does not trigger notification) |
tradeStatus.TRADE_FINISHED | Trade finished | false (does not trigger notification) |
tradeStatus.TRADE_SUCCESS | Trade completed successfully | true (triggers notification) |
tradeStatus.WAIT_BUYER_PAY | Trade created | false (does not trigger notification) |
Error codes
Error Code | Description |
ACQ.SYSTEM_ERROR | System error |
ACQ.INVALID_PARAMETER | Incorrect parameter |
ACQ.ACCESS_FORBIDDEN | You have no permission to use the product. |
ACQ.EXIST_FORBIDDEN_WORD | Prohibited words are included. |
ACQ.PARTNER_ERROR | Incorrect APPID or abnormal status. |
ACQ.TOTAL_FEE_EXCEED | The frozen amount exceeds the limit. |
ACQ.PAYMENT_AUTH_CODE_INVALID | The user's payment code is invalid. |
ACQ.CONTEXT_INCONSISTENT | The trade information has been modified. |
ACQ.TRADE_HAS_SUCCESS | The trade is successful. |
ACQ.TRADE_HAS_CLOSE | The trade is closed. |
ACQ.BUYER_BALANCE_NOT_ENOUGH | The customer's balance is not enough. |
ACQ.BUYER_BANKCARD_BALANCE_NOT_ENOUGH | The customer's bank account balance is not enough. |
ACQ.ERROR_BALANCE_PAYMENT_DISABLE | The customer's balance is unavailable. |
ACQ.BUYER_SELLER_EQUAL | The payer and payee cannot be the same. |
ACQ.TRADE_BUYER_NOT_MATCH | The payment and pre-auth customer does not match. |
ACQ.BUYER_ENABLE_STATUS_FORBID | The customer status is abnormal. |
ACQ.BEYOND_PAY_RESTRICTION | The merchant's payment amount exceeds the limit. |
ACQ.BEYOND_PER_RECEIPT_RESTRICTION | The merchant's payment amount exceeds the monthly limit. |
ACQ.SELLER_BEEN_BLOCKED | The merchant account is frozen. |
ACQ.INVALID_STORE_ID | The store ID is invalid. |
ACQ.SUB_MERCHANT_CREATE_FAIL | The merchant failed to create. |
ACQ.SUB_MERCHANT_TYPE_INVALID | The merchant type is invalid. |
ACQ.MERCHANT_AGREEMENT_NOT_EXIST | The business contract does not exist. |
ACQ.MERCHANT_AGREEMENT_INVALID | The business contract is invalid. |
ACQ.MERCHANT_STATUS_NOT_NORMAL | The business contract status is abnormal. |
ACQ.AMOUNT_OR_CURRENCY_ERROR | The transaction amount or currency is incorrect. |
ACQ.CURRENCY_NOT_SUPPORT | The currency is not supported. |
Sample
Request
"biz_content": {
"auth_no":"2018092610002001000225691613",
"out_trade_no":"PT20180909262008002",
"subject":"TradePay001",
"total_amount":"3000.00",
"trans_currency":"THB",
"settle_currency":"THB",
"buyer_id":"2088622903359001",
“seller_id":"2088621898856371",
"auth_confirm_mode":"COMPLETE",
"store_id":"StoreDavidTest01",
"sub_merchant":{
"merchant_id":"MerchantDavidTest01",
"merchant_type":"merchant"
},
"extend_params":{
"sys_service_provider _id":"2088421609886161"
}
"product_code":"OVERSEAS_INSTORE_AUTH"
}