交易查询接口（条码支付）

2021-06-15 05:56

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

网关URL

环境

HTTPS请求地址

生产环境

备份：https://intlmapi.alipay.com/gateway.do

测试环境

https://mapi.alipaydev.com/gateway.do

注意：
如果使用POST方法，请在请求URL中传入_input_charset。例如： https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

请求参数

参数描述

基本参数

service

String 不可空

接口名

示例：alipay.acquire.overseas.query

partner

String(16) 不可空

支付宝分配的用于标识支付宝帐户的合作伙伴ID。合作伙伴ID是2088开头的16位数字。

示例：2088*********662

_input_charset

String

请求数据的编码集，支持UTF-8。

示例：UTF-8

sign

String 不可空

签名值

示例：c8il4epm90wyn768fijgqhy8tay37gqa

sign_type

String 不可空

签名类型，支持 RSA，RSA2和MD5。请使用大写形式。

示例：MD5

业务参数

partner_trans_id

String(64) 不可空

原支付请求中合作伙伴的交易号

示例：2010121000000002

alipay_trans_id

String(64)

支付宝为商户请求分配的支付宝交易号。该字段与partner和partner_trans_id形成映射关系。

示例：201311221703338463

返回参数

参数描述

is_success

String(1) 不可空

用于展示请求是否成功，值为T表示成功，值为F表示失败。

注意：成功的请求并不意味着业务被接受并成功完成处理

示例：T

sign_type

String 不可空

签名类型。支持RSA，RSA2和MD5。请使用大写形式。

示例：MD5

sign

String(32) 不可空

签名值

示例：59c7275cf3c82f038b7c0076f9888926

result_code

String(32) 不可空

请求处理结果。SUCCESS代表处理成功， FAIL代表处理失败。

示例：SUCCESS

error

String(48)

请求失败时返回的错误代码，用于描述请求失败的原因。有关详细信息，参见本文档中的错误码。

示例：TRANS_NOT_FOUND

alipay_trans_status

String(32)

交易状态。详见交易状态。

示例：WAIT_BUYER_PAY

alipay_buyer_login_id

String(20)

买家支付宝账号。可用电子邮箱地址或手机号。实际值已脱敏。

示例：caoxxx@126.com or 186xxx22156

alipay_buyer_user_id

String(16) 不可空

支付宝账号唯一ID，2088开头的16位数字。

示例：2088102130896433

partner_trans_id

String(64) 不可空

与请求内的partner_trans_id一致

示例：201311221000000002

alipay_trans_id

String(64)

支付宝为商户请求分配的支付宝交易号。该字段与partner和partner_trans_id形成映射关系。

示例：201311221703338463

alipay_pay_time

String(16)

订单支付时间，格式为yyyyMMddHHmmss。

示例：201311212323

currency

String(8) 不可空

交易结算币种

示例：USD

trans_amount

Number(11,2) 不可空

以结算币种表示的订单金额。取值范围0.01-100000000.00，保留小数点后两位。但当币种为JPY时，使用整数值。

示例：39.25

exchange_rate

Number(8,6)

支付请求中的外币与人民币之间的汇率。汇率换算在支付宝交易订单创建时发生。

示例：6.0939

trans_amount_cny

Number(9,2)

以人民币表示的订单金额，即买家实际支付的金额。

示例：239.19

m_discount_forex_amount

Number(9,2)

如果交易中使用了优惠券/代金券，此参数会返回结算币种对应的核销金额，否则，无返回金额。

示例：2.19

forex_total_fee

Number(9,2)

以结算币种表示的订单金额

注意：该字段仅适用于部分支付宝产品。

示例：42.19

trans_forex_rate

Number(8,6)

标价币种和结算币种间的汇率

注意：该字段仅适用于部分支付宝产品。

示例：6.0939

支付宝网关拒绝的参数：

参数描述

is_success

String(1) 不可空

用于展示请求是否成功，值为T表示成功，值为F表示失败。

注意：成功的请求并不意味着业务被接受并成功完成处理。

示例：F

sign_type

String 不可空

签名类型。支持RSA，RSA2和MD5。请使用大写形式。

示例：MD5

sign

String(32) 不可空

签名值

示例：59c7275cf3c82f038b7c0076f9888926

detail_error_code

String(48)

详细错误码，描述响应码的返回原因。当返回的result_code为SUCCESS时，该字段不会被返回。

示例：TRANS_NOT_FOUND

detail_error_des

String(48)

详细错误码的描述。当返回的result_code为SUCCESS时，该字段不会被返回。

错误码

