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

Environment

HTTPS request URL

Production environment

https://intlmapi.alipay.com/gateway.do

Test environment

https://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 are 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 serial number assigned by Alipay to identify a trade in the Alipay system, 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. This parameter 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. This parameter is required when trade_no is not provided. 

Example:990xxxxxxx8989

#Response

#Synchronous response

ParameterDescription
Basic parameter

is_success

String Required

Indicates the status of the API call, 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 code that is returned when the request is failed to describe the request failure reason. For more information, see the Error Code section in this document.

Example:TRADE_NOT_EXIST

Business parameter

buyer_email

String Required

Buyer's Alipay ID, which can be an email address or phone number.

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

buyer_id

String Required

The unique Alipay user ID of the buyer

Example:2088002007018955

trade_status

String Required

Alipay transaction status. The value can be 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

A 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

Merchandise title. Special characters are not supported.

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

Merchandise description. 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

Alipay account of the partner

Example:tianc001@alipay.com

seller_id

String Required

Seller ID, a unique ID assigned by Alipay, which contains 16 digits and 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

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.

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 can be T or F.

T: True

F: False

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_type

String

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 value of 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 system of this type.

EXTERFACE_IS_CLOSED

The interface has been closed.

#Additional information

#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.

TRADE_FINISHED

Transaction is finished successfully.

TRADE_CLOSED

Transaction is closed during processing (finished, not successfully)

#Additional trade status

Status

Description

ZHIFUBAO_CONFIRM

Custom Service confirms goods for buyer.

ZHIFUBAO_CANCEL_FP

Custom Service cancels instant payment for buyer.

DAEMON_CONFIRM_CANCEL_PRE_AUTH

Expiration Program cancels pre-authorization.

DAEMON_CONFIRM_CLOSE

Expiration Program cancels transaction as buyer did not pay.

#Samples

#Request

Request sample with the trade_no field specified

https://intlmapi.alipay.com/gateway.do?service=single_trade_query&partner=2088021017666931&_input_charset=UTF-8&sign_type=MD5&trade_no=2019082622001336531050687821&sign=71f3d322d742f7d272eec685a263baa3


Request sample with the out_trade_no field specified

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


#Response

Synchronous reponse sample

Success response

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="out_trade_no">out_trade_no_20190826_204556</param>
        <param name="partner">208xxxxxxxxx6931</param>
        <param name="service">single_trade_query</param>
        <param name="_input_charset">UTF-8</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-08-26 21:43:08</gmt_create>
        <gmt_last_modified_time>2019-08-26 21:43:10</gmt_last_modified_time>
        <gmt_payment>2019-08-26 21:43:11</gmt_payment>
        <is_total_fee_adjust>F</is_total_fee_adjust>
        <operator_role>B</operator_role>
        <out_trade_no>out_trade_no_20190826_204556</out_trade_no>
        <payment_type>100</payment_type>
        <price>0.07</price>
        <quantity>1</quantity>
        <seller_email>nat***@126.com</seller_email>
        <seller_id>208xxxxxxxxx6931</seller_id>
        <subject>Mika's capsule coffee</subject>
        <to_buyer_fee>0.00</to_buyer_fee>
        <to_seller_fee>0.07</to_seller_fee>
        <total_fee>0.07</total_fee>
        <trade_no>201xxxxxxxxxxxxxxxxxxxxx7821</trade_no>
        <trade_status>TRADE_FINISHED</trade_status>
        <use_coupon>F</use_coupon>
        </trade>
    </response>
    <sign>0e98e20ee3d1e1bc4f10a828c7b100df</sign>
    <sign_type>MD5</sign_type>
</alipay>

Error response

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