single_trade_query

2025-01-20 08:29

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

Environment	HTTPS request URL
Production environment	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

Request parameters

Parameter Description

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

Parameter Description

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 code	Description
TRADE_NOT_EXIST	The trade doesn't exist. Check whether out_trade_no or Alipay trade_no is incorrect.
ILLEGAL_SIGN	Illegal signature
ILLEGAL_DYN_MD5_KEY	Dynamic key information is incorrect.
ILLEGAL_ENCRYPT	Encryption is incorrect.
ILLEGAL_ARGUMENT	Parameter is incorrect.
ILLEGAL_SERVICE	Service parameter is incorrect.
ILLEGAL_USER	User ID is incorrect.
ILLEGAL_PARTNER	Partner ID is incorrect.
ILLEGAL_EXTERFACE	Interface configuration is incorrect.
ILLEGAL_PARTNER_EXTERFACE	Partner's interface information is incorrect.
ILLEGAL_SECURITY_PROFILE	Matching private key configuration has not been found.
ILLEGAL_AGENT	Agency ID is incorrect.
ILLEGAL_SIGN_TYPE	The signature type is incorrect.
ILLEGAL_CHARSET	The character set is illegal.
ILLEGAL_CLIENT_IP	Client IP address is illegal
HAS_NO_PRIVILEGE	No right to visit
ILLEGAL_DIGEST_TYPE	Digest type is illegal.
ILLEGAL_DIGEST	Digest is illegal.
ILLEGAL_FILE_FORMAT	File format is illegal.
ILLEGAL_ENCODING	Encoding type is illegal.
EXTERFACE_IS_CLOSED	API is closed.
ILLEGAL_REQUEST_REFERER	Anti-phishing checks the illegal request.
ILLEGAL_ANTI_PHISHING_KEY	Anti-phishing checks the illegal timeframe.
ANTI_PHISHING_KEY_TIMEOUT	Anti-phishing checks the timeframe timeout.
ILLEGAL_EXTER_INVOKE_IP	IP Anti-phishing checks the illegal IP.

System errors

Returned result	Description
SYSTEM_ERROR	Alipay system failed to process the request due to temporary internal glitch.
SESSION_TIMEOUT	Session timeout
ILLEGAL_TARGET_SERVICE	Wrong target service
ILLEGAL_ACCESS_SWITCH_SYSTEM	Merchant is not allowed to visit the system of this type.
EXTERFACE_IS_CLOSED	The interface has been closed.

Payment type

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

Transaction status

Status	Description
WAIT_BUYER_PAY	Transaction awaits user payment.
WAIT_SELLER_SEND_GOODS	Transaction awaits seller sending goods.
WAIT_BUYER_CONFIRM_GOODS	Transaction awaits buyer confirming goods.
TRADE_FINISHED	Transaction is finished successfully.
TRADE_CLOSED	Transaction is closed during processing (finished, not successfully)
WAIT_SYS_CONFIRM_PAY	Transaction awaits system confirming the payment. Do not provide the goods to the customer before the payment is confirmed.
WAIT_SYS_PAY_SELLER	The buyer confirms the goods, and the transaction awaits system to pay to seller.
TRADE_REFUSE	Transaction is refused.
TRADE_REFUSE_DEALING	Transaction is refused.
TRADE_CANCEL	Transaction is cancelled.
TRADE_PENDING	Transaction is pending.
TRADE_SUCCESS	Transaction is completed, and is available for refund.
BUYER_PRE_AUTH	The buyer has paid. (IVR Payment)
COD_WAIT_SELLER_SEND_GOODS	Transaction awaits the seller to provide the goods to the customer. (COD)
COD_WAIT_BUYER_PAY	Transaction awaits user payment. (COD)
COD_WAIT_SYS_PAY_SELLER	Buyer confirms that the goods is received, and the transaction awaits system paying to seller. (COD)

Additional trade status

Status	Description
ZHIFUBAO_CONFIRM	The custom service confirms goods for buyer.
ZHIFUBAO_CANCEL_FP	The custom service cancels the instant payment for buyer.
DAEMON_CONFIRM_CANCEL_PRE_AUTH	Expiration program cancels the pre-authorization.
DAEMON_CONFIRM_CLOSE	Expiration 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>