Payments
go to Evonet

Dispute API

概述

Dispute API 为商户提供争议案件查询、抗辩材料提交以及平台异步通知接受能力。本文档覆盖争议处理的两类业务场景，两者共用同一套异步通知机制，但业务流程与商户处理方式不同，请商户结合自身业务场景区分对接：

争议拒付（Chargeback Dispute）：发卡行对某笔交易正式发起拒付。商户需通过本 API 查询争议案件、提交抗辩材料、接受争议结果。

拒付预警（Dispute Alert）：基于 Ethoca 的拒付预警服务。发卡行确认欺诈或持卡人发起争议时，平台推送预警通知，并视情况自动退款或转入人工退款流程。商户仅需接收通知，无需主动查询或抗辩。


一、争议类型总览

两类业务均由平台通过异步通知推送给商户，事件码统一为 "Dispute"，但通知内容与商户动作不同。对接前请先确认当前通知属于哪类业务：

对比项争议拒付（Chargeback Dispute）拒付预警（Dispute Alert）
触发来源发卡行正式发起拒付（Chargeback）Ethoca 告警：确认欺诈（Confirmed Fraud）或客户争议（Customer Dispute）
商户交互查询（dispute.query）、提交/更新抗辩（dispute.defend）仅接收异步通知，回复 SUCCESS
涉及接口异步通知 + dispute.query + dispute.defend仅异步通知

快速判断：通知中disputeType 为 Dispute Alert 的，属于拒付预警；disputeType 为 Chargeback 的属于争议拒付。


二、异步通知

2.1 通知机制（两类业务通用）

平台主动向商户配置的回调地址推送通知。商户必须返回字符串 SUCCESS 以确认收到。


2.2 争议拒付通知（Chargeback Dispute）

通知类型由 disputeInfo.disputeMode 决定。

disputeMode说明
DISPUTE_NOTIFICATION有新的争议针对商户提出
DOCUMENT_ERROR_NOTIFICATION已提交的抗辩文件存在问题，需重新上传

DISPUTE_NOTIFICATION：

{
    "eventCode": "Dispute",
    "action": {
        "type": "accept",
        "suggestion": "A cardholder is claiming that they did not authorize or participate in a transaction that you processed. ..."
    },
    "disputeInfo": {
        "ARN": "74678814244000020091002",
        "caseNo": "2025051518140410700026",
        "disputeAmount": {"currency": "USD", "value": "44.99"},
        "disputeCode": "10.4",
        "disputeEndtime": "2024-09-18T19:00:00Z",
        "disputeMessage": "Other Fraud - Card- Absent Environment",
        "disputeMode": "DISPUTE_NOTIFICATION",
        "disputeSettlementAmount": {"currency": "USD", "value": "44.99"},
        "disputeType": "Chargeback",
        "paymentBrand": "VIS",
        "recordTime": "2025-05-15T10:14:04Z",
        "status": "notified"
    },
    "merchantTransInfo": {
        "merchantTransID": "T505141747192201380",
        "merchantTransTime": "2025-05-14T11:10:01+08:00"
    },
    "storeInfo": {
        "merName": "集团号唯一性测试",
        "storeName": "xzsGroupTest1"
    },
    "transAmount": {"currency": "CNY", "value": "1.00"}
}

DOCUMENT_ERROR_NOTIFICATION：

{
    "eventCode": "Dispute",
    "disputeInfo": {
        "caseNo": "2025052015150461400351",
        "disputeMode": "DOCUMENT_ERROR_NOTIFICATION",
        "documentErrorRemarks": "test",
        "status": "uploadNeeded"
    }
}

通知体字段

