单笔查询接口

2021-02-26 07:00

通过单笔交易查询接口，商户可以根据支付宝交易订单号或商户网站唯一订单号查询交易详细信息。

网关URL

环境	HTTPS请求URL
生产环境	https://intlmapi.alipay.com/gateway.do
测试环境	https://mapi.alipaydev.com/gateway.do

请求参数

参数	类型（长度范围）	参数说明	是否可为空	样例
基本参数
service	String	接口名称。	不可空	single_trade_query
partner	String(16)	签约的支付宝账号对应的支付宝唯一用户号。以2088开头的16位纯数字组成。	不可空	2088001159940003
_input_charset	String	商户网站使用的编码格式，如utf-8、gbk、gb2312等。	不可空	GBK
sign	String	参数值	不可空	d8ed9f015214e7cd59bfadb6c945a87b
sign_type	String	签名方式只支持DSA、RSA、MD5。	不可空	MD5
业务参数
trade_no	String(64)	支付宝根据商户请求，创建订单生成的支付宝交易号。最短16位，最长64位。建议使用支付宝交易号进行查询，用商户网站唯一订单号查询的效率比较低。	可空	2010121502730740
out_trade_no	String(64)	支付宝合作商户网站唯一订单号（确保在商户系统中唯一）。	可空	210909550602881

同步返回

参数	类型（长度范围）	参数说明	是否可为空	样例
基本参数
is_success	String	请求是否成功。请求成功不代表业务处理成功。 T代表成功 F代表失败	不可空	T
sign	String	签名值	不可空	tphoyf4aoio5e6zxoaydjevem2c1s1zo
sign_type	String	签名方式只支持DSA、RSA、MD5。	不可空	MD5
error	String	只有当查询交易失败后，才返回错误代码。	可空	TRADE_NOT_EXIST
业务参数
buyer_email	String	买家支付宝账号。	不可空	tianc002@alipay.com
buyer_id	String	买家支付宝账号对应的支付宝唯一用户号。	不可空	2088002007274897
trade_status	String	交易状态包含： TRADE_FINISHED WAIT_BUYER_PAY TRADE_CLOSED	不可空	TRADE_FINISHED
is_total_fee_adjust	String	调整过－T；没有调整过－F。	不可空	F
out_trade_no	String	支付宝合作商户网站唯一订单号（确保在商户系统中唯一）。	可空	20080108-5
trade_no	String	支付宝根据商户请求，创建订单生成的支付宝交易号。最短16位，最长64位。	不可空	2010073000019942
subject	String	商品的标题/交易标题/订单标题/订单关键字等。	不可空	Cannon相机
flag_trade_locked	String	1表示冻结； 0表示未冻结。	不可空	0
body	String	对一笔交易的具体描述信息。如果是多种商品，请将商品描述字符串累加传给body。	不可空	Canon最新款卡片机
gmt_create	Date	交易创建的时间。格式为yyyy-MM-dd HH:mm:ss。	不可空	2008-01-08 20:36:12
seller_email	String	卖家的支付宝账号。	不可空	tianc001@alipay.com
seller_id	String	卖家支付宝账号对应的支付宝唯一用户号。以2088开头的纯16位数字。	不可空	2088002007272365
total_fee	Number	单位：RMB。交易金额大于0元。担保交易单笔交易金额不能超过100万，精确到小数点后两位。	不可空	325
price	Number	单位为：RMB Yuan。取值范围为[0.01,1000000.00]，精确到小数点后两位。	可空	10.00
quantity	Number	购买数量。	可空	1
coupon_discount	String	支付宝代金券金额	可空	1
use_coupon	String(1)	使用过－T；未使用过－F。	可空	T
discount	String	折扣。	可空	0.00
gmt_last_modified_time	Date	交易额最新修改时间。格式为yyyy-MM-dd HH:mm:ss。	可空	2008-01-08 20:39:30
gmt_payment	Date	交易付款的时间。格式为yyyy-MM-dd HH:mm:ss。	可空	2008-01-08 20:39:30
to_buyer_fee	String	累计的已经退款金额。	可空	1.00
to_seller_fee	String	累计的已打款给卖家的金额。	可空	20.00
payment_type	String	收款类型。	可空	1
operator_role	String	B：买家 S：卖家	可空	B

示例

请求示例

https://intlmapi.alipay.com/gateway.do?service=single_trade_query&sign=d8ed9f015214e7cd59bfadb6c945a87b&trade_no=2010121502730740&partner=2088721091300630&out_trade_no=2009011803596246&sign_type=MD5

返回示例

成功返回

copy

<alipay>
<is_success>T</is_success>
<request>
<param name="_input_charset">UTF-8</param>
<param name="service">single_trade_query</param>
<param name="partner">2088721091300630</param>
<param name="out_trade_no">2009011803596246</param>
<param name="sendFormat">normal</param>
</request>
<response>
<trade>
<body>hello</body>
<buyer_email>intltest059@service.alipay.com</buyer_email>
<buyer_id>2088122921745555</buyer_id>
<discount>0.00</discount>
<flag_trade_locked>0</flag_trade_locked>
<gmt_create>2017-06-15 16:25:31</gmt_create>
<gmt_last_modified_time>2017-06-15 16:25:58</gmt_last_modified_time>
<gmt_payment>2017-06-15 16:25:58</gmt_payment>
<is_total_fee_adjust>F</is_total_fee_adjust>
<operator_role>B</operator_role>
<out_trade_no>2009011803596246</out_trade_no>
<payment_type>100</payment_type>
<price>0.02</price>
<quantity>1</quantity>
<seller_email>test@126.com</seller_email>
<seller_id>2088721091300630</seller_id>
<subject>world</subject>
<to_buyer_fee>0.00</to_buyer_fee>
<to_seller_fee>0.02</to_seller_fee>
<total_fee>0.02</total_fee>
<trade_no>2017061521001003550204235677</trade_no>
<trade_status>TRADE_FINISHED</trade_status>
<use_coupon>F</use_coupon>
</trade>
</response>
<sign>6283ce0cf5aaa812d9c1d29719d53e8d</sign>
<sign_type>MD5</sign_type>
</alipay>

