AlipayHKAlipayHKDOCS

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

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>