争议

接口地址

测试环境基础地址

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{}

通用响应

字段类型说明
codestring成功为 0,失败返回错误码
msgstring结果说明
serverTimestring服务端毫秒时间戳
successboolean是否成功
dataobject业务结果

查询争议资格

接口

POST /eligibility

请求参数

参数类型必填说明
transactionIdstring是交易编号

请求示例

{
  "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"
  }
}
字段类型说明
transactionIdstring交易编号
eligibleboolean是否满足创建新争议的条件
reasonCodestring不满足条件时的原因码
disputeIdstring已有争议的编号
amountstring当前可争议金额
currencystring币种

仅已清算的消费交易可以创建争议。全额退款或已有争议时不可重复创建;部分退款后,按剩余金额处理。

创建争议

接口

POST /create

请求参数

参数类型必填说明
transactionIdstring是交易编号
reasonstring是争议原因,见下表
evidenceobject是按原因填写对应证据对象
evidence.fraudobject条件必填FRAUD 对应的证据
evidence.notReceivedobject条件必填NOT_RECEIVED 对应的证据
evidence.notAsDescribedobject条件必填NOT_AS_DESCRIBED 对应的证据
evidence.duplicateobject条件必填DUPLICATE 对应的证据
evidence.canceledobject条件必填CANCELED 对应的证据
evidence.otherobject条件必填OTHER 对应的证据
additionalDocumentationstring[]否补充文档,最多 1 个文件 ID
evidence.duplicate.cashReceiptstring[]条件必填cash_receipt 对应文件,最多 1 个文件 ID
evidence.duplicate.checkImagestring[]条件必填check_photo 对应文件,最多 1 个文件 ID
evidence.duplicate.cardStatementstring[]条件必填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。

争议响应对象

创建、更新证据、详情、正式提交以及分页列表项使用同一对象。

字段类型说明
idstring争议编号
transactionIdstring关联交易编号
cardIdstring卡片编号
cardholderIdstring持卡人编号
cardLast4string卡号后四位
amountstring争议金额
returnedAmountstring实际返还金额
currencystring币种
statusstring争议状态,见下表
reasonstring争议原因
submitDeadlinestring最晚正式提交时间
submittedAtstring正式提交时间
closedAtstring争议结束时间
createdAtstring创建时间
updatedAtstring修改时间
evidenceobject证据对象,结构与请求一致
evidence.fraudobjectFRAUD 的证据,字段与请求一致
evidence.notReceivedobjectNOT_RECEIVED 的证据,字段与请求一致
evidence.notAsDescribedobjectNOT_AS_DESCRIBED 的证据,字段与请求一致
evidence.duplicateobjectDUPLICATE 的证据,字段与请求一致
evidence.canceledobjectCANCELED 的证据,字段与请求一致
evidence.otherobjectOTHER 的证据,字段与请求一致
additionalDocumentationstring[]补充文档文件 ID
evidence.duplicate.cashReceiptstring[]现金收据文件 ID
evidence.duplicate.checkImagestring[]支票照片文件 ID
evidence.duplicate.cardStatementstring[]银行卡对账单文件 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

请求参数

参数类型必填说明
idstring否争议编号,精确筛选
transactionIdstring否交易编号
cardIdstring否卡片编号,包含换卡前后的关联争议
cardholderIdstring否持卡人编号
statusstring否UNSUBMITTED / SUBMITTED / WON / LOST / EXPIRED
keywordstring否按争议编号、卡片编号或持卡人编号搜索
startDatestring否创建时间起点,yyyy-MM-dd HH:mm:ss
endDatestring否创建时间终点,yyyy-MM-dd HH:mm:ss
pageNuminteger否页码,默认 1
pageSizeinteger否每页条数,默认 20,最大 100

请求示例

{
  "status": "UNSUBMITTED",
  "pageNum": 1,
  "pageSize": 20
}

响应

data 包含 pageNum、pageSize、total、totalPage、list;list 中每项为完整争议对象。

查询争议详情

接口

POST /{id}/detail

请求示例

{}

响应

data 返回争议对象。