参数类型说明
eventCodeString始终为 "Dispute"（争议相关通知）
actionObject卡组织建议的操作（DISPUTE_NOTIFICATION 时出现）
action.typeString操作类型，如 accept
action.suggestionString卡组织的详细建议
disputeInfoObject争议核心信息
disputeInfo.caseNoString争议案件唯一编号
disputeInfo.disputeModeString通知类型：DISPUTE_NOTIFICATION 或 DOCUMENT_ERROR_NOTIFICATION
disputeInfo.statusString当前争议状态
disputeInfo.ARNString收单方参考号（通知中为大写；查询中为小写 arn）
disputeInfo.disputeCodeString争议原因码
disputeInfo.disputeMessageString争议原因描述
disputeInfo.disputeTypeString争议类别，如 Chargeback
拒付预警场景为 Dispute Alert
disputeInfo.disputeAmountObject争议金额
disputeInfo.disputeAmount.currencyStringISO 4217 货币代码
disputeInfo.disputeAmount.valueString金额值（两位小数字符串）
disputeInfo.disputeSettlementAmountObject结算金额
disputeInfo.disputeSettlementAmount.currencyStringISO 4217 货币代码
disputeInfo.disputeSettlementAmount.valueString金额值（两位小数字符串）
disputeInfo.disputeEndtimeString争议截止时间（ISO 8601 UTC）
disputeInfo.recordTimeString通知创建时间（ISO 8601 UTC）
disputeInfo.paymentBrandString支付网络，如 VIS
disputeInfo.documentErrorRemarksString错误说明（仅 DOCUMENT_ERROR_NOTIFICATION）
merchantTransInfoObject原始商户交易详情
merchantTransInfo.merchantTransIDString商户交易 ID
merchantTransInfo.merchantTransTimeString商户交易时间（ISO 8601 含时区），如 2025-05-14T11:10:01+08:00
storeInfoObject门店信息
storeInfo.merNameString商户名称
storeInfo.storeNameString门店名称
transAmountObject原始交易金额
transAmount.currencyStringISO 4217 货币代码
transAmount.valueString交易金额（两位小数字符串）

2.3 拒付预警通知（Dispute Alert）

通知类型由 disputeInfo.status 决定，告警来源由 disputeInfo.alertType 区分：

字段取值说明
disputeInfo.statusreceived已受理 Ethoca 告警，告警接入成功
disputeInfo.statusmanual_pending该告警需人工退款，已进入人工处理流程
disputeInfo.statusrefunded该告警已自动完成全额退款
disputeInfo.alertTypeConfirmed Fraud确认欺诈告警
disputeInfo.alertTypeCustomer Dispute客户争议告警

merchantTransInfo 可用性说明

拒付预警通知中，原始商户交易信息 merchantTransInfo（含 merchantTransID、merchantTransTime）仅在 manual_pending / refunded 状态的通知中返回，received 通知不含该字段。

示例：

{
    "eventCode": "Dispute",
    "disputeInfo": {
        "alertType": "Confirmed Fraud",
        "caseNo": "6acc54459a35987b70edeef4",
        "disputeAmount": {"currency": "HKD", "value": "100.00"},
        "disputeMode": "DISPUTE_NOTIFICATION",
        "disputeType": "Dispute Alert",
        "recordTime": "2026-10-12T11:40:41+08:00",
        "remarks": "API for Ethoca",
        "status": "refunded"
    },
    "merchantTransInfo": {
        "merchantTransID": "pay-2609161412010002000041603719",
        "merchantTransTime": "2026-09-16T14:11:59+08:00"
    },
    "storeInfo": {
        "storeID": "S005317",
        "storeName": "E3 EVONET Test"
    },
    "transAmount": {"currency": "HKD", "value": "100.00"}
}


三、争议查询(dispute.query)

3.1 接口信息

字段值
请求方式GET
路径/g2/v1/settlement/mer/{SID}/dispute.query

通过案件编号或日期范围查询争议。传入 caseNo 返回指定争议，否则返回日期范围内的全部争议。

3.2 请求参数

  • 按案件编号查询：
参数类型必填最大长度说明
caseNoString(64)是64争议案件编号
  • 按日期范围查询：
参数类型必填最大长度说明
startDateString(8)是8起始日期，格式 YYYYMMDD
endDateString(8)是8截止日期，格式 YYYYMMDD。必须晚于 startDate

3.3 请求示例

  • 按案件编号：
GET /g2/v1/settlement/mer/{SID}/dispute.query

{
    "caseNo": "2025052015150461400351"
}
  • 按日期范围：
GET /g2/v1/settlement/mer/{SID}/dispute.query

{
    "startDate": "20250514",
    "endDate": "20250521"
}

3.4 响应参数

