争议
接口地址
测试环境基础地址
https://api.futurepay-develop.com/api/v1/issuing/dispute生产环境基础地址
https://api.futurepay.global/api/v1/issuing/dispute接口目录
| 功能 | 请求方式 | 接口路径 | 请求体 |
|---|---|---|---|
| 查询争议资格 | POST | /eligibility | 交易编号 |
| 创建争议 | POST | /create | 创建参数 |
| 查询争议分页列表 | POST | /paging | 分页及筛选参数,或 {} |
| 查询争议详情 | POST | /{id}/detail | {} |
| 更新证据 | POST | /{id}/evidence | 证据更新参数 |
| 正式提交 | POST | /{id}/submit | {} |
通用响应
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 成功为 0,失败返回错误码 |
| msg | string | 结果说明 |
| serverTime | string | 服务端毫秒时间戳 |
| success | boolean | 是否成功 |
| data | object | 业务结果 |
查询争议资格
接口
POST /eligibility请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| transactionId | string | 是 | 交易编号 |
请求示例
{
"transactionId": "TXN_EXAMPLE"
}响应示例
{
"code": "0",
"msg": "succeeded",
"serverTime": "1794614400000",
"success": true,
"data": {
"transactionId": "TXN_EXAMPLE",
"eligible": true,
"reasonCode": null,
"disputeId": null,
"amount": "20.00",
"currency": "USD"
}
}| 字段 | 类型 | 说明 |
|---|---|---|
| transactionId | string | 交易编号 |
| eligible | boolean | 是否满足创建新争议的条件 |
| reasonCode | string | 不满足条件时的原因码 |
| disputeId | string | 已有争议的编号 |
| amount | string | 当前可争议金额 |
| currency | string | 币种 |
仅已清算的消费交易可以创建争议。全额退款或已有争议时不可重复创建;部分退款后,按剩余金额处理。
创建争议
接口
POST /create请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| transactionId | string | 是 | 交易编号 |
| reason | string | 是 | 争议原因,见下表 |
| evidence | object | 是 | 按原因填写对应证据对象 |
| evidence.fraud | object | 条件必填 | FRAUD 对应的证据 |
| evidence.notReceived | object | 条件必填 | NOT_RECEIVED 对应的证据 |
| evidence.notAsDescribed | object | 条件必填 | NOT_AS_DESCRIBED 对应的证据 |
| evidence.duplicate | object | 条件必填 | DUPLICATE 对应的证据 |
| evidence.canceled | object | 条件必填 | CANCELED 对应的证据 |
| evidence.other | object | 条件必填 | OTHER 对应的证据 |
| additionalDocumentation | string[] | 否 | 补充文档,最多 1 个文件 ID |
| evidence.duplicate.cashReceipt | string[] | 条件必填 | cash_receipt 对应文件,最多 1 个文件 ID |
| evidence.duplicate.checkImage | string[] | 条件必填 | check_photo 对应文件,最多 1 个文件 ID |
| evidence.duplicate.cardStatement | string[] | 条件必填 | bank_statement 对应文件,最多 1 个文件 ID |
争议原因
| reason | 含义 |
|---|---|
| FRAUD | 持卡人未授权的消费 |
| NOT_RECEIVED | 未收到商品或服务 |
| NOT_AS_DESCRIBED | 商品或服务与描述不符 |
| DUPLICATE | 重复扣款 |
| CANCELED | 商品或服务已取消但仍被扣款 |
| OTHER | 其他原因 |
请求示例
{
"transactionId": "TXN_EXAMPLE",
"reason": "FRAUD",
"additionalDocumentation": [
"0123456789abcdef0123456789abcdef.pdf"
],
"evidence": {
"fraud": {
"explanation": "持卡人确认未进行此笔消费。"
}
}
}响应
data 返回争议对象,初始 status 为 UNSUBMITTED。
争议响应对象
创建、更新证据、详情、正式提交以及分页列表项使用同一对象。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 争议编号 |
| transactionId | string | 关联交易编号 |
| cardId | string | 卡片编号 |
| cardholderId | string | 持卡人编号 |
| cardLast4 | string | 卡号后四位 |
| amount | string | 争议金额 |
| returnedAmount | string | 实际返还金额 |
| currency | string | 币种 |
| status | string | 争议状态,见下表 |
| reason | string | 争议原因 |
| submitDeadline | string | 最晚正式提交时间 |
| submittedAt | string | 正式提交时间 |
| closedAt | string | 争议结束时间 |
| createdAt | string | 创建时间 |
| updatedAt | string | 修改时间 |
| evidence | object | 证据对象,结构与请求一致 |
| evidence.fraud | object | FRAUD 的证据,字段与请求一致 |
| evidence.notReceived | object | NOT_RECEIVED 的证据,字段与请求一致 |
| evidence.notAsDescribed | object | NOT_AS_DESCRIBED 的证据,字段与请求一致 |
| evidence.duplicate | object | DUPLICATE 的证据,字段与请求一致 |
| evidence.canceled | object | CANCELED 的证据,字段与请求一致 |
| evidence.other | object | OTHER 的证据,字段与请求一致 |
| additionalDocumentation | string[] | 补充文档文件 ID |
| evidence.duplicate.cashReceipt | string[] | 现金收据文件 ID |
| evidence.duplicate.checkImage | string[] | 支票照片文件 ID |
| evidence.duplicate.cardStatement | string[] | 银行卡对账单文件 ID |
| status | 含义 |
|---|---|
| UNSUBMITTED | 尚未正式提交成功 |
| SUBMITTED | 已正式提交,等待处理 |
| WON | 争议胜诉 |
| LOST | 争议败诉 |
| EXPIRED | 争议已过期 |
时间格式为 yyyy-MM-dd HH:mm:ss。
响应示例
{
"code": "0",
"msg": "succeeded",
"serverTime": "1794614400000",
"success": true,
"data": {
"id": "DISPUTE202611140001",
"transactionId": "TXN_EXAMPLE",
"cardId": "ic_EXAMPLE",
"cardholderId": "ich_EXAMPLE",
"cardLast4": "0435",
"amount": "20.00",
"returnedAmount": null,
"currency": "USD",
"status": "UNSUBMITTED",
"reason": "FRAUD",
"submitDeadline": "2027-02-12 00:00:00",
"submittedAt": null,
"closedAt": null,
"createdAt": "2026-11-14 00:00:00",
"updatedAt": null,
"additionalDocumentation": ["0123456789abcdef0123456789abcdef.pdf"],
"evidence": {
"fraud": {
"explanation": "持卡人确认未进行此笔消费。"
}
}
}
}查询争议分页列表
接口
POST /paging请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 争议编号,精确筛选 |
| transactionId | string | 否 | 交易编号 |
| cardId | string | 否 | 卡片编号,包含换卡前后的关联争议 |
| cardholderId | string | 否 | 持卡人编号 |
| status | string | 否 | UNSUBMITTED / SUBMITTED / WON / LOST / EXPIRED |
| keyword | string | 否 | 按争议编号、卡片编号或持卡人编号搜索 |
| startDate | string | 否 | 创建时间起点,yyyy-MM-dd HH:mm:ss |
| endDate | string | 否 | 创建时间终点,yyyy-MM-dd HH:mm:ss |
| pageNum | integer | 否 | 页码,默认 1 |
| pageSize | integer | 否 | 每页条数,默认 20,最大 100 |
请求示例
{
"status": "UNSUBMITTED",
"pageNum": 1,
"pageSize": 20
}响应
data 包含 pageNum、pageSize、total、totalPage、list;list 中每项为完整争议对象。
查询争议详情
接口
POST /{id}/detail请求示例
{}响应
data 返回争议对象。
更新证据
接口
POST /{id}/evidence请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reason | string | 否 | 修改争议原因 |
| evidence | object | 是 | 对应原因的完整证据,字段要求与创建相同 |
| evidence.fraud | object | 按原因必填 | FRAUD 完整证据 |
| evidence.notReceived | object | 按原因必填 | NOT_RECEIVED 完整证据 |
| evidence.notAsDescribed | object | 按原因必填 | NOT_AS_DESCRIBED 完整证据 |
| evidence.duplicate | object | 按原因必填 | DUPLICATE 完整证据 |
| evidence.canceled | object | 按原因必填 | CANCELED 完整证据 |
| evidence.other | object | 按原因必填 | OTHER 完整证据 |
| additionalDocumentation | string[] | 否 | 补充文档,最多 1 个文件 ID |
| evidence.duplicate.cashReceipt | string[] | 条件必填 | cash_receipt 对应文件,最多 1 个文件 ID |
| evidence.duplicate.checkImage | string[] | 条件必填 | check_photo 对应文件,最多 1 个文件 ID |
| evidence.duplicate.cardStatement | string[] | 条件必填 | bank_statement 对应文件,最多 1 个文件 ID |
填写与争议原因对应的一个完整证据对象,必填字段每次修改均须提供。证据字段不再沿用旧值。附件字段不传保留原附件,传 [] 清空对应附件。
仅 status=UNSUBMITTED 时允许修改证据;正在提交或超过 submitDeadline 时不可修改。SUBMITTED、WON、LOST、EXPIRED 均不可修改。
请求示例
{
"evidence": {
"fraud": {
"explanation": "已补充持卡人情况说明。"
}
}
}响应
data 返回更新后的争议对象。
证据对象
按 reason 填写对应的一个证据对象。传入其他原因的证据对象会报错,包括空对象 {}。
evidence.fraud(FRAUD)
| 字段 | 类型 | 说明 |
|---|---|---|
| explanation | string | 争议情况说明,最长 10000 字符 |
evidence.notReceived(NOT_RECEIVED)
| 字段 | 类型 | 说明 |
|---|---|---|
| productType | string | merchandise:商品;service:线下服务 |
| productDescription | string | 商品或服务描述,最长 5000 字符 |
| expectedDate | string | 预计收到日期,yyyy-MM-dd |
| explanation | string | 争议情况说明,最长 10000 字符 |
evidence.notAsDescribed(NOT_AS_DESCRIBED)
| 字段 | 类型 | 说明 |
|---|---|---|
| productType | string | merchandise:商品;service:线下服务 |
| receivedDate | string | 实际收到日期,yyyy-MM-dd,不得晚于当前日期 |
| returnStatus | string | returned:商家接受退货;refused:商家拒绝退货 |
| returnDate | string | 退货日期,yyyy-MM-dd,不得晚于当前日期 |
| returnDescription | string | 退货情况说明,最长 5000 字符 |
| cancelDate | string | 取消日期,yyyy-MM-dd,不得晚于当前日期 |
| cancelReason | string | 取消原因,最长 5000 字符 |
| explanation | string | 争议情况说明,最长 10000 字符 |
evidence.duplicate(DUPLICATE)
| 字段 | 类型 | 说明 |
|---|---|---|
| paymentProofType | string | cash_receipt:现金收据;check_photo:支票照片;issuing_transaction_id:原消费交易;bank_statement:银行账单 |
| originalTransactionId | string | 重复扣款对应的原消费交易编号 |
| explanation | string | 争议情况说明,最长 10000 字符 |
evidence.canceled(CANCELED)
| 字段 | 类型 | 说明 |
|---|---|---|
| productType | string | merchandise:商品;service:线下服务 |
| productDescription | string | 商品或服务描述,最长 5000 字符 |
| expectedDate | string | 预计收到日期,yyyy-MM-dd |
| returnStatus | string | returned:商家接受退货;refused:商家拒绝退货 |
| returnDate | string | 退货日期,yyyy-MM-dd,不得晚于当前日期 |
| returnDescription | string | 退货情况说明,最长 5000 字符 |
| policyCompliance | string | compliant:符合政策;no_policy:没有政策;non_compliant:不符合政策 |
| cancelDate | string | 取消日期,yyyy-MM-dd,不得晚于当前日期 |
| cancelReason | string | 取消原因,最长 5000 字符 |
| explanation | string | 争议情况说明,最长 10000 字符 |
evidence.other(OTHER)
| 字段 | 类型 | 说明 |
|---|---|---|
| productType | string | merchandise:商品;service:线下服务 |
| productDescription | string | 商品或服务描述,最长 5000 字符 |
| explanation | string | 争议情况说明,最长 10000 字符 |
各原因必填字段
以下字段位于各原因对应的证据对象内,创建、修改及正式提交均按此校验。
| reason | 产品类型 | 必填字段 |
|---|---|---|
| FRAUD | — | explanation |
| NOT_RECEIVED | 商品、线下服务 | productType、productDescription、expectedDate、explanation |
| NOT_AS_DESCRIBED | 商品 | productType、receivedDate、returnStatus、explanation;已退回时还需 returnDate、returnDescription |
| NOT_AS_DESCRIBED | 线下服务 | productType、receivedDate、cancelDate、cancelReason、explanation |
| DUPLICATE | — | paymentProofType、explanation;须提供所选类型的证明文件,选择 issuing_transaction_id 时须提供 originalTransactionId |
| CANCELED | 商品 | productType、productDescription、expectedDate、returnStatus、policyCompliance、cancelDate、cancelReason、explanation;已退回时还需 returnDate、returnDescription |
| CANCELED | 线下服务 | productType、productDescription、expectedDate、policyCompliance、cancelDate、cancelReason、explanation |
| OTHER | 商品、线下服务 | productType、productDescription、explanation |
证据文件通过现有上传接口 /api/v1/issuing/reference/upload 上传。
附件字段
additionalDocumentation 位于请求外层,选填。付款证明文件位于 evidence.duplicate 内,所选证明类型对应的文件必填。各附件数组最多 1 个文件 ID,使用上传接口返回的 data.path。
| 字段 | 用途 | 适用条件 |
|---|---|---|
| additionalDocumentation | 补充文档 | 所有争议原因 |
| evidence.duplicate.cashReceipt | 现金收据 | DUPLICATE,paymentProofType=cash_receipt 时必填 |
| evidence.duplicate.checkImage | 支票照片 | DUPLICATE,paymentProofType=check_photo 时必填 |
| evidence.duplicate.cardStatement | 银行卡对账单 | DUPLICATE,paymentProofType=bank_statement 时必填 |
修改原因或付款证明类型后,不再适用的原付款证明附件会移除,补充文档保留。
重复扣款示例
{
"transactionId": "TXN_EXAMPLE",
"reason": "DUPLICATE",
"additionalDocumentation": [],
"evidence": {
"duplicate": {
"paymentProofType": "cash_receipt",
"cashReceipt": ["0123456789abcdef0123456789abcdef.jpg"],
"explanation": "同一订单已付现金,又被扣款。"
}
}
}与描述不符:商品
{
"transactionId": "TXN_EXAMPLE",
"reason": "NOT_AS_DESCRIBED",
"evidence": {
"notAsDescribed": {
"productType": "merchandise",
"receivedDate": "2026-11-14",
"returnStatus": "returned",
"returnDate": "2026-11-15",
"returnDescription": "已通过快递寄回商家。",
"explanation": "收到的商品型号与订单不符,已退回。"
}
}
}与描述不符:线下服务
{
"transactionId": "TXN_EXAMPLE",
"reason": "NOT_AS_DESCRIBED",
"evidence": {
"notAsDescribed": {
"productType": "service",
"receivedDate": "2026-11-14",
"cancelDate": "2026-11-15",
"cancelReason": "服务内容与约定不符。",
"explanation": "实际提供的服务项目与订单不一致,已取消。"
}
}
}正式提交
接口
POST /{id}/submit请求示例
{}响应
data 返回最新争议对象。
正式提交会校验证据并收取争议费。
提交成功后,status 为 SUBMITTED,证据不可修改。处理结束后为 WON、LOST 或 EXPIRED。
超过 submitDeadline 不可提交。
争议通知
通知类型
| eventCode | 说明 |
|---|---|
| VCC_DISPUTE_RESULT_NOTIFY | 争议结果通知,当前状态见 status |
通知示例
{
"merchantId": "1929723739654762496",
"notificationItems": [
{
"eventCode": "VCC_DISPUTE_RESULT_NOTIFY",
"eventDate": 1795084568000,
"id": "DISPUTE_EXAMPLE",
"transactionId": "TXN_EXAMPLE",
"cardId": "ic_EXAMPLE",
"cardholderId": "ich_EXAMPLE",
"cardLast4": "0435",
"amount": "20.00",
"returnedAmount": null,
"currency": "USD",
"status": "WON",
"reason": "FRAUD",
"submitDeadline": "2027-02-17 09:58:41",
"submittedAt": "2026-11-19 10:00:00",
"closedAt": "2026-11-20 10:00:00",
"createdAt": "2026-11-19 09:58:40",
"updatedAt": "2026-11-20 10:00:00",
"evidence": {
"fraud": {
"explanation": "持卡人确认未进行此笔消费。"
}
},
"additionalDocumentation": []
}
]
}常见错误
| code | 说明 |
|---|---|
| TRANSACTION_NOT_FOUND | 交易不存在或无权访问 |
| DISPUTE_NOT_FOUND | 争议不存在或无权访问 |
| DISPUTE_ALREADY_EXISTS | 当前交易已有争议 |
| DISPUTE_TRANSACTION_INVALID | 当前交易不允许发起争议 |
| DISPUTE_FULLY_REFUNDED | 交易已全额退款 |
| DISPUTE_DRAFT_NOT_EDITABLE | 争议当前不可修改 |
| API_FILE_NOT_FOUND | 文件不存在或无权使用 |
| DISPUTE_FILE_PURPOSE_DUPLICATED | 同一文件用途重复 |
| DISPUTE_CANCEL_CARD_REASON_INVALID | 只有 FRAUD 可以要求注销关联卡 |
| DISPUTE_ALREADY_SUBMITTED | 已提交,不可重复提交 |
| DISPUTE_SUBMIT_IN_PROGRESS | 争议正在提交 |
| DISPUTE_SUBMIT_DEADLINE_EXPIRED | 已超过最晚提交时间 |
| DISPUTE_CARD_CANCEL_FAILED | 关联卡注销失败 |
| DISPUTE_FEE_INSUFFICIENT | 余额不足以支付争议费 |
| DISPUTE_SUBMIT_FAILED | 正式提交失败 |
Updated about 11 hours ago