统一收单交易查询接口 -凯发app官方网站

支付

当面付

app 支付

接入指南

api 列表

交易

账单

接口说明

接口英文名称：alipay.trade.query

请求url：https://openapi.alipay.com/v3/alipay/trade/query

请求方式：post

path指该参数为路径参数

query指该参数需在请求url传参

body指该参数需在请求json传参

当面付

该接口提供所有支付宝支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。需要调用查询接口的情况：当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知；调用支付接口后，返回系统错误或未知交易状态情况；调用alipay.trade.pay，返回inprocess的状态；调用alipay.trade.cancel之前，需确认支付状态

公共请求参数

参数	类型	是否必选	最大长度	描述	示例值
authorization	string	必选	1024	请求身份信息，参考。在header参数中传递
content-type	string	可选	32	报文内容格式，默认需要使用application/json，加密请求使用text/plain，参考。在header参数中传递	application/json
x-http-method-override	string	可选	16	http方法，对于部分不支持put、patch、delete等操作的情况，可以使用post发送请求，并通过该参数传输实际需要使用的http method，参考。在header参数中传递	put
alipay-request-id	string	可选	32	调用方的requestid，用于定位一次请求，需要每次请求保持唯一。排查问题时可以提供该字段，参考。在header参数中传递。	0ba7cddb1665744697169391253118
alipay-encrypt-type	string	可选	16	加密算法，请求使用加密能力时，需要指定加密算法，参考。在header参数中传递	aes
alipay-root-cert-sn	string	可选	128	支付宝根证书序列号。证书模式时，可传入该参数，支付宝服务端会校验序列号，确保调用方的证书未被篡改，参考。在header参数中传递	687b59193f3f462dd5336e5abf83c5d8_02941eef3187dddf3d3b83462e1dfcf6
alipay-app-auth-token	string	可选	128	应用授权令牌，参考代调用规则。在header参数中传递	201509bbeff9351ad1874306903e96b91d248a36

业务请求参数

body参数

以下参数二选一传入

out_trade_nostring(64)

【描述】订单支付时传入的商户订单号,和支付宝交易号不能同时为空。
trade_no,out_trade_no如果同时存在优先取trade_no

【示例值】20150320010101001

trade_nostring(64)

【描述】支付宝交易号，和商户订单号不能同时为空

【示例值】2014112611001004680 073956707

query_options可选string[](128)

【描述】查询选项，商户通过上送该参数来定制同步需要额外返回的信息字段，数组格式。

【枚举值】

交易结算信息: trade_settle_info

交易支付使用的资金渠道: fund_bill_list

交易支付时使用的所有优惠券信息: voucher_detail_list

【示例值】trade_settle_info

参数	类型	是否必选	最大长度	描述	示例值
out_trade_no	string	二选一	64	订单支付时传入的商户订单号,和支付宝交易号不能同时为空。 trade_no,out_trade_no如果同时存在优先取trade_no	20150320010101001
trade_no	string	64	支付宝交易号，和商户订单号不能同时为空	2014112611001004680 073956707
query_options	string[]	可选	128	查询选项，商户通过上送该参数来定制同步需要额外返回的信息字段，数组格式。枚举值交易结算信息: trade_settle_info 交易支付使用的资金渠道: fund_bill_list 交易支付时使用的所有优惠券信息: voucher_detail_list 交易支付使用单品券优惠的商品优惠信息: discount_goods_detail 商家优惠金额: mdiscount_amount 医保信息: medical_insurance_info	trade_settle_info

常见请求示例

默认示例

curljavac#php

curl -x post \
 "https://openapi.alipay.com/v3/alipay/trade/query" \
 -h "authorization: alipay-sha256withrsa app_id=${appid},timestamp=${now},nonce=${uuid},expired_seconds=600,sign=${sign}" \
 -h "alipay-request-id: ${requestid}" \
 -h "alipay-app-auth-token: ${app_auth_token}" \
 -h "content-type: application/json" \
 -d '{
	"out_trade_no":"20150320010101001",
	"trade_no":"2014112611001004680 073956707",
	"org_pid":"2088101117952222",
	"query_options":[
		"trade_settle_info"
	]
}'

说明：本示例仅供参考。

公共响应参数