错误输出

copy

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

错误码

基本上API接口的调用的检查是在支付宝的2个级别进行的

第一个级别是在支付宝网关。在这里会进行一些基础的校验，如签名，商家ID是否有效或者是否有权限使用某个接口等。如果校验失败，就会返回相应的错误码，归类在下面的网关错误中。

一旦网关校验通过了，接口请求就会被转发到内部系统进行进一步的处理。这里会进行业务逻辑的校验。如果校验失败，就会返回相应的错误码，归类在业务错误代码中。

业务错误码

错误代码（error_code）	含义
TRADE_NOT_EXIST	交易不存在，请检查提供的商户网站唯一订单号或者支付宝交易号是否正确
ILLEGAL_SIGN	签名不正确
ILLEGAL_DYN_MD5_KEY	动态密钥信息错误
ILLEGAL_ENCRYPT	加密不正确
ILLEGAL_ARGUMENT	参数不正确
ILLEGAL_SERVICE	Service参数不正确
ILLEGAL_USER	客户ID不正确
ILLEGAL_PARTNER	商户ID不正确
ILLEGAL_EXTERFACE	接口配置不正确
ILLEGAL_PARTNER_EXTERFACE	商户接口信息不正确
ILLEGAL_SECURITY_PROFILE	未找到匹配的密钥配置
ILLEGAL_AGENT	代理ID不正确
ILLEGAL_SIGN_TYPE	签名类型不正确
ILLEGAL_CHARSET	字符集不合法
ILLEGAL_CLIENT_IP	客户端IP地址无权访问服务
HAS_NO_PRIVILEGE	无权访问
ILLEGAL_DIGEST_TYPE	摘要类型不正确
ILLEGAL_DIGEST	文件摘要不正确
ILLEGAL_FILE_FORMAT	文件格式不正确
ILLEGAL_ENCODING	不支持该编码类型
EXTERFACE_IS_CLOSED	接口已关闭
ILLEGAL_REQUEST_REFERER	防钓鱼检查不支持该请求来源
ILLEGAL_ANTI_PHISHING_KEY	防钓鱼检查非法时间戳参数
ANTI_PHISHING_KEY_TIMEOUT	防钓鱼检查时间戳超时
ILLEGAL_EXTER_INVOKE_IP	防钓鱼检查非法调用IP

系统错误码

当出现系统错误提示时，请联系支付宝技术支持协助处理。

错误代码（error_code）	含义
SYSTEM_ERROR	支付宝系统错误
SESSION_TIMEOUT	session超时
ILLEGAL_TARGET_SERVICE	错误的target_service
ILLEGAL_ACCESS_SWITCH_SYSTEM	partner不允许访问该类型的系统
EXTERFACE_IS_CLOSED	接口已关闭

收款类型

枚举名	枚举说明
01	红包结算金预收款
02	红包结算金
03	提醒收款
04	自动发货商品
1	商品购买
2	服务购买
3	网络拍卖
4	捐赠
5	邮费补偿
6	奖金
7	基金购买
8	机票购买
9	收AA款
10	团购
11	电子客票
12	彩票
13	拍卖
14	手机支付类型
15	鲜花礼品
16	代理商电子客票
17	党费
18	外汇
19	自动直充
20	境外收单退款
21	即时到账退款
22	业务保证金
24	送礼金
25	交房租
26	motopay类型
23	购物车支付
27	团购担保交易付款

交易状态

枚举名	枚举说明
WAIT_BUYER_PAY	等待买家付款
WAIT_SELLER_SEND_GOODS	买家已付款，等待卖家发货
WAIT_BUYER_CONFIRM_GOODS	卖家已发货，等待买家确认
TRADE_FINISHED	交易成功结束
TRADE_CLOSED	交易中途关闭（已结束，未成功完成）
WAIT_SYS_CONFIRM_PAY	支付宝确认买家银行汇款中，暂勿发货
WAIT_SYS_PAY_SELLER	买家确认收货，等待支付宝打款给卖家
TRADE_REFUSE	立即支付交易拒绝
TRADE_REFUSE_DEALING	立即支付交易拒绝中
TRADE_CANCEL	立即支付交易取消
TRADE_PENDING	等待卖家收款
TRADE_SUCCESS	支付成功
BUYER_PRE_AUTH	买家已付款（语音支付）
COD_WAIT_SELLER_SEND_GOODS	等待卖家发货（货到付款）
COD_WAIT_BUYER_PAY	等待买家签收付款（货到付款）
COD_WAIT_SYS_PAY_SELLER	签收成功等待系统打款给卖家（货到付款）

交易附加状态

枚举名	枚举说明
ZHIFUBAO_CONFIRM	客服代买家确认收货
ZHIFUBAO_CANCEL_FP	客服代付款方取消快速支付
DAEMON_CONFIRM_CANCEL_PRE_AUTH	超时程序取消预授权
DAEMON_CONFIRM_CLOSE	超时程序因买家不付款关闭交易