Payments
go to Evonet

Refund API

通过 POST /payment/{merchantTransID}/refund 发起全额（refunded_full）或部分退款（refunded_partial）。

请求示例：

{
    "merchantTransInfo": {
        "merchantTransID": "refund_25073",
        "merchantTransTime": "2025-07-09T11:18:00+08:00"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100.00"
    },
    "webhook": "https://6ee8218a-52e4-4b16-8d67-594cdb34bb23.mock.pstmn.io",
    "initiatingReason": "initiatingReason",
    "metadata": "metadata"
}

响应示例：

{
    "metadata": "metadata",
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141712550002000071332821",
            "evoTransTime": "2026-04-14T09:12:55Z",
            "retrievalReferenceNum": "610417890130",
            "traceNum": "890130"
        },
        "merchantTransInfo": {
            "merchantTransID": "pay_2604141712550002000071332821",
            "merchantTransTime": "2026-04-14T17:12:54+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019243",
            "pspTransTime": "2026-04-14T09:12:54Z",
            "retrievalReferenceNum": "610417890130"
        },
        "status": "refund_pending",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "489533",
            "fundingType": "credit",
            "last4No": "1119",
            "paymentBrand": "Visa"
        },
        "issuingCountry": "USA"
    },
    "refund": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141713200002000099623511",
            "evoTransTime": "2026-04-14T09:13:20Z",
            "retrievalReferenceNum": "610417890139",
            "traceNum": "000359"
        },
        "merchantTransInfo": {
            "merchantTransID": "refund_25073",
            "merchantTransTime": "2025-07-09T11:18:00+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019243",
            "pspTransTime": "2026-04-14T09:13:20Z",
            "retrievalReferenceNum": "610417890139"
        },
        "status": "refund_pending",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

处理逻辑

响应中，需首先查看 result.code：

  • 非 S 开头：退款失败
  • S 开头（如 S0000）：退款成功，需要查看 refund.status
    • refund_pending：需接收 eventCode: "Refund" 的异步通知，通过异步通知中的 refund.status 字段确定退款结果
📘

Note

可以通过调用 GET /payment 接口来查看部分退款或全额退款。

关键字段：

字段名类型描述注意事项
refund.statusstring退款状态
result.codestring应答码S 开头表示查询成功

更多参数信息请参考：payment API 中 POST refund 部分。


退款结果查询方式

发起退款后，可通过以下三种方式查询退款结果：

1. Retrieve API 查询

调用 GET /payment 接口查询订单信息。

在响应中：

  • 查看 payment.status 判断整体订单状态 (如 refunded_full / refunded_partial)
  • 查看 events 数组中退款相关事件

响应示例：

{
    "action": {
        "type": "completed"
    },
    "authentication": {
        "liabilityShift": false
    },
    "events": [
        {
            "eventID": "evt_pay_2604141712550002000071332821_1",
            "eventTime": "2026-04-14T17:12:55.950Z",
            "merchantTransID": "pay_2604141712550002000071332821",
            "status": "authorized"
        },
        {
            "eventID": "evt_pay_2604141712550002000071332821_2",
            "eventTime": "2026-04-14T17:12:56.041Z",
            "merchantTransID": "pay_2604141712550002000071332821",
            "status": "captured"
        },
        {
            "eventID": "evt_pay_2604141713200002000099623511_1",
            "eventTime": "2026-04-14T17:13:22.042Z",
            "merchantTransID": "refund_25073",
            "status": "refund_successed"
        }
    ],
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141712550002000071332821",
            "evoTransTime": "2026-04-14T09:12:55Z",
            "retrievalReferenceNum": "610417890130",
            "traceNum": "890130"
        },
        "merchantTransInfo": {
            "merchantTransID": "pay_2604141712550002000071332821",
            "merchantTransTime": "2026-04-14T17:12:54+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019243",
            "cvcCheckResult": " ",
            "cvcCheckResultRaw": " ",
            "pspTransTime": "2026-04-14T09:12:54Z",
            "retrievalReferenceNum": "610417890130"
        },
        "status": "refunded_full",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "489533",
            "fundingType": "credit",
            "last4No": "1119",
            "paymentBrand": "Visa"
        },
        "isNetworkToken": false,
        "issuingCountry": "USA"
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "transInitiator": {
        "platform": "WEB",
        "terminalID": "123456",
        "userCreateIP": "222.71.133.101"
    }
}