参数	类型	是否必选	最大长度	描述	示例值
alipay-timestamp	string	可选	32	unix时间戳，用于验签及问题排查，参考。在header参数中传递	1666004496123
alipay-signature	string	可选	512	支付宝响应报文签名，参考。在header中返回
alipay-traceid	string	可选	64	支付宝traceid ，用于排查问题使用，参考。在header中返回	0ba7cddb1665744697169391253118
alipay-nonce	string	可选	64	支付宝nonce标记，每次请求会生成不同的nonce，可用于防重放判断，参考。在header中返回	515cf24c2f78b13564e94c2a495695ab

业务响应参数

trade_no必选string(64)

【描述】支付宝交易号

【示例值】2013112011001004330000121536

out_trade_no必选string(64)

【描述】商家订单号

【示例值】6823789339978248

buyer_logon_id必选string(100)

【描述】买家支付宝账号

【示例值】159****5620

trade_status必选string(32)

【描述】交易状态：wait_buyer_pay（交易创建，等待买家付款）、trade_closed（未付款交易超时关闭，或支付完成后全额退款）、trade_success（交易支付成功）、trade_finished（交易结束，不可退款）

【示例值】trade_closed

total_amount必选price(11)

【描述】交易的订单金额，单位为元，两位小数。该参数的值为支付时传入的total_amount

【示例值】88.88

fund_bill_list必选tradefundbill[]

【描述】交易支付使用的资金渠道。
只有在签约中指定需要返回资金明细，或者入参的query_options中指定时才返回该字段信息。

fund_channel必选string(32)

【描述】交易使用的资金渠道，详见支付渠道列表

【示例值】alipayaccount

amount必选price(32)

【描述】该支付工具类型所使用的金额

【示例值】10

real_amount可选price(11)

【描述】渠道实际付款金额

【示例值】11.21

buyer_user_id必选string(16)

【描述】买家在支付宝的用户id

新商户建议使用buyer_open_id替代该字段。对于新商户，buyer_user_id字段未来计划逐步回收，存量商户可继续使用。如使用buyer_open_id，请确认应用-开发配置-openid配置管理已启用。无该配置项，可查看openid配置申请。

【示例值】2088101117955611

send_pay_date特殊可选date(32)

【描述】本次交易打款给卖家的时间

【示例值】2014-11-27 15:45:57

receipt_amount特殊可选string(11)

【描述】实收金额，单位为元，两位小数。该金额为本笔交易，商户账户能够实际收到的金额

【示例值】15.25

store_id特殊可选string(32)

【描述】商户门店编号

【示例值】nj_s_001

terminal_id特殊可选string(32)

【描述】商户机具终端编号

【示例值】nj_t_001

store_name特殊可选string(512)

【描述】请求交易支付中的商户店铺的名称

【示例值】证大五道口店

buyer_open_id特殊可选string(128)

【描述】买家支付宝用户唯一标识详情可查看 openid简介

【示例值】01501o8f93i3njagb1jg4onxtxv25dcn3gec3uggnc4cju0

discount_amount特殊可选string(11)

【描述】平台优惠金额

【示例值】88.88

ext_infos特殊可选string(1024)

【描述】交易额外信息，特殊场景下与支付宝约定返回。
json格式。

【示例值】{"action":"cancel"}

buyer_user_type特殊可选string(18)

【描述】买家用户类型。corporate:企业用户；private:个人用户。

【枚举值】

企业用户: corporate

个人用户: private

【示例值】private

mdiscount_amount特殊可选string(11)

【描述】商家优惠金额

【示例值】88.88

buyer_pay_amount可选price(11)

【描述】买家实付金额，单位为元，两位小数。该金额代表该笔交易买家实际支付的金额，不包含商户折扣等金额

【示例值】8.88

point_amount可选price(11)

【描述】积分支付的金额，单位为元，两位小数。该金额代表该笔交易中用户使用积分支付的金额，比如集分宝或者支付宝实时优惠等

【示例值】10

invoice_amount可选price(11)

【描述】交易中用户支付的可开具发票的金额，单位为元，两位小数。该金额代表该笔交易中可以给用户开具发票的金额

【示例值】12.11

