Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

single_trade_query

Call this interface to obtain the information of a particular transaction, such as the transaction ID, out_trade_no, and transaction status.

Request

Service address

EnvironmentHTTPS request URL
Production environmenthttps://intlmapi.alipay.com/gateway.do
Test environmenthttps://mapi.alipaydev.com/gateway.do

Request parameters

ParameterDescription
Basic parameter

service

String Required

Interface name 

Example:single_trade_query

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088. 

Example:2088*********662

_input_charset

String Required

The charset with which the request data is encoded. UTF-8, GBK, and GB2312 are supported. 

Example:UTF-8

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase. 

Example:MD5

sign

String Required

Sign value 

Example:7d314d22efba4f336fb187697793b9d2

Business parameter

trade_no

String(64)

The unique transaction ID assigned by Alipay, with a length in the range 16 - 64 bits. If out_trade_no and trade_no appear at the same time, trade_no takes precedence. Note: This field is required when out_trade_no is not provided.

Example:2008102303210710

out_trade_no

String(64)

The unique transaction ID that is assigned by the partner. If both trade_no and out_trade_no appear, trade_no takes precedence. Note: This parameter is required when trade_no is not provided. 

Example:990xxxxxxx8989

Notes:

  • Only the HTTPS request is supported for this API.
  • Do not use the halfwidth quotation mark (") in parameter values.

Response

Synchronous response

ParameterDescription
Basic parameter

is_success

String Required

Indicates whether the request succeeds or not, with a value of T for success and F for failure.

Example:T

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase. 

Example:MD5

sign

String Required

Sign value 

Example:7d314d22efba4f336fb187697793b9d2

error

String

Error message

Example:TRADE_NOT_EXIST

Business parameter

buyer_email

String Required

Buyer’s Alipay account

Example:t********@alipay.com

buyer_id

String Required

The unique buyer ID assigned by Alipay

Example:2088002007018955

trade_status

String Required

The transaction status, with a value of TRADE_FINISHED, WAIT_BUYER_PAY, or TRADE_CLOSED. See Trade status for details. 

Example:TRADE_FINISHED

is_total_fee_adjust

String Required

Indicates whether the total fee is adjusted. The value is T for the adjusted total fee and F for the non-adjusted total fee. 

Example:F

out_trade_no

String

The unique transaction ID that is assigned by the partner

Example:990xxxxxxx8989

trade_no

String Required

The unique transaction ID assigned by Alipay, with a length in the range 16 - 64 bits. If out_trade_no and trade_no appear at the same time, trade_no takes precedence. 

Example:2008102303210710

subject

String(256) Required

Brief description of the transaction. Special characters are not supported. Note: The value of this field will be displayed to customers. 

Example:kids clothing

flag_trade_locked

String Required

Indicates whether the trade transaction is locked. If the value is 1, the transaction is locked. If the value is 0, the transaction is not locked. 

Example:0

body

String

Detailed description about the goods. Special characters are not supported.

Example:Glitter leggings

gmt_create

Date Required

The time when the transaction is created. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8.

Example:2008-10-22 20:49:31

seller_email

String Required

Partner Alipay account

Example:tianc001@alipay.com

seller_id

String Required

A unique seller ID assigned by Alipay. This 16-digit number begins with 2088.

Example:2088002007018966

total_fee

Number Required

The transaction amount in CNY. It is the exact amount that the buyer has paid. Accurate to two decimal places. The transaction amount is in HKD when the buyer paid by Alipay HK. 

Example:100

price

Number(11,2)

Goods prices, which is accurate to 2 digits after the decimal point. The unit is RMB and the value is in the range 0.01 - 100000000.00. The unit is HKD when the buyer paid by Alipay HK.

Example:10.00

quantity

Number

The quantity of goods 

Example:1

coupon_discount

String

The amount of Alipay coupon discount 

Example:1

use_coupon

String(1)

Indicates whether the Alipay coupon is used in the transaction. The value can be T for a used coupon and F a coupon that is not used. 

Example:T

discount

Number

The discount amount 

Example:0.00

gmt_last_modified_time

Date

The last time when the value of total_fee is modified. Format: yyyy-MM-dd HH:mm:ss. Use GMT +8 

Example:2008-01-08 20:39:30

gmt_payment

Date

The time when the transaction is paid by the buyer. Format: yyyy-MM-dd HH:mm:ss. Use GMT+8. 

Example:2008-10-22 20:49:50

to_buyer_fee

String

The accumulative refunded amount paid to the buyer 

Example:1.00

to_seller_fee

String

The accumulative amount paid to the seller 

Example:20.00

payment_typeString

The payment type. See Payment Type for details. 

Example:1

operator_role

String

The operator role, with a value of B for buyers or S for sellers. 

Example:B

Error codes

Business errors

Error codeDescription
TRADE_NOT_EXISTThe trade doesn't exist. Check whether out_trade_no or Alipay trade_no is incorrect.
ILLEGAL_SIGNIllegal signature
ILLEGAL_DYN_MD5_KEYDynamic key information is incorrect.
ILLEGAL_ENCRYPTEncryption is incorrect.
ILLEGAL_ARGUMENTParameter is incorrect.
ILLEGAL_SERVICEService parameter is incorrect.
ILLEGAL_USERUser ID is incorrect.
ILLEGAL_PARTNERPartner ID is incorrect.
ILLEGAL_EXTERFACEInterface configuration is incorrect.
ILLEGAL_PARTNER_EXTERFACEPartner's interface information is incorrect.
ILLEGAL_SECURITY_PROFILEMatching private key configuration has not been found.
ILLEGAL_AGENTAgency ID is incorrect.
ILLEGAL_SIGN_TYPEThe signature type is incorrect.
ILLEGAL_CHARSETThe character set is illegal.
ILLEGAL_CLIENT_IPClient IP address is illegal
HAS_NO_PRIVILEGENo right to visit
ILLEGAL_DIGEST_TYPEDigest type is illegal.
ILLEGAL_DIGESTDigest is illegal.
ILLEGAL_FILE_FORMATFile format is illegal.
ILLEGAL_ENCODINGEncoding type is illegal.
EXTERFACE_IS_CLOSEDAPI is closed.
ILLEGAL_REQUEST_REFERERAnti-phishing checks the illegal request.
ILLEGAL_ANTI_PHISHING_KEYAnti-phishing checks the illegal timeframe.
ANTI_PHISHING_KEY_TIMEOUTAnti-phishing checks the timeframe timeout.
ILLEGAL_EXTER_INVOKE_IPIP Anti-phishing checks the illegal IP.

System errors

Returned resultDescription
SYSTEM_ERRORAlipay system failed to process the request due to temporary internal glitch.
SESSION_TIMEOUTSession timeout
ILLEGAL_TARGET_SERVICEWrong target service
ILLEGAL_ACCESS_SWITCH_SYSTEMMerchant is not allowed to visit the system of this type.
EXTERFACE_IS_CLOSEDThe interface has been closed.

Payment type

TypeDescription
01Coupon Fee Pre-payment
02Coupon Fee Payment
03Reminding Payment
04Automatic Sending Goods
1Merchandise
2Service Purchase
3Online Auction
4Donation
5Post Fee Compensation
6Bonus
7Funds Purchase
8Air Ticket
9Go Dutch
10Group Purchase
11Electronic Ticket
12Lottery Ticket
13Auction
14Mobile Payment
15Flowers & Gifts
16Agent Electronic Ticket
17Party Membership Dues
18Foreign Exchange
19Automatic Charge
20Refund of Overseas Payment
21Refund of Instant Payment
22Business Deposit
24Cash Gift
25Rent
26Motopay
23Shopping Chart
27Escrow Payment of Group Purchase

Transaction status

StatusDescription
WAIT_BUYER_PAYTransaction awaits user payment.
WAIT_SELLER_SEND_GOODSTransaction awaits seller sending goods.
WAIT_BUYER_CONFIRM_GOODSTransaction awaits buyer confirming goods.
TRADE_FINISHEDTransaction is finished successfully.
TRADE_CLOSEDTransaction is closed during processing (finished, not successfully)
WAIT_SYS_CONFIRM_PAYTransaction awaits system confirming the payment. Do not provide the goods to the customer before the payment is confirmed.
WAIT_SYS_PAY_SELLERThe buyer confirms the goods, and the transaction awaits system to pay to seller.
TRADE_REFUSETransaction is refused.
TRADE_REFUSE_DEALINGTransaction is refused.
TRADE_CANCELTransaction is cancelled.
TRADE_PENDINGTransaction is pending.
TRADE_SUCCESSTransaction is completed, and is available for refund.
BUYER_PRE_AUTHThe buyer has paid. (IVR Payment)
COD_WAIT_SELLER_SEND_GOODSTransaction awaits the seller to provide the goods to the customer. (COD)
COD_WAIT_BUYER_PAYTransaction awaits user payment. (COD)
COD_WAIT_SYS_PAY_SELLERBuyer confirms that the goods is received, and the transaction awaits system paying to seller. (COD)

Additional trade status

StatusDescription
ZHIFUBAO_CONFIRMThe custom service confirms goods for buyer.
ZHIFUBAO_CANCEL_FPThe custom service cancels the instant payment for buyer.
DAEMON_CONFIRM_CANCEL_PRE_AUTHExpiration program cancels the pre-authorization.
DAEMON_CONFIRM_CLOSEExpiration program cancels the transaction because the buyer did not pay.

Samples

Request

Request sample with the out_trade_no field specified:

https://intlmapi.alipay.com/gateway.do?service=single_trade_query&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&out_trade_no=out_trade_no_20190826_204556&sign=6d1118194460012bb589620676b5aff2

Request sample with the trade_no field specified:

https://intlmapi.alipay.com/gateway.do?service=single_trade_query&partner=208xxxxxxxxx5500&_input_charset=UTF-8&sign_type=MD5&trade_no=201xxxxxxxxxxxxxxxxxxxxx7821&sign=6c8bdebe125249d86bc0030cedaeb0b3

Response

Request succeeds:

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner">208xxxxxxxxx5500</param>
        <param name="service">single_trade_query</param>
        <param name="_input_charset">UTF-8</param>
        <param name="trade_no">201xxxxxxxxxxxxxxxxxxxxx7003</param>
    </request>
    <response>
        <trade>
            <buyer_email>186******65</buyer_email>
            <buyer_id>208xxxxxxxxx6535</buyer_id>
            <discount>0.00</discount>
            <flag_trade_locked>0</flag_trade_locked>
            <gmt_create>2019-09-10 14:08:34</gmt_create>
            <gmt_last_modified_time>2019-09-10 14:08:38</gmt_last_modified_time>
            <gmt_payment>2019-09-10 14:08:38</gmt_payment>
            <is_total_fee_adjust>F</is_total_fee_adjust>
            <operator_role>B</operator_role>
            <out_trade_no>out_trade_no_20190910_140243</out_trade_no>
            <payment_type>100</payment_type>
            <price>0.01</price>
            <quantity>1</quantity>
            <seller_email>che***@antfin.com</seller_email>
            <seller_id>208xxxxxxxxx5500</seller_id>
            <subject>Mika's coffee shop</subject>
            <to_buyer_fee>0.00</to_buyer_fee>
            <to_seller_fee>0.01</to_seller_fee>
            <total_fee>0.01</total_fee>
            <trade_no>201xxxxxxxxxxxxxxxxxxxxx7003</trade_no>
            <trade_status>TRADE_FINISHED</trade_status>
            <use_coupon>F</use_coupon>
        </trade>
    </response>
    <sign>4dc773bcfe9d661fbb7d3889bb2d751d</sign>
    <sign_type>MD5</sign_type>
</alipay>

Request is failed:

copy
<?xml version="1.0"  encoding="utf-8"?>
  <alipay>
  <is_success>F</is_success>
  <error>ILLEGAL_SIGN</error>
  </alipay>