参数类型说明
resultObject处理结果
result.codeString结果码。S0000 表示成功；不以 S 前缀开头的均为失败
result.messageString结果描述
listItemsString返回的争议记录总数（字符串形式的整数）
dataArray争议记录列表
data[].disputeInfoObject争议核心信息
data[].disputeInfo.caseNoString争议案件唯一编号
data[].disputeInfo.disputeModeString查询时的模式，如 DEFENSE_INFO
data[].disputeInfo.statusString当前状态。详见状态流转
data[].disputeInfo.resultString争议结果类别，如 newChargeback
data[].disputeInfo.disputeTypeString争议类别，如 Chargeback
data[].disputeInfo.disputeCodeString争议原因码，如 10.4（欺诈）、13.7（已取消商品/服务）
data[].disputeInfo.disputeMessageString争议原因描述
data[].disputeInfo.suggestionString卡组织给出的建议
data[].disputeInfo.disputeEndTimeString争议截止时间（ISO 8601 UTC），如 2024-09-18T19:00:00Z
data[].disputeInfo.recordTimeString争议创建时间（ISO 8601 UTC），如 2025-05-15T10:14:04Z
data[].disputeInfo.paymentBrandString支付网络，如 VIS
data[].disputeInfo.disputeAmountObject争议金额
data[].disputeInfo.disputeAmount.currencyStringISO 4217 货币代码
data[].disputeInfo.disputeAmount.valueString金额值（两位小数字符串）
data[].disputeInfo.disputeSettlementAmountObject争议结算金额
data[].disputeInfo.disputeSettlementAmount.currencyStringISO 4217 货币代码
data[].disputeInfo.disputeSettlementAmount.valueString金额值（两位小数字符串）
data[].disputeInfo.arnString收单方参考号（查询中为小写 arn，通知中为大写 ARN）
data[].merchantTransInfoObject原始商户交易详情（可能为空对象 {}）
data[].merchantTransInfo.merchantTransIDString商户交易 ID
data[].merchantTransInfo.merchantTransTimeString商户交易时间（ISO 8601 含时区），如 2025-05-14T11:10:01+08:00
data[].storeInfoObject门店信息（可能为空对象 {}）
data[].storeInfo.merNameString商户名称
data[].storeInfo.storeNameString门店名称
data[].transAmountObject原始交易金额（可能为空对象 {}）
data[].transAmount.currencyStringISO 4217 货币代码
data[].transAmount.valueString交易金额（两位小数字符串）

3.5 响应示例

  • 单笔查询：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "listItems": "1",
    "data": [
        {
            "disputeInfo": {
                "caseNo": "2025052015150461400351",
                "disputeMode": "DEFENSE DOCUMENT_UPDATE",
                "status": "uploadNeeded",
                "result": "newChargeback",
                "disputeType": "Chargeback",
                "disputeCode": "10.4",
                "disputeMessage": "Other Fraud - Card- Absent Environment",
                "suggestion": "A cardholder is claiming that they did not authorize or participate in a transaction that you processed. ...",
                "disputeEndTime": "2024-09-18T19:00:00Z",
                "recordTime": "2025-05-20T07:15:04Z",
                "paymentBrand": "VIS",
                "disputeAmount": {
                    "currency": "USD",
                    "value": "44.99"
                },
                "disputeSettlementAmount": {
                    "currency": "USD",
                    "value": "44.99"
                },
                "arn": "74678814244000020091001"
            },
            "merchantTransInfo": {
                "merchantTransID": "T505141747192201380",
                "merchantTransTime": "2025-05-14T11:10:01+08:00"
            },
            "storeInfo": {
                "merName": "集团号唯一性测试",
                "storeName": "xzsGroupTest1"
            },
            "transAmount": {
                "currency": "CNY",
                "value": "1.00"
            }
        }
    ]
}

  • 日期范围查询：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "listItems": "5",
    "data": [
        {
            "disputeInfo": {
                "caseNo": "2025051518140406000018",
                "disputeMode": "DISPUTE_NOTIFICATION",
                "status": "End",
                "disputeType": "Chargeback",
                "disputeCode": "10.4",
                "disputeMessage": "Other Fraud - Card- Absent Environment",
                "suggestion": "A cardholder is claiming that they did not authorize...",
                "disputeEndTime": "2024-09-18T19:00:00Z",
                "recordTime": "2025-05-15T10:14:04Z",
                "paymentBrand": "VIS",
                "disputeAmount": {"currency": "USD", "value": "44.99"},
                "disputeSettlementAmount": {"currency": "USD", "value": "44.99"},
                "arn": "74678814244000020091000"
            },
            "merchantTransInfo": {
                "merchantTransID": "T505141747192201380",
                "merchantTransTime": "2025-05-14T11:10:01+08:00"
            },
            "storeInfo": {
                "merName": "集团号唯一性测试",
                "storeName": "xzsGroupTest1"
            },
            "transAmount": {"currency": "CNY", "value": "1.00"}
        },
        {
            "disputeInfo": {
                "caseNo": "2025051518140406800019",
                "disputeMode": "DEFENSE_INFO",
                "status": "caseCompleted",
                "disputeType": "Chargeback",
                "disputeCode": "13.7",
                "disputeMessage": "Cancelled Merchandise/Services",
                "disputeEndTime": "2021-07-01T19:00:00Z",
                "recordTime": "2025-05-15T10:14:04Z",
                "paymentBrand": "VIS",
                "disputeAmount": {"currency": "THB", "value": "1798.00"},
                "disputeSettlementAmount": {"currency": "THB", "value": "1798.00"},
                "arn": "74678811156000010061000"
            },
            "merchantTransInfo": {},
            "storeInfo": {},
            "transAmount": {}
        }
    ]
}

