退款

在支付成功后，您可以通过调用 refund 接口对成功支付的交易发起退款。

下图为退款流程图：

yuque_diagram (15).png

退款步骤

根据以下步骤开始集成：

  1. 发起退款请求
  2. 获取退款结果

步骤 1：发起退款请求 服务端

调用 refund 接口发起退款请求。以下是一个退款请求的示例代码：

copy
{
  "paymentId": "20181129190741010007000000XXXX",
  "refundRequestId": "20181129190741020007000000XXXX",
  "refundAmount": {
    "value": "100",
    "currency": "USD"
  },
  "refundNotifyUrl": "https://www.baidu.com"
}

以下代码展示了一个响应的示例：

copy
{
  "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"
}

步骤 2：获取退款结果 服务端

Antom 会通过服务器交互将相应的退款结果发送给您，您可以通过以下方法之一获取退款结果：

  • 接收异步通知
  • 查询退款结果

接收异步通知

接收来自 Antom notifyRefund 发送的异步通知。

以下是退款异步通知请求的代码示例：

copy
{
  "notifyType": "REFUND_RESULT",
  "refundAmount": {
    "currency": "HKD",
    "value": "10000"
  },
  "refundId": "2021080419401080130018866020092XXXX",
  "refundRequestId": "amsdemorefund_zhangyikai_zyk_20210804_165236_931",
  "refundStatus": "SUCCESS",
  "refundTime": "2021-08-04T01:52:37-07:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }

当您收到 Antom 的异步通知，您需要按照返回收到确认信息的格式返回响应，但无需做加签处理。您需要对 Antom 发送的支付通知进行验签，关于如何验证通知的签名并做出响应，请参阅处理通知。

无论订单是否退款成功，每个通知请求均需按以下固定格式响应。否则，Antom 会重新发送异步通知：

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}

接收异步通知

除了通过异步通知获取退款结果，您还可以调用 inquiryRefund 接口主动查询退款结果，使用退款阶段中的 refundRequestId 查询退款状态。

以下是退款查询请求的代码示例：

copy
{
    "refundRequestId": "REQUEST_20240612202258994"
}

以下代码展示了一个响应报文的示例：

copy
{
  "refundAmount": {
    "currency": "HKD",
    "value": "10000"
  },
  "refundId": "2021080419401080130018866020092XXXX",
  "refundRequestId": "amsdemorefund_zhangyikai_zyk_20210804_165236_931",
  "refundStatus": "SUCCESS",
  "refundTime": "2021-08-04T01:52:37-07:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }
}

下表展示了退款查询的响应中 refundStatus 字段可能返回的值，请您根据指引进行处理：

refundStatus

信息

后续操作

SUCCESS

退款成功。

无需进一步操作。

FAIL

退款失败。

建议更换 refundRequestId 重试。如果问题未解决，联系 Antom 技术支持排查问题。

PROCESSING退款处理中。

建议继续查询，直到获取终态结果或收到退款异步通知。