参数	类型	是否必选	最大长度	描述	示例值
trade_no	string	必选	64	支付宝交易号	2013112011001004330000121536
out_trade_no	string	必选	64	商家订单号	6823789339978248
buyer_logon_id	string	必选	100	买家支付宝账号	159****5620
trade_status	string	必选	32	交易状态：wait_buyer_pay（交易创建，等待买家付款）、trade_closed（未付款交易超时关闭，或支付完成后全额退款）、trade_success（交易支付成功）、trade_finished（交易结束，不可退款）	trade_closed
total_amount	price	必选	11	交易的订单金额，单位为元，两位小数。该参数的值为支付时传入的total_amount	88.88
buyer_pay_amount	price	可选	11	买家实付金额，单位为元，两位小数。该金额代表该笔交易买家实际支付的金额，不包含商户折扣等金额	8.88
point_amount	price	可选	11	积分支付的金额，单位为元，两位小数。该金额代表该笔交易中用户使用积分支付的金额，比如集分宝或者支付宝实时优惠等	10
invoice_amount	price	可选	11	交易中用户支付的可开具发票的金额，单位为元，两位小数。该金额代表该笔交易中可以给用户开具发票的金额	12.11
send_pay_date	date	特殊可选	32	本次交易打款给卖家的时间	2014-11-27 15:45:57
receipt_amount	string	特殊可选	11	实收金额，单位为元，两位小数。该金额为本笔交易，商户账户能够实际收到的金额	15.25
store_id	string	特殊可选	32	商户门店编号	nj_s_001
terminal_id	string	特殊可选	32	商户机具终端编号	nj_t_001
fund_bill_list	tradefundbill[]	必选		交易支付使用的资金渠道。只有在签约中指定需要返回资金明细，或者入参的query_options中指定时才返回该字段信息。
store_name	string	特殊可选	512	请求交易支付中的商户店铺的名称	证大五道口店
buyer_user_id	string	必选	16	买家在支付宝的用户id 新商户建议使用buyer_open_id替代该字段。对于新商户，buyer_user_id字段未来计划逐步回收，存量商户可继续使用。如使用buyer_open_id，请确认应用-开发配置-openid配置管理已启用。无该配置项，可查看openid配置申请。	2088101117955611
buyer_open_id	string	特殊可选	128	买家支付宝用户唯一标识详情可查看 openid简介	01501o8f93i3njagb1jg4onxtxv25dcn3gec3uggnc4cju0
discount_amount	string	特殊可选	11	平台优惠金额	88.88
ext_infos	string	特殊可选	1024	交易额外信息，特殊场景下与支付宝约定返回。 json格式。	{"action":"cancel"}
buyer_user_type	string	特殊可选	18	买家用户类型。corporate:企业用户；private:个人用户。枚举值企业用户: corporate 个人用户: private	private
mdiscount_amount	string	特殊可选	11	商家优惠金额	88.88

响应示例

正常示例

异常示例

{
	"trade_no":"2013112011001004330000121536",
	"out_trade_no":"6823789339978248",
	"buyer_logon_id":"159****5620",
	"trade_status":"trade_closed",
	"total_amount":"88.88",
	"buyer_pay_amount":"8.88",
	"point_amount":"10",
	"invoice_amount":"12.11",
	"send_pay_date":"2014-11-27 15:45:57",
	"receipt_amount":"15.25",
	"store_id":"nj_s_001",
	"terminal_id":"nj_t_001",
	"fund_bill_list":[
		{
			"fund_channel":"alipayaccount",
			"amount":"10",
			"real_amount":"11.21"
		}
	],
	"store_name":"证大五道口店",
	"buyer_user_id":"2088101117955611",
	"buyer_open_id":"01501o8f93i3njagb1jg4onxtxv25dcn3gec3uggnc4cju0",
	"discount_amount":"88.88",
	"ext_infos":"{\"action\":\"cancel\"}",
	"buyer_user_type":"private",
	"mdiscount_amount":"88.88"
}

说明：本示例仅供参考。

公共错误码

业务错误码

状态码	错误码	错误描述	凯发app官方网站的解决方案
400	acq.invalid_parameter	参数无效	检查请求参数，修改后重新发起请求
400	acq.system_error	系统错误	重新发起请求
400	acq.trade_not_exist	查询的交易不存在	检查传入的交易号是否正确，修改后重新发起请求

设置阅读模式

接口说明

公共请求参数

业务请求参数

公共响应参数

业务响应参数

公共错误码

业务错误码

相关问题