注意：当相关数据不可用时，merchantTransInfo、storeInfo、transAmount 可能为空对象 {}。


四、抗辩操作（dispute.defend）

4.1 接口信息

字段值
请求方式POST
路径/g2/v1/settlement/mer/{SID}/dispute.defend

针对争议提交抗辩操作，包括接受结果、上传初始抗辩文件或更新已提交的文件。

4.2 请求参数

参数类型必填说明
disputeInfo.disputeModeString是抗辩模式。
ACCEPT_DISPUTE_RESULT：接受争议结果，放弃抗辩。状态变为 finished；
DEFENSE_DOCUMENT：提交抗辩文件（首次）。状态变为 uploadNeeded；
DEFENSE_DOCUMENT_UPDATE：更新已提交的抗辩文件。状态变为 continueDefensing
disputeInfo.caseNoString是争议案件编号
disputeInfo.fileMetaDataArray条件必填文件列表。当 disputeMode 为 DEFENSE_DOCUMENT 或 DEFENSE_DOCUMENT_UPDATE 时必填
disputeInfo.fileMetaData[].fileNameString是含扩展名的文件名，如 receipt.PDF
disputeInfo.fileMetaData[].fileString是Base64 编码的文件内容。编码前单文件最大 10 MB

4.3 请求示例

  • ACCEPT_DISPUTE_RESULT：

POST /g2/v1/settlement/mer/{SID}/dispute.defend

{
    "disputeInfo": {
        "disputeMode": "ACCEPT_DISPUTE_RESULT",
        "caseNo": "2025052015150461400351"
    }
}

  • DEFENSE_DOCUMENT_UPDATE：

POST /g2/v1/settlement/mer/{SID}/dispute.defend

{
    "disputeInfo": {
        "disputeMode": "DEFENSE_DOCUMENT_UPDATE",
        "caseNo": "2025052015150461400351",
        "fileMetaData": [
            {
                "fileName": "123.PDF",
                "file": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBl..."
            }
        ]
    }
}

注意：首次提交（DEFENSE_DOCUMENT）的 fileMetaData 结构与 DEFENSE_DOCUMENT_UPDATE 相同。

4.4 响应参数

参数类型说明
resultObject处理结果
result.codeString结果码。S0000 表示成功
result.messageString结果描述
disputeInfoObject更新后的争议信息
disputeInfo.caseNoString争议案件编号
disputeInfo.disputeModeString使用的抗辩模式
disputeInfo.statusString更新后的争议状态

4.5 响应示例

  • 成功（ACCEPT_DISPUTE_RESULT）：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "disputeInfo": {
        "caseNo": "2025052210165183500384",
        "disputeMode": "ACCEPT_DISPUTE_RESULT",
        "status": "finished"
    }
}

  • 成功（DEFENSE_DOCUMENT_UPDATE）：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "disputeInfo": {
        "caseNo": "2025052015150461400351",
        "disputeMode": "DEFENSE_DOCUMENT_UPDATE",
        "status": "continueDefensing"
    }
}

  • 失败：

{
    "result": {
        "code": "B0014",
        "message": "Invalid transaction status uploadNeeded to complete the request"
    }
}


Updated about 17 hours ago

Did this page help you?