Antom, leading provider of tailored payment solutions

refund

POST /v1/payments/refund
使用此接口对成功的支付发起退款。退款可以是全额或部分退款。只要总退款金额小于或等于原始交易金额,一个交易可以有多个退款。如果退款请求超出了合同中确定的退款窗口,退款请求将被拒绝。
注意: 如果退款请求超时或返回的 resultStatus 为 U,可以使用相同的 refundRequestId 字段重试退款。refundRequestId 字段设计为幂等的。 

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息,有关报文头的结构信息,请参阅:
注意:将每个参数(除数组外)的数据类型设置为字符串,即参数的值必须使用英文双引号(" ")包裹起来。例如:
  • 如果参数的数据类型为整数属性,且其值为 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

商家发起的退款金额。

refundReason String  

退款原因。
注意:如果您希望向用户和支付方式提供退款原因,请指定此字段。

更多信息:

  • 最大长度:256 字符

refundNotifyUrl String  

您接收退款结果通知的地址。该地址必须在请求中指定或在 Antom Dashboard 中设置。
注意:如果您希望接收退款结果的异步通知,请指定此字段。如果请求和 Antom Dashboard 中都指定了退款通知地址,则请求中指定的值优先。

更多信息:

  • 最大长度:1024 字符

captureId String  

Antom 为识别请款分配的专属 ID。
注意:当存在多笔请款时,请指定此参数进行退款操作。

更多信息:

  • 最大长度:64 字符

metadata String  

用于提交元数据,包括特殊用例信息。
当您需要添加元数据时指定此参数。

更多信息:

  • 最大长度:2048 字符

出参

result Result  REQUIRED

指示此接口是否调用成功。如果接口调用成功,退款也成功。

refundRequestId String  

商家为识别退款请求而分配的特定 ID。
注意:此字段在退款成功(result.resultStatus 的值为 S)时返回。

更多信息:

  • 最大长度:64 字符

refundId String  

Antom 为识别退款而分配的退款 ID。refundId 与 refundRequestId 之间存在一一对应关系。
注意:此字段在退款成功(result.resultStatus 的值为 S)时返回。

更多信息:

  • 最大长度:64 字符

paymentId String  

Antom 为识别原始支付退款而分配的特定 ID。
注意:此字段在退款成功(result.resultStatus 的值为 S)时返回。

更多信息:

  • 最大长度:64 字符

acquirerReferenceNo String  

非 Antom 收单机构为识别交易而分配的交易 ID。

更多信息:

  • 最大长度:64 字符

refundAmount Amount  

退款时付款人的退款金额。
注意:此字段在退款成功(result.resultStatus 的值为 S)时返回。

refundTime Datetime  

退款成功、失败或未知状态的日期和时间。

更多信息:

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

grossSettlementAmount Amount  

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

settlementQuote Quote  

结算币种与交易币种之间的汇率。
注意:此字段在返回 grossSettlementAmount 时返回。
API Explorer

请求

URL
Method
POST
json
{
  "paymentId": "20241212194010800100188670211082739",
  "captureId": "20241212194010807000188670209694546",
  "refundReason": "amsdemorefund",
  "refundRequestId": "yuqian_refund_654ac17e-bc5e-4648-b9de-a18f0a74aa2a",
  "refundAmount": {
    "currency": "SGD",
    "value": "1000"
  }
}

响应

Case
json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "refundAmount": {
    "value": "100",
    "currency": "USD"
  },
  "refundTime": "2020-10-10T12:01:01+08:30",
  "paymentId": "20181129190741010007000000XXXX",
  "refundRequestId": "20181129190741020007000000XXXX",
  "refundId": "40181129190741020007000000XXXX"
}

结果处理逻辑

对于不同的请求结果,需要执行不同的操作。详情如下:
  • 如果 result.resultStatus 的值为S,退款成功。
  • 如果 result.resultStatus 的值为F,退款失败。失败原因是退款窗口已过期(result.resultCode = REFUND_WINDOW_EXCEED)。如果仍需处理退款,请联系 Antom 技术支持。
  • 如果 result.resultStatus 的值为U,结果未知。可能由于系统或网络问题导致处理失败。使用相同的 refundRequestId 重试,或使用 inquiryRefund 接口查询退款结果。

结果码

