Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

退款

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

商家发起的退款金额。

Show child parameters

refundReason String  

退款原因。

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

更多信息：

  • 最大长度：256 字符

refundNotifyUrl String  

于接收退款结果通知的链接。该链接必须在请求中指定或在 Antom Dashboard 中设置。

注意：如果您希望接收退款结果的异步通知，请指定此字段。如果请求和 Antom Dashboard 中都指定了退款通知链接，则请求中指定的值优先。

更多信息：

  • 最大长度：1024 字符

出参

result Result  REQUIRED

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

Show child parameters

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）时返回。

Show child parameters

refundTime Datetime  

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

更多信息：

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

grossSettlementAmount Amount  

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

Show child parameters

settlementQuote Quote  

结算货币与交易货币之间的汇率。此字段在返回 grossSettlementAmount 时返回。

Show child parameters
API Explorer
示例代码沙箱运行

请求

URL

请求体

响应

Case
Success
响应体

结果处理逻辑

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

  • 如果 result.resultStatus 的值为S，退款成功。
  • 如果 result.resultStatus 的值为F，退款失败。通常，失败原因是退款窗口已过期(result.resultCode = REFUND_WINDOW_EXCEED)。如果仍需处理退款，请联系相关人员。
  • 如果 result.resultStatus 的值为U，结果未知。可能由于系统或网络问题导致处理失败。使用相同的 refundRequestId 重试，或使用 退款查询 接口查询退款结果。

结果码

结果码值结果码信息行动建议
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退款正在处理中。

等待异步通知或调用 退款查询 接口查询最终退款状态。请勿重试退款请求。 

REFUND_NOT_SUPPORTEDF该交易不支持退款。

检查交易状态和合同中的退款政策。如果交易成功且合同允许退款，请联系 Antom 技术支持。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过了限制。

再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。

PARTIAL_REFUND_NOT_SUPPORTEDF该交易不支持部分退款。

进行全额退款或与买家协商线下退款。  

PAYMENT_METHOD_NOT_SUPPORTEDF支付状态成功时，支付方式不支持取消或退款交易。

获取 Antom 技术支持前请勿重试。

ORDER_IS_CANCELEDF交易已取消。

交易已取消，无法退款。

UNKNOWN_EXCEPTIONU由于未知原因，接口调用失败。

再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。