错误码	描述
SYSTEM_ERROR	支付宝系统错误。解决方案：输入正确的参数，并且重新发送请求。具体请参见案例 2。
ILLEGAL_SIGN	签名不合法。解决方案：详见数字签名。
INVALID_PARAMETER	参数值错误。解决方案：根据具体接口说明检查每个请求参数。
ILLEGAL_ARGUMENT	参数名错误。解决方案：根据具体接口说明检查每个请求参数。如果此错误仍然存在，联系支付宝技术支持。
ILLEGAL_PARTNER	商户ID不正确。解决方案：确保partner的参数值与支付宝分配的值一致。如果此错误仍然存在，联系支付宝技术支持。
ILLEGAL_EXTERFACE	接口配置错误。解决方案：确保service参数的值同接口说明中的值一致。如果此错误仍然存在，联系支付宝技术支持。
ILLEGAL_PARTNER_EXTERFACE	商户无权使用该接口解决方案：确保您与支付宝的协议已签订。如果需要，请联系支付宝技术支持。
ILLEGAL_SIGN_TYPE	签名类型不正确解决方案：确保sign_type值为 MD5、RSA 或 RSA2。如果此错误仍然存在，请联系支付宝技术支持。
HAS_NO_PRIVILEGE	无权访问。解决方案：请联系支付宝技术支持。
REASON_TRADE_BEEN_FREEZEN	由于安全原因，交易被冻结。解决方案：请联系支付宝技术支持。
TRADE_NOT_EXIST	根据partner_trans_id值无法找到对应交易解决方案：确保partner_trans_id参数值正确。如果此错误仍然存在，请联系支付宝技术支持。

结果处理

案例1：当接口调用因网络问题或请求超时而失败，并且支付宝无响应时，执行以下操作：

1. 检查您的网络是否连接支付宝网关。使用正确的参数重新发送请求，直到收到支付宝响应。重试规则为每三秒钟一次，最多五次。

2. 如果仍未收到支付宝响应，请联系支付宝国际技术支持。

案例2：如果收到支付宝响应，且以下结果之一被返回：

is_success=F，error=SYSTEM_ERROR
is_success=T，result_code=FAIL，detail_error_code=SYSTEM_ERROR

执行以下操作：

使用正确的参数重新发送请求（每三秒一次，最多五次），直到支付宝响应。
如果依然无法得到响应，请联系支付宝技术支持。

案例3：如果收到支付宝响应，且is_success=T，result_code=SUCCESS，交易查询成功。

案例4：如果收到支付宝响应，且以下结果之一被返回：

is_success=F，error=SYSTEM_ERROR
is_success=T，result_code=FAIL，detail_error_code=SYSTEM_ERROR

交易查询失败。参考具体错误码以了解更多信息。

伪代码

copy
try{
  if(isCase3){ //CASE 3
    doSuccessProcess();
  }
  else if(isCase4){ //CASE 4
    doFailureProcess();
  }
  else{ //CASE 2
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }

}catch (Exception ex){ // CASE 1
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }
}

示例

请求示例

指定parter_trans_id字段的请求示例

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.query&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&partner_trans_id=out_trade_no_20190904_151744&sign=23473d26d38f2a9b877315a00542f833

指定alipay_trans_id字段的请求示例

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.query&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&alipay_trans_id=2019090422001436530558497325&sign=2bd963c953916b78c2c141f8faea4124

返回示例

请求成功，且查询业务成功：

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner_trans_id">out_trade_no_20190904_151744</param>
        <param name="partner">208xxxxxxxxx8155</param>
        <param name="_input_charset">UTF-8</param>
        <param name="service">alipay.acquire.overseas.query</param>
        <param name="sign">23473d26d38f2a9b877315a00542f833</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <alipay_buyer_login_id>186****9365</alipay_buyer_login_id>
            <alipay_buyer_user_id>208xxxxxxxxx6535</alipay_buyer_user_id>
            <alipay_pay_time>201xxxxxxx1805</alipay_pay_time>
            <alipay_trans_id>201xxxxxxxxxxxxxxxxxxxxxxx7325</alipay_trans_id>
            <alipay_trans_status>TRADE_CLOSED</alipay_trans_status>
            <currency>USD</currency>
            <exchange_rate>7.18041000</exchange_rate>
            <forex_total_fee>0.01</forex_total_fee>
            <out_trade_no>out_trade_no_20190904_151744</out_trade_no>
            <partner_trans_id>out_trade_no_20190904_151744</partner_trans_id>
            <result_code>SUCCESS</result_code>
            <trans_amount>0.01</trans_amount>
            <trans_amount_cny>0.07</trans_amount_cny>
            <trans_forex_rate>1</trans_forex_rate>
        </alipay>
    </response>
    <sign>787e2affe713f470f7db016cede91c04</sign>
    <sign_type>MD5</sign_type>
</alipay>

请求失败：

PID无权调用此接口

copy
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_PARTNER_EXTERFACE</error>
</alipay>

PID有权调用此接口，但签名错误

copy
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>

PID有权调用此接口，签名也正确，但找不到交易

copy
<alipay>
<is_success>T</is_success>
<request>
<param name="partner_trans_id">TRADE_20210611164347</param>
<param name="partner">2088************</param>
<param name="_input_charset">UTF-8</param>
<param name="service">alipay.acquire.overseas.query</param>
<param name="sign">*</param>
<param name="sign_type">MD5</param>
</request>
<response>
<alipay>
<detail_error_code>TRADE_NOT_EXIST</detail_error_code>
<detail_error_des>交易不存在</detail_error_des>
<out_trade_no>TRADE_20210611164347</out_trade_no>
<partner_trans_id>TRADE_20210611164347</partner_trans_id>
<result_code>FAIL</result_code>
</alipay>
</response>
<sign>*</sign>
<sign_type>MD5</sign_type>
</alipay>