结果码值结果码信息行动建议
SUCCESSS成功
退款成功,无需进一步操作。
ACCESS_DENIEDF访问被拒绝。
请联系 Antom 技术支持以获取详细原因。
INVALID_APIF调用的接口无效或未激活。
请联系 Antom 技术支持来解决问题。
CURRENCY_NOT_SUPPORTF币种不受支持。
请联系 Antom 技术支持以获取详细原因。
INVALID_MERCHANT_STATUSF由于存在限制,商户状态异常。
请联系 Antom 技术支持以获取详细原因。
KEY_NOT_FOUNDF未找到 Antom 或商户的私钥或公钥。
检查私钥或公钥是否存在。如果不存在,请在 Antom Dashboard 中上传私钥。
MERCHANT_BALANCE_NOT_ENOUGHF商户余额不足。
在商户余额充足后再次调用接口。尝试再次退款时,需要更改 refundRequestId 字段。
MULTIPLE_REFUNDS_NOT_SUPPORTEDF由于合同限制,不支持多次退款。
检查是否存在多个退款。不要再调用退款接口。对于每个退款,仅调用一次接口。
NO_INTERFACE_DEFF接口未定义。
检查链接是否正确。请参考接口文档中的端点。
ORDER_IS_CLOSEDF您发起的请求具有与已关闭交易相同的 paymentRequestId。
使用新的 paymentRequestId 重新发起退款。
ORDER_NOT_EXISTF订单不存在。
检查 paymentId 是否正确。如果正确,请联系 Antom 技术支持以获取具体原因。
ORDER_STATUS_INVALIDF订单状态无效。交易正在进行中或交易失败。
检查订单状态并采取相应操作。如果交易正在处理中,请等待。如果交易失败,不要发起退款,请联系 Antom 技术支持以获取详细原因。
PARAM_ILLEGALF缺少必需的参数,或者存在非法参数。例如,非数字输入,无效的日期,或者参数的长度和类型错误。
检查并验证当前接口所需的请求字段(包括头字段和正文字段)是否正确传递并有效。
PROCESS_FAILF发生了常见的业务失败。
请勿重试。请联系 Antom 技术支持以获取详细原因。
REFUND_AMOUNT_EXCEEDF退款总额超过了支付金额或退款金额低于最小退款金额。
确认总退款金额是否超过支付金额或退款金额是否低于最小退款金额。使用小于等于支付金额且大于等于最小退款金额的金额创建新的退款,或联系 Antom 技术支持。
REFUND_WINDOW_EXCEEDF退款日期超过了合同约定的可退款期限。
确认退款日期是否超过可退款期限。在合同中检查可退款期限,或联系 Antom 技术支持获取具体的可退款期限。
REPEAT_REQ_INCONSISTENTF金额或币种与先前请求不同。
确保请求中的所有字段相同,或使用新的 paymentRequestId 重新发起退款。
SYSTEM_ERRORF发生了系统错误。
请勿重试。请联系 Antom 技术支持以获取详细原因。
REFUND_IN_PROCESSU退款正在处理中。
等待异步通知或调用 inquiryRefund 接口查询最终退款状态。请勿重试退款请求。 
REFUND_NOT_SUPPORTF该交易不支持退款。
检查交易状态和合同中的退款政策。如果交易成功且合同允许退款,请联系 Antom 技术支持。
REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过了限制。
再次调用接口以解决问题。如果未解决,请联系 Antom 技术支持。
PARTIAL_REFUND_NOT_SUPPORTEDF该交易不支持部分退款。
进行全额退款或与买家协商线下退款。  
PAYMENT_METHOD_NOT_SUPPORTEDF支付状态成功时,支付方式不支持取消或退款交易。
请勿重试。请联系 Antom 技术支持以获取详细原因。
ORDER_IS_CANCELEDF交易已取消。
交易已取消,无法退款。
REFUND_BY_TRANSACTION_TYPE_INCONSISTENTF因交易类型不一致,退款失败。
请立即停止本次退款,并检查后续退款请求是否与首笔退款保持相同的退款维度,即统一按 paymentId 或统一按 captureId 进行退款,修正后重发。
REFUND_AFTER_DISPUTE_NOT_SUPPORTEDF拒付后不允许退款。
拒付后无法发起退款,请等待拒付结果通知。
UNKNOWN_EXCEPTIONU由于未知原因,接口调用失败。
再次调用接口以解决问题。如果未解决,请联系 Antom 技术支持。