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

退款通知

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

结构

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

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

  • 如果字段的数据类型为整数属性，且其值为 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

APO 分配的用于识别退款的专属 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

acquirerInfo AcquirerInfo  

处理该支付的收单机构信息。

Show child parameters

rrn String  

取回参考号（RRN）。可用于与发卡行跟踪支付、退款或争议的详细信息。

更多信息：

  • 最大长度：32 字符

arn String  

收单银行提供的交易号。可以提供给买家，也可用于查询资金流动。

更多信息：

  • 最大长度：64 字符

出参

result Result  REQUIRED

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

Show child parameters
API Explorer

请求

请求体

响应

响应体

结果处理逻辑

在接收到 APO 的通知后，发送包含固定值的以下报文，以确认已收到 APO 的通知：

Sample Code

如果由于操作问题或网络问题，没有向 APO 返回这样的消息，APO 会重新发送通知，直到商家返回所需的消息。首次通知后的 24 小时内，APO 会重新发送通知，最多重试 8 次，间隔时间为 0 秒、2 分钟、10 分钟、10 分钟、1 小时、2 小时、6 小时和 15 小时。

结果/错误码

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

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

ACCESS_DENIEDF访问被拒绝。

请联系 APO 技术支持以获取详细原因。

INVALID_APIF调用的接口无效或未激活。

请联系 APO 技术支持来解决问题。

CLIENT_INVALIDF客户端 ID 无效。APO 对客户端 ID 有限制。

请检查客户端 ID 是否正确，或联系 APO 技术支持获取详细原因。

CURRENCY_NOT_SUPPORTF币种不受支持。

请联系 APO 技术支持以获取详细原因。

INVALID_CONTRACTF合同中的参数值与当前交易不符。

检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 APO 技术支持以解决问题。

INVALID_MERCHANT_STATUSF由于存在限制，商户状态异常。

请联系 APO 技术支持以获取详细原因。

INVALID_SIGNATUREF签名验证失败。用于签署请求的私钥与 APO Dashboard 的公钥不匹配。

检查用于签署请求的私钥是否与 APO Dashboard 的公钥匹配。以下签名参考信息很有用：

KEY_NOT_FOUNDF未找到 APO 或商户的私钥或公钥。

检查私钥或公钥是否存在。如果不存在，请在 APO Dashboard 中上传私钥。

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

请检查媒体类型是否正确，并使用 APO 接受的媒体类型。

MERCHANT_BALANCE_NOT_ENOUGHF商户余额不足。

在商户余额充足后再次调用接口。尝试再次退款时，需要更改 refundRequestId 字段。

MERCHANT_NOT_REGISTEREDF商户未注册。

请使用注册接口注册商户。如果调用注册接口失败，请联系 APO 技术支持。

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

确保 HTTP 方法为POST。

MULTIPLE_REFUNDS_NOT_SUPPORTEDF由于合同限制，不支持多次退款。

检查是否存在多个退款。不要再调用退款接口。对于每个退款，仅调用一次接口。

NO_INTERFACE_DEFF接口未定义。

检查链接是否正确。请参考接口文档中的端点。

ORDER_IS_CLOSEDF交易已关闭，无法再次支付。

使用新的 paymentRequestId 重新发起退款。

ORDER_NOT_EXISTF订单不存在。

检查 paymentId 是否正确。如果正确，请联系 APO 技术支持以获取具体原因。

ORDER_STATUS_INVALIDF订单状态无效。交易正在处理中或交易失败。

检查订单状态并采取相应操作。

  • 如果交易正在处理中，请等待。
  • 如果交易失败，不要发起退款。请具体原因联系 APO 技术支持。
PARAM_ILLEGALF缺少必需的参数，或者存在非法参数。例如，非数字输入，无效的日期，或者参数的长度和类型错误。

检查并验证当前接口所需的请求字段（包括头字段和正文字段）是否正确传递并有效。

PROCESS_FAILF发生了常见的业务失败。

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

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

确认总退款金额是否超过支付金额。使用小于或等于支付金额的金额创建新的退款，或联系 APO 技术支持。

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

确认退款日期是否超过可退款期限。在合同中检查可退款期限，或联系 APO 技术支持获取具体的可退款期限。

REPEAT_REQ_INCONSISTENTF金额或币种与先前请求不同。

确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起退款。

RISK_REJECTF请求因风险控制被拒绝。

提示买家请求被拒绝，因为风险控制失败。

SYSTEM_ERRORF发生了系统错误。

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

REFUND_IN_PROCESSU退款正在处理中。

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

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过了限制。

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

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

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