refund

2026-05-15 09:30

POST /v2/payments/refund

调用 refund 接口来对交易成功的订单进行全额或部分退款。

结构

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

请求参数

参数名称	类型	是否必需	描述
refundRequestId	String	是	由商户分配的用于标识退款请求的唯一 ID。（最大长度：64 个字符）
paymentId	String	是	支付 ID。注意：每个 paymentId 同一时间仅允许处理一个退款请求。
originalMerchantRefundId	String	USB 连线通信模式时必需	商户侧 POS 的 referenceRefundId（仅在 USB 连线通信模式下可用）。
refundAmount	Amount	否	退款金额。注意：仅在部分退款时需传入值，若未传入值则视为全额退款。
memo	String	否	退款备注信息。（最大长度：256个字符）

Amount

参数名称	类型	是否必需	描述
value	Integer	是	货币最小单位的金额值。例如，`10000` 表示新加坡元 100.00。（取值范围：0-2147483647）
currency	String	是	遵循 ISO-4217 标准的 3 个字符的货币代码。例如，`USD`。（最大长度：3 个字符）

响应参数

参数名称	类型	是否必需	描述
refundRequestId	String	是	退款 ID。
result	Result	是	接口调用的结果。
refundId	String	是	退款 ID。

Result

参数名称	类型	是否必需	描述
resultStatus	String	是	结果状态。有效值为： `S`：成功 `F`：失败 `U`：未知
resultCode	String	否	结果码。（最大长度：64 个字符）
resultMessage	String	否	详细描述结果码的结果消息。（最大长度：256 个字符）

结果码

结果码	状态码	结果信息	后续操作
`SUCCESS`	`S`	成功	无需后续操作。
`DPOS_PAYMENT_ACCESS_DENIED`	`F`	访问被拒绝。	请联系 Antom 技术支持以获取详细原因。
`DPOS_PAYMENT_CURRENCY_NOT_SUPPORT`	`F`	币种不受支持。	请联系 Antom 技术支持以获取详细原因。
`DPOS_PAYMENT_INVALID_MERCHANT_STATUS`	`F`	由于存在限制，商户状态异常。	请联系 Antom 技术支持以获取详细原因。
`DPOS_PAYMENT_ORDER_IS_CLOSED`	`F`	您发起的请求具有与已关闭交易相同的 paymentRequestId。	使用新的 paymentRequestId 重新发起退款。
`DPOS_PAYMENT_ORDER_NOT_EXIST`	`F`	订单不存在。	检查 paymentId 是否正确。如果正确，请联系 Antom 技术支持以获取具体原因。
`DPOS_PAYMENT_ORDER_STATUS_INVALID`	`F`	订单状态无效。交易正在进行中或交易失败。	检查订单状态并采取相应操作。如果交易正在处理中，请等待。如果交易失败，不要发起退款。请具体原因联系 Antom 技术支持。
`DPOS_PAYMENT_REPEAT_REQ_INCONSISTENT`	`F`	金额或币种与先前请求不同。	确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起退款。
`DPOS_PAYMENT_RISK_REJECT`	`F`	因风险控制，请求被拒绝。	提示买家请求被拒绝，因为风险控制失败。
`DPOS_PAYMENT_ORDER_IS_CANCELED`	`F`	交易已取消。	交易已取消，无法退款。
`DPOS_SYSTEM_ ERROR`	`F`	发生系统错误。	获取 Antom 技术支持前请勿重试。
`DPOS_REFUND_KEY_NOT_FOUND`	`F`	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
`DPOS_REFUND_MERCHANT_BALANCE_NOT_ENOUGH`	`F`	商户余额不足。	当商家账户余额充足后，再次调用接口。重试时需要修改 refundRequestId 参数。
`DPOS_REFUND_MULTIPLE_REFUNDS_NOT_SUPPORTED`	`F`	由于合同限制，不支持多次退款。	检查是否存在多个退款。不要再调用退款接口。每个退款请求仅调用一次接口。
`DPOS_REFUND_NO_INTERFACE_DEF`	`F`	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
`DPOS_REFUND_INVALID_API`	`F`	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
`DPOS_REFUND_PROCESS_FAIL`	`F`	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
`DPOS_REFUND_REFUND_AMOUNT_EXCEED`	`F`	退款总额超过了支付金额。	确认退款总额是否超过支付金额。创建一个金额小于或等于支付金额的新退款，或联系 Antom 技术支持。
`DPOS_REFUND_REFUND_WINDOW_EXCEED`	`F`	退款日期超过了合同约定的退款期限。	确认退款日期是否超过可退款期限。在合同中查看可退款期限，或联系 Antom 技术支持获取具体可退款期限。
`DPOS_REFUND_REQUEST_TRAFFIC_EXCEED_LIMIT`	`F`	请求流量超过限制。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。
`DPOS_REFUND_REFUND_IN_PROCESS`	`U`	退款正在处理中。	等待异步通知或调用 inquiryRefund 接口查询最终退款状态。请勿重试退款请求。
`DPOS_REFUND_REFUND_NOT_SUPPORT`	`F`	该交易不支持退款。	检查交易状态和合同中的退款政策。如果交易成功且合同允许退款，请联系 Antom 技术支持。
`DPOS_REFUND_PARTIAL_REFUND_NOT_SUPPORTED`	`F`	该交易不支持部分退款。	进行全额退款或与买家协商线下退款。
`DPOS_REFUND_PAYMENT_METHOD_NOT_SUPPORTED`	`F`	支付状态成功时，支付方式不支持取消或退款交易。	获取 Antom 技术支持前请勿重试。
`DPOS_REFUND_UNKNOWN_EXCEPTION`	`U`	由于未知原因，接口调用失败。	再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。

示例

以下代码展示了一个请求报文：

copy
{
    "payRequestId": "uB0RN0c88v26cwW9IN2lE3fuW3AIRZ0v2ooyH6amwtM3by6o13e**********",
    "paymentId": "2026022593030000001******",
    "refundRequestId": "03PF50082_1770267087585_85******",
    "memo": "",
    "refundAmount": null
}

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

copy
{
    "refundId": "20260410194010890100111670209******",
    "refundRequestId": "03PF50082_1770267087585_85******",
    "refundTime": "2026-04-10T11:32:54Z",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success.",
        "resultStatus": "S"
    }
}