Antom, leading provider of tailored payment solutions
Contact Us
Log In

inquiryRefund（线下商店）

POST /v1/payments/inquiryRefund

使用此接口查询先前提交的退款请求的信息。

 

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

注意：将每个参数（除数组外）的数据类型设置为字符串，即参数的值必须使用英文双引号（" "）包裹起来。例如：

  • 如果参数的数据类型为整数属性，且其值为 20，设置为 "20"。
  • 如果参数的数据类型为布尔属性，且其值为 true，设置为 "true"。


入参

refundRequestId String  

商户为识别退款请求分配的专属 ID。refundRequestId 和 refundId 不能都为null。不支持特殊字符。如果同时指定了refundRequestId 和 refundId，则 refundId 优先。

更多信息：

  • 最大长度：64 字符

refundId String  

Antom 为识别退款而分配的退款 ID。refundRequestId 和refundId 不能同时为null。refundId 与 refundRequestId 之间存在一对一对应关系。如果同时指定了 refundRequestId 和 refundId，则 refundId 优先。

更多信息：

  • 最大长度：64 字符

出参

result Result  REQUIRED

请求结果包含状态和错误代码等信息。

注意：此字段不表示退款结果。此字段仅指示查询退款接口是否调用成功。 

refundId String  

Antom 为识别退款而分配的退款 ID。refundId 与 refundRequestId 之间存在一对一对应关系。

注意: 当找不到退款记录，或 result.resultStatus 为F或U时，此字段为null。

更多信息：

  • 最大长度：64 字符

refundRequestId String  

商家为识别退款请求所分配的专属 ID。

注意: 当退款记录未找到，或 result.resultStatus 为F/U时，此字段为null。

更多信息：

  • 最大长度：64 字符

refundAmount Amount  

由商家发起的退款金额。

注意: 当退款记录未找到，或 result.resultStatus 为F/U时，此字段为null。

refundTime Datetime  

退款在 Antom （而非 Antom 移动支付提供商，即 Alipay+ 支付方式）成功完成的日期和时间。

注意：当 refundStatus 的值为SUECCESS时，返回此字段。

更多信息：

  • 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

refundStatus String  

指示了 Antom （而非 Antom 移动支付提供商，即 Alipay+ 支付方式）退款的最终状态。有效值包括：

  • SUCCESS: 表示退款成功。
  • PROCESSING: 表示退款仍在处理中。
  • FAIL: 表示退款失败。

注意: 当找不到退款记录，或者 result.resultStatus 为F或U时，此字段为null。

更多信息：

  • 最大长度：16 字符

grossSettlementAmount Amount  

退款结算金额，等于退款金额乘以 settlementQuote 的值。当货币兑换预先确定且交易时汇率被锁定时，此字段将返回。

settlementQuote Quote  

结算货币与支付货币之间的汇率。当返回 grossSettlementAmount 时，此字段会被返回。

API Explorer

请求

URL

Method
POST
json
{
  "refundId": "2021080419401080130018866020092XXXX",
  "refundRequestId": "amsdemorefund_zhangyikai_zyk_20210804_165236_931"
}

响应

json
{
  "refundAmount": {
    "currency": "HKD",
    "value": "10000"
  },
  "refundId": "2021080419401080130018866020092XXXX",
  "refundRequestId": "amsdemorefund_zhangyikai_zyk_20210804_165236_931",
  "refundStatus": "SUCCESS",
  "refundTime": "2021-08-04T01:52:37-07:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

更多信息

本节提供了关于关键参数的更多详细信息。请参阅以下列表：

  • refundTime：

退款成功执行的时间，即 Antom 在退款达到最终成功状态的时间，不包括 Antom 移动支付供应商（Alipay+ 支付方式）的情况。

  • refundStatus：

此字段仅标识 Antom 端的退款状态，不包括Alipay+支付方式 端的状态。  

  • refundId：

退款 ID。对于轮询相同的退款，此字段必须唯一。对于轮询不同的退款，此字段必须不同。此字段可用于退款查询。

  • refundRequestId 或 refundId:
    • 调用 退款（线下商店） 接口后返回成功结果，商家可以使用 refundId 或 refundRequestId 查询原始退款结果。
    • 调用 退款（线下商店） 接口后返回未知异常或超时，商家只能使用 refundRequestId 查询原始退款结果。
    • 如果商家同时使用 refundId 和 refundRequestId 调用此接口，Antom 只会使用 refundId 进行查询，忽略请求中的 refundRequestId。
    • 如果商家使用正确的 refundId 或 refundRequestId 调用此接口，但该退款不属于商家，将返回错误代码ORDER_NOT_EXIST。

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。详细信息请参见以下列表：

  • 如果 result.resultStatus 的值为S，则退款查询成功。
  • 如果 result.resultStatus 的值为F，则退款查询失败。
  • 如果 result.resultStatus 的值为U，请求结果未知。请使用相同的请求参数重试查询请求。

结果码

结果码值结果码信息行动建议
SUCCESSS成功

接口调用成功，无需进一步操作。

ORDER_NOT_EXISTF退款订单不存在。

15 秒后再次调用接口。如果三次重试后仍未返回结果，说明订单未创建。

CLIENT_INVALIDF客户端无效。

检查 clientId 是否正确。

METHOD_NOT_SUPPORTEDF服务器不支持请求的 HTTP 方法。

检查 HTTP 方法是否正确。

MEDIA_TYPE_NOT_ACCEPTABLEF服务器不支持客户端可接受的媒体类型。

检查媒体类型是否正确。