Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

退款（线下商店）

POST /v1/payments/refund

使用此接口发起对成功支付的同步或异步退款。 

结构

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

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

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

入参

refundRequestId String  REQUIRED

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

更多信息：

  • 此为幂等字段。商户使用 refundRequestId 字段来实施幂等性控制。对于那些使用相同的 refundRequestId 发起，并且已达到最终状态（成功S或失败F）的退款请求，应当返回相同的结果。
  • 最大长度：64 字符

paymentId String  REQUIRED

Antom 分配给待退款的原始支付的专属 ID。

更多信息：

  • 最大长度：64 字符

referenceRefundId String  

直接向客户提供服务或商品的商家为识别退款而分配的退款 ID。

更多信息：

  • 最大长度：64 字符

refundAmount Amount  REQUIRED

商家发起的退款金额。

Show child parameters

refundReason String  

退款原因。

更多信息：

  • 最大长度：256 字符

出参

result Result  REQUIRED

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

Show child parameters

refundRequestId String  

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

更多信息：

  • 最大长度：64 字符

refundId String  

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

更多信息：

  • 最大长度：64 字符

paymentId String  

Antom 分配给待退款的原始支付的专属 ID。

更多信息：

  • 最大长度：64 字符

refundAmount Amount  

退款执行者为此次退款收取的退款金额。

Show child parameters

refundTime Datetime  

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

更多信息：

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

grossSettlementAmount Amount  

结算总额，等于交易金额乘以 settlementQuote 的值。

注意：当结算货币与交易货币相同时，此字段为空。

Show child parameters

settlementQuote Quote  

交易时的结算货币与交易货币之间的汇率，仅在锁定汇率的情况下提供。

注意：当结算货币与交易货币相同时，此字段为空。

Show child parameters
API Explorer

请求

URL

请求体

响应

响应体

更多信息 

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

  • refundRequestId：

退款可以是全额退款或是部分退款。只要总退款金额不超过原交易金额，一次交易可以有多次退款。如果超出了退款窗口期，退款请求将会被拒绝。在遇到超时或返回的 resultStatus 为U时，可以使用相同的 refundRequestId 重试退款。

  • refundId:

此参数可用于退款查询。 

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。请参阅以下列表以了解详情：

  • 如果 result.resultStatus 的值为 S，对于同步退款，意味着退款成功。对于异步退款，意味着退款请求已成功处理，商户可以调用 退款结果查询（线下商店）接口查询退款结果。
  • 如果 result.resultStatus 的值为 F，意味着退款失败。通常是因为退款超出了退款窗口时间（result.resultCode= FREFUND_WINDOW_EXCEED）。如果仍需处理退款，请联系相关人员。
  • 如果 result.resultStatus 的值为 U，结果未知。可能由于系统或网络问题导致处理失败。商户可以使用相同的 refundRequestId 进行重试。

结果码

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

退款成功，无需进一步操作。

ACCESS_DENIEDF访问被拒绝。

如需详细原因，请联系 Antom 技术支持。  

CLIENT_INVALIDF客户端无效。

请检查 clientId 是否正确。

CURRENCY_NOT_SUPPORT F币种不支持。

请使用合同中约定的币种。

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

请检查媒体类型是否正确。

MULTIPLE_REFUNDS_NOT_SUPPORTEDF不支持多次退款。

检查是否存在多个退款。

MERCHANT_BALANCE_NOT_ENOUGHF商户余额不足。

在商家余额充足后再次调用接口。重试时需要更改 refundRequestId 字段。

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

请检查 HTTP 方法是否正确。

ORDER_IS_CANCELEDF交易已取消。

交易已取消，无法退款。

ORDER_NOT_EXISTF订单不存在。

请检查 paymentId 是否正确。

ORDER_STATUS_INVALIDF订单状态无效。

检查订单状态。

REFUND_AMOUNT_EXCEEDF退款总额超过了支付金额。

确认退款总额是否超过支付金额。

REFUND_WINDOW_EXCEEDF退款日期超过了合同中约定的退款期限。

确认退款日期是否超过可退款期限。

REPEAT_REQ_INCONSISTENTF重复请求不一致。

使用对应的 refundRequestId 重新发起退款请求。