Payments
go to Evonet

Dispute API

一、概述

Dispute API 为商户提供争议案件查询、抗辩材料提交以及平台异步通知接受能力。本文档涵盖完整对接流程，包含 API 接口、请求/响应格式、状态流转及错误码。

争议（拒付）是指持卡人对某笔交易提出异议，并要求发卡行撤销该笔交易。商户可通过本 API 端到端管理整理争议的整个生命周期。


二、API 接口

2.1 异步通知

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

2.1.1 统一事件码

所有争议通知的事件码均为 "Dispute"。具体通知类型由 disputeInfo.disputeMode 决定。

2.1.2 通知类型（按 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"
    }
}

2.1.3 通知体字段

参数类型说明
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
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.1.4 商户必须返回的响应

商户必须返回字符串：

SUCCESS

若 5 秒内未响应，平台将重试。响应必须是纯字符串 SUCCESS——不得包装为 JSON 或其他格式。


2.2 争议查询(dispute.query)

2.2.1 接口信息

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

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

2.2.2 请求参数

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

2.2.3 请求示例

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

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

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

2.2.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交易金额（两位小数字符串）

2.2.5 响应示例

  • 单笔查询：

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "listItems": "1",
    "data": [
        {
            "disputeInfo": {
                "caseNo": "2025052015150461400351",
                "disputeMode": "DEFENSE_INFO",
                "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": "DEFENSE_INFO",
                "status": "caseCompleted",
                "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 可能为空对象 {}。


2.3 抗辩操作（dispute.defend）

2.3.1 接口信息

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

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

2.3.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

2.3.3 请求示例

  • ACCEPT_DISPUTE_RESULT：

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

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

  • DEFENSE_DOCUMENT_UPDATE：

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

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

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

2.3.4 响应参数

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

2.3.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 2 hours ago

Did this page help you?