退款查询

2024-08-08 04:20

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 字符

merchantAccountId String

用于识别商户账户的商户 ID。

注意：当你在多个地点使用同一个客户端 ID 时，需要指定此参数。

更多信息：

最大长度：32 字符

出参

result Result REQUIRED

请求调用结果的信息。

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

Show child parameters

refundId String

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

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：64 字符

refundRequestId String

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

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：64 字符

refundAmount Amount

由商家发起的退款金额。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

Show child parameters

refundTime Datetime

Antom 确认成功退款的日期和时间。

注意：此字段在退款成功（refundStatus 的值为SUCCESS）时返回。

更多信息：

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

refundStatus String

表示 Antom 退款的最终状态。有效值包括：

SUCCESS：退款成功。
PROCESSING：退款处理中。
FAIL：退款失败。

注意：
此字段在接口调用成功（result.resultStatus 的值为S）时返回。
此字段仅标识 Antom 端的退款状态，不包括 Alipay+ 支付方式端的状态。

更多信息：

最大长度：16 字符

grossSettlementAmount Amount

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

Show child parameters

settlementQuote Quote

结算货币与交易货币之间的汇率。

注意：当返回 grossSettlementAmount 时，此字段会返回。

Show child parameters

API Explorer

示例代码沙箱运行

请求

URL

请求体

响应

Case

Success

响应体

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。详细信息如下：

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

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	接口调用成功。从 refundStatus 获取退款状态。
ACCESS_DENIED	F	访问被拒绝。	详细原因请咨询 Antom 技术支持。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
ORDER_NOT_EXIST	F	订单不存在。	请在 15 秒后再次调用接口。如果尝试三次后仍没有返回结果，说明订单未创建成功。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
SYSTEM_ERROR	F	发生系统错误。	获取 Antom 技术支持前请勿重试。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过限制。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。

退款结果代码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	退款成功，无需进一步操作。
ACCESS_DENIED	F	访问被拒绝。	请联系 Antom 技术支持以获取详细原因。
API_INVALID	F	接口名称或接口调用格式使用不正确。	检查发送请求时，接口名称、HTTP 方法或请求格式是否正确。
CURRENCY_NOT_SUPPORT	F	货币不受支持。	详细原因请咨询 Antom 技术支持。
INVALID_MERCHANT_STATUS	F	由于存在限制，商户状态异常。	详细原因请咨询 Antom 技术支持。
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
MERCHANT_BALANCE_NOT_ENOUGH	F	商户余额不足。	当商家账户余额充足后，再次调用接口。重试时需要修改 refundRequestId 字段。
MULTIPLE_REFUNDS_NOT_SUPPORTED	F	由于合同限制，不支持多次退款。	检查是否存在多个退款。不要再调用退款接口。每个退款请求仅调用一次接口。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
ORDER_IS_CLOSED	F	您发起的请求具有与已关闭交易相同的 paymentRequestId。	使用新的 paymentRequestId 重新发起退款。
ORDER_NOT_EXIST	F	订单不存在。	检查 paymentId 是否正确。如果正确，请联系 Antom 技术支持了解具体原因。
ORDER_STATUS_INVALID	F	订单状态无效。交易正在进行中或交易失败。	检查订单状态并采取相应操作。如果交易正在处理中，请等待。如果交易失败，不要发起退款。对于具体原因，请联系 Antom 技术支持。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
REFUND_AMOUNT_EXCEED	F	退款总额超过了支付金额。	确认退款总额是否超过支付金额。创建一个金额小于或等于支付金额的新退款，或联系 Antom 技术支持。
REFUND_WINDOW_EXCEED	F	退款日期超过了合同约定的退款期限。	确认退款日期是否超过可退款期限。在合同中查看可退款期限，或联系 Antom 技术支持获取具体可退款期限。
REPEAT_REQ_INCONSISTENT	F	金额或货币与先前请求不同。	确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起退款。
RISK_REJECT	F	因风险控制，请求被拒绝。	提示用户请求被拒绝，因为风险控制失败。
SYSTEM_ERROR	F	发生系统错误。	获取 Antom 技术支持前请勿重试。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过限制。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。