退款通知

2024-12-18 05:49

Antom 在退款处理完成时，使用此接口向商户发送退款结果。商户根据退款结果继续进行商户端的交易处理。

结构

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

注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

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

入参

notifyType String REQUIRED

退款状态通知的类型。有效值为：

REFUND_RESULT：表示是关于退款结果的通知。

result Result REQUIRED

退款结果的详细信息，如退款状态、结果代码和结果报文。

Show child parameters

refundStatus String REQUIRED

表示退款结果。有效值为：

SUCCESS: 退款成功。
FAIL: 退款失败。

refundRequestId String REQUIRED

商家为识别退款请求而分配的特定 ID。

更多信息：

最大长度：64 字符

refundId String REQUIRED

Antom 分配的用于识别退款的特定 ID。与 paymentId 和 paymentRequestId 之间存在一一对应关系。

更多信息：

最大长度：64 字符

refundAmount Amount REQUIRED

商家发起的退款金额。

Show child parameters

refundTime Datetime

退款成功或失败的最终状态的日期和时间。

注意：此字段在退款成功（result.resultStatus 的值为S）时返回。

grossSettlementAmount Amount

退款结算金额，等于退款金额乘以 settlementQuote 的值。

注意：当币种兑换预先确定且交易时汇率被锁定时，此字段返回。

Show child parameters

settlementQuote Quote

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

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

Show child parameters

出参

result Result REQUIRED

发送给 Antom 以确认已收到通知的固定值。

Show child parameters

API Explorer

请求

请求体

响应

响应体

结果处理逻辑

在收到 Antom 通知后，发送以下固定值的消息给 Antom，以确认收到 Antom 的通知：

Sample Code

如果由于操作问题或网络问题没有将此类消息返回给 Antom，Antom 会反复发送通知，直到商家返回所需消息。首次通知发送后的 24 小时内会进行重试。通知将重试最多八次，间隔为 0 秒, 2 分钟, 10 分钟, 10 分钟, 1 小时, 2 小时, 6 小时, 和 15 小时。

注意：沙箱环境中，如果您没有按照固定格式返回信息，Antom 将不会重新发送异步通知给您。

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	退款成功，无需进一步操作。
ACCESS_DENIED	F	访问被拒绝。	请联系 Antom 技术支持以获取详细原因。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持来解决问题。
CLIENT_INVALID	F	客户端 ID 无效。Antom 对客户端 ID 有限制。	请检查客户端 ID 是否正确，或联系 Antom 技术支持获取详细原因。
CURRENCY_NOT_SUPPORT	F	货币不受支持。	请联系 Antom 技术支持以获取详细原因。
INVALID_CONTRACT	F	合同中的参数值与当前交易不符。	检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 Antom 技术支持以解决问题。
INVALID_MERCHANT_STATUS	F	由于存在限制，商户状态异常。	请联系 Antom 技术支持以获取详细原因。
INVALID_SIGNATURE	F	签名验证失败。用于签署请求的私钥与 Antom Dashboard 的公钥不匹配。	检查用于签署请求的私钥是否与 Antom Dashboard 的公钥匹配。以下签名参考信息很有用：请求头中的签名字段如何生成签名
KEY_NOT_FOUND	F	未找到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom Dashboard 中上传私钥。
MEDIA_TYPE_NOT_ACCEPTABLE	F	服务器不支持客户端可接受的媒体类型。	请检查媒体类型是否正确，并使用 Antom 接受的媒体类型。
MERCHANT_BALANCE_NOT_ENOUGH	F	商户余额不足。	在商户余额充足后再次调用接口。尝试再次退款时，需要更改 refundRequestId 字段。
MERCHANT_NOT_REGISTERED	F	商户未注册。	请使用注册接口注册商户。如果调用注册接口失败，请联系 Antom 技术支持。
METHOD_NOT_SUPPORTED	F	服务器不支持请求的 HTTP 方法。仅支持 POST 方法。	确保 HTTP 方法为`POST`。
MULTIPLE_REFUNDS_NOT_SUPPORTED	F	由于合同限制，不支持多次退款。	检查是否存在多个退款。不要再调用退款接口。对于每个退款，仅调用一次接口。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
ORDER_IS_CLOSED	F	交易已关闭，无法再次支付。	使用新的 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 技术支持前请勿重试。
REFUND_IN_PROCESS	U	退款正在处理中。	等待异步通知或调用退款查询接口来查询最终的退款状态。请勿重试退款请求。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过了限制。	再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。