说明：event.status = refund_successed 表示退款成功，refund_declined 表示退款失败。payment.status 表示当前订单整体退款状态。

2. 异步通知 (Webhook)

系统会发送 eventCode = "Refund" 的异步通知。

示例：

{
    "eventCode": "Refund",
    "metadata": "metadata",
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141712550002000071332821",
            "evoTransTime": "2026-04-14T09:12:55Z",
            "retrievalReferenceNum": "610417890130",
            "traceNum": "890130"
        },
        "merchantTransInfo": {
            "merchantTransID": "pay_2604141712550002000071332821",
            "merchantTransTime": "2026-04-14T17:12:54+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019243",
            "pspTransTime": "2026-04-14T09:12:54Z",
            "retrievalReferenceNum": "610417890130"
        },
        "status": "refunded_full",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "489533",
            "fundingType": "credit",
            "last4No": "1119",
            "paymentBrand": "Visa"
        },
        "issuingCountry": "USA"
    },
    "refund": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141713200002000099623511",
            "evoTransTime": "2026-04-14T09:13:20Z",
            "retrievalReferenceNum": "610417890139",
            "traceNum": "000359"
        },
        "merchantTransInfo": {
            "merchantTransID": "refund_25073",
            "merchantTransTime": "2025-07-09T11:18:00+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019328",
            "pspTransTime": "2026-04-14T17:13:20+08:00",
            "retrievalReferenceNum": "610417890139"
        },
        "status": "refund_successed",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "storeInfo": {
        "mcc": "5816",
        "sid": "S005188",
        "storeID": "S005188"
    }
}

说明：refund.status 为退款状态结果，建议以异步通知作为退款结果的最终依据。

3. Event 查询接口

可通过 GET /event 接口查询单个事件详情：使用 Retrieve API 返回的 events.eventID 作为查询参数。

响应示例：

{
    "authentication": {
        "liabilityShift": false
    },
    "event": {
        "eventID": "evt_pay_2604141713200002000099623511_1",
        "eventTime": "2026-04-14T17:13:22.042Z",
        "status": "refund_successed"
    },
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141712550002000071332821",
            "evoTransTime": "2026-04-14T09:12:55Z",
            "retrievalReferenceNum": "610417890130",
            "traceNum": "890130"
        },
        "merchantTransInfo": {
            "merchantTransID": "pay_2604141712550002000071332821",
            "merchantTransTime": "2026-04-14T17:12:54+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019243",
            "cvcCheckResult": " ",
            "cvcCheckResultRaw": " ",
            "pspTransTime": "2026-04-14T09:12:54Z",
            "retrievalReferenceNum": "610417890130"
        },
        "status": "refunded_full",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "489533",
            "fundingType": "credit",
            "last4No": "1119",
            "paymentBrand": "Visa"
        },
        "isNetworkToken": false,
        "issuingCountry": "USA"
    },
    "refund": {
        "evoTransInfo": {
            "evoTransID": "pay_2604141713200002000099623511",
            "evoTransTime": "2026-04-14T09:13:20Z",
            "retrievalReferenceNum": "610417890139",
            "traceNum": "000359"
        },
        "merchantTransInfo": {
            "merchantTransID": "refund_25073",
            "merchantTransTime": "2025-07-09T11:18:00+08:00"
        },
        "pspTransInfo": {
            "authorizationCode": "019328",
            "pspTransTime": "2026-04-14T09:13:20Z",
            "retrievalReferenceNum": "610417890139"
        },
        "status": "refund_successed",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

说明： 可用于精确查询某一笔退款事件状态。

参数信息请参考：payment API 中 GET event 部分。


Updated 13 days ago