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

支付

当面付

app 支付

接入指南

api 列表

交易

账单

接口说明

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

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

请求方式：post

path指该参数为路径参数

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

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

通用场景

用于交易创建后，用户在一定时间内未进行支付，可调用该接口直接将未付款的交易进行关闭。

公共请求参数

参数	类型	是否必选	最大长度	描述	示例值
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参数

以下参数二选一传入必选

trade_nostring(64)

【描述】该交易在支付宝系统中的交易流水号。最短 16 位，最长 64 位。和out_trade_no不能同时为空，如果同时传了 out_trade_no和 trade_no，则以 trade_no为准。

【示例值】2013112611001004680073956707

out_trade_nostring(64)

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

【示例值】hz0120131127001

notify_url｜通知地址可选string(1024)

【描述】支付宝服务器主动通知商户服务器里指定的页面http/https路径。在body参数中传递

【示例值】http://api.test.alipay.net/atinterface/receive_notify.htm

operator_id可选string(28)

【描述】商家操作员编号 id，由商家自定义。

【示例值】yx01

参数	类型	是否必选	最大长度	描述	示例值
notify_url	string	可选	1024	支付宝服务器主动通知商户服务器里指定的页面http/https路径。在body参数中传递	http://api.test.alipay.net/atinterface/receive_notify.htm
trade_no	string	二选一	64	该交易在支付宝系统中的交易流水号。最短 16 位，最长 64 位。和out_trade_no不能同时为空，如果同时传了 out_trade_no和 trade_no，则以 trade_no为准。	2013112611001004680073956707
out_trade_no	string	64	订单支付时传入的商户订单号,和支付宝交易号不能同时为空。 trade_no,out_trade_no如果同时存在优先取trade_no	hz0120131127001
operator_id	string	可选	28	商家操作员编号 id，由商家自定义。	yx01

常见请求示例

默认示例

curljavac#php

curl -x post \
 https://openapi.alipay.com/v3/alipay/trade/close \
 -h "authorization: alipay-sha256withrsa app_id=${appid},timestamp=${now},nonce=${uuid},expired_seconds=600,sign=${sign}" \
 -h "alipay-request-id: ${requestid}" \
 -h "content-type: application/json" \
 -d '{
	"notify_url":"http://api.test.alipay.net/atinterface/receive_notify.htm",
	"trade_no":"2013112611001004680073956707",
	"out_trade_no":"hz0120131127001",
	"operator_id":"yx01"
}'

说明：本示例仅供参考。

公共响应参数

参数	类型	是否必选	最大长度	描述	示例值
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)

【描述】支付宝交易号

【示例值】2013112111001004500000675971

out_trade_no特殊可选string(64)

【描述】创建交易传入的商户订单号

【示例值】yx_001

参数	类型	是否必选	最大长度	描述	示例值
trade_no	string	特殊可选	64	支付宝交易号	2013112111001004500000675971
out_trade_no	string	特殊可选	64	创建交易传入的商户订单号	yx_001

响应示例

正常示例

异常示例

{
	"trade_no":"2013112111001004500000675971",
	"out_trade_no":"yx_001"
}

说明：本示例仅供参考。

公共错误码

业务错误码

状态码	错误码	错误描述	凯发app官方网站的解决方案
400	acq.invalid_parameter	参数无效	检查请求参数，修改后重新发起请求
400	acq.reason_illegal_status	交易状态异常	确认交易状态，非待支付状态下不支持关单操作
400	acq.reason_trade_status_invalid	交易状态异常	确认交易状态，非待支付状态下不支持关单操作
400	acq.system_error	系统异常	重新发起请求
400	acq.trade_not_exist	交易不存在	检查传入的交易号和外部订单号是否正确，修改后再重新发起
400	acq.trade_status_error	交易状态不合法	检查当前交易的状态是不是等待买家付款，只有等待买家付款状态下才能发起交易关闭。

关联异步通知

触发通知类型

通知类型	描述	默认开启
tradestatus.trade_closed	交易关闭	1
tradestatus.trade_success	交易成功	0

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=rsa2&sign=wco t3d8kg71dtlkwn7r9pzuoxeabjwp8/fousxcuskxsovyxbpsaidpryscjhcjmaglncjokjqlj28/asl93jotw39fx6i07lxhnbpknezalwmvpdnqui01hzszf9v1i6ggzjbiad5lg8bzttxzoj87ub2i9guj3nr/nuc9vey=&trade_no=null&app_id=null&out_trade_no=null&out_biz_no=null&buyer_logon_id=null&seller_id=null&seller_email=null&trade_status=null&total_amount=null&refund_fee=null&subject=null&body=null&gmt_create=null&gmt_payment=null&gmt_refund=null&gmt_close=null&fund_bill_list=null&receipt_amount=null&invoice_amount=null&buyer_pay_amount=null&point_amount=null&buyer_id=null

设置阅读模式