更新证据

接口

POST /{id}/evidence

请求参数

参数类型必填说明
reasonstring否修改争议原因
evidenceobject是对应原因的完整证据,字段要求与创建相同
evidence.fraudobject按原因必填FRAUD 完整证据
evidence.notReceivedobject按原因必填NOT_RECEIVED 完整证据
evidence.notAsDescribedobject按原因必填NOT_AS_DESCRIBED 完整证据
evidence.duplicateobject按原因必填DUPLICATE 完整证据
evidence.canceledobject按原因必填CANCELED 完整证据
evidence.otherobject按原因必填OTHER 完整证据
additionalDocumentationstring[]否补充文档,最多 1 个文件 ID
evidence.duplicate.cashReceiptstring[]条件必填cash_receipt 对应文件,最多 1 个文件 ID
evidence.duplicate.checkImagestring[]条件必填check_photo 对应文件,最多 1 个文件 ID
evidence.duplicate.cardStatementstring[]条件必填bank_statement 对应文件,最多 1 个文件 ID

填写与争议原因对应的一个完整证据对象,必填字段每次修改均须提供。证据字段不再沿用旧值。附件字段不传保留原附件,传 [] 清空对应附件。

仅 status=UNSUBMITTED 时允许修改证据;正在提交或超过 submitDeadline 时不可修改。SUBMITTED、WON、LOST、EXPIRED 均不可修改。

请求示例

{
  "evidence": {
    "fraud": {
      "explanation": "已补充持卡人情况说明。"
    }
  }
}

响应

data 返回更新后的争议对象。

证据对象

按 reason 填写对应的一个证据对象。传入其他原因的证据对象会报错,包括空对象 {}。

evidence.fraud(FRAUD)

字段类型说明
explanationstring争议情况说明,最长 10000 字符

evidence.notReceived(NOT_RECEIVED)

字段类型说明
productTypestringmerchandise:商品;service:线下服务
productDescriptionstring商品或服务描述,最长 5000 字符
expectedDatestring预计收到日期,yyyy-MM-dd
explanationstring争议情况说明,最长 10000 字符

evidence.notAsDescribed(NOT_AS_DESCRIBED)

字段类型说明
productTypestringmerchandise:商品;service:线下服务
receivedDatestring实际收到日期,yyyy-MM-dd,不得晚于当前日期
returnStatusstringreturned:商家接受退货;refused:商家拒绝退货
returnDatestring退货日期,yyyy-MM-dd,不得晚于当前日期
returnDescriptionstring退货情况说明,最长 5000 字符
cancelDatestring取消日期,yyyy-MM-dd,不得晚于当前日期
cancelReasonstring取消原因,最长 5000 字符
explanationstring争议情况说明,最长 10000 字符

evidence.duplicate(DUPLICATE)

字段类型说明
paymentProofTypestringcash_receipt:现金收据;check_photo:支票照片;issuing_transaction_id:原消费交易;bank_statement:银行账单
originalTransactionIdstring重复扣款对应的原消费交易编号
explanationstring争议情况说明,最长 10000 字符

evidence.canceled(CANCELED)

字段类型说明
productTypestringmerchandise:商品;service:线下服务
productDescriptionstring商品或服务描述,最长 5000 字符
expectedDatestring预计收到日期,yyyy-MM-dd
returnStatusstringreturned:商家接受退货;refused:商家拒绝退货
returnDatestring退货日期,yyyy-MM-dd,不得晚于当前日期
returnDescriptionstring退货情况说明,最长 5000 字符
policyCompliancestringcompliant:符合政策;no_policy:没有政策;non_compliant:不符合政策
cancelDatestring取消日期,yyyy-MM-dd,不得晚于当前日期
cancelReasonstring取消原因,最长 5000 字符
explanationstring争议情况说明,最长 10000 字符

evidence.other(OTHER)

字段类型说明
productTypestringmerchandise:商品;service:线下服务
productDescriptionstring商品或服务描述,最长 5000 字符
explanationstring争议情况说明,最长 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正式提交失败

Did this page help you?