拒付预警通知

本文档介绍如何接收和处理争议预警通知。Onerway会通过Webhook方式实时推送争议预警信息，帮助商户在潜在争议成为正式拒付前识别并响应威胁，减少经济损失并改善争议预防效果。

术语说明

拒付预警通知（Pre-Dispute Notification，也称为拒付预警）是在正式争议或拒付提交之前发送的早期预警信号。这种主动方式允许商户采取预防措施，避免正式争议流程的成本和复杂性。

功能说明

拒付预警通知服务能够：

实时推送争议风险预警信息
早期检测潜在争议活动
提供详细的交易和预警原因数据
主动争议预防能力
与主要争议预警服务集成
提供全面的预警元数据用于风险评估

通知接收配置

要接收拒付预警通知，商户需要在Onerway商户后台配置 Webhook URL。系统会将拒付预警信息以 HTTP POST 方式推送到该URL。配置步骤如下：

登录Onerway商户后台
导航至"开发者" > "通知设定"
配置"拒付预警通知"的接收地址（Webhook URL）
测试通知接收是否正常工作

预警服务提供商

预警服务

拒付预警服务由第三方风险管理公司提供：

Ethoca Alerts - 实时争议预防网络
Verifi RDR - 快速争议解决服务
定制预警服务 - 请联系Onerway获取

要启用特定预警服务，请联系您的Onerway客户经理。

通知示例

拒付预警通知响应

json

{
  "notifyType": "PRE_DISPUTE",                           // 通知类型
  "transactionId": "1948584185883394048",                // 预警交易ID
  "merchantNo": "800626",                                // 商户号
  "timeZone": "+08:00",                                  // 时间戳时区
  "predisputeId": "1948584185883394048",                 // 预警ID
  "service": null,                                       // 预警服务提供商（可选）
  "type": null,                                          // 服务类型（可选）
  "createdTime": "2025-07-25 10:21:06",                 // 预警创建时间
  "receivedTime": "2025-07-25 11:20:48",                // Onerway接收时间
  "amount": "0.01",                                      // 预警金额
  "currency": "GBP",                                     // 预警货币
  "source": "Issuer",                                   // 预警来源
  "reasonCode": "10.1",                                 // 原因代码
  "txnId": "1948582879735185408",                       // 原始交易ID
  "merchantTxnId": "1753413333000",                     // 商户交易ID
  "txnTime": "2025-07-25 11:15:36",                     // 原始交易时间
  "orderAmount": "15.40",                               // 原始订单金额
  "orderCurrency": "USD",                               // 原始订单货币
  "paymentMethod": "VISA",                              // 支付方式
  "chargebackStatus": "0",                              // 当前拒付状态
  "refundStatus": "0",                                  // 当前退款状态
  "eci": null,                                          // 电子商务指示符
  "website": "voidmain",                                // 交易网站
  "email": "",                                          // 客户邮箱
  "sign": "15ad79c150560aa07baffd32f1e0ac0088af7acc00cb9b4f8d46563139e906f5"  // 签名
}

json

1948584185883394048 // transactionId

通知字段说明

Parameter	Type	Length	Signed	Description
amount	String	19	Yes	Pre-dispute alert amount.
chargebackStatus	String	/	Yes	Chargeback status indicating dispute activity.
createdTime	String	/	Yes	Alert creation time by alert service provider. Format: `yyyy-MM-dd HH:mm:ss`
currency	String	8	Yes	Pre-dispute alert currency. See ISO 4217 currency codes
eci	String	/	Yes	Electronic Commerce Indicator for 3DS authentication status.
email	String	256	Yes	Customer email address for transaction notifications and receipts.
merchantNo	String	20	Yes	Merchant number assigned by `Onerway` upon registration, obtained from the `Onerway` merchant dashboard.
merchantTxnId	String	64	Yes	Unique transaction identifier for each customer payment, generated by the merchant system.
notifyType	String	/	Yes	Notification type identifying the business scenario. See NotifyTypeEnum for all available types.
orderAmount	String	19	Yes	Transaction amount in the specified currency, formatted as a decimal string.
orderCurrency	String	8	Yes	Three-letter currency code according to ISO 4217 standard for the transaction amount.
paymentMethod	String	/	Yes	Specific payment method used for the transaction.
predisputeId	String	20	Yes	Pre-dispute alert ID generated by Onerway.
reasonCode	String	32	Yes	Pre-dispute alert reason code. See Pre-Dispute Alert Reason Codes
receivedTime	String	/	Yes	Time when Onerway received the alert. Format: `yyyy-MM-dd HH:mm:ss`
refundStatus	String	/	Yes	Current refund status of the transaction.
service	String	64	No	Alert service provider.
sign	String	/	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
source	String	64	Yes	Alert source.
timeZone	String	/	Yes	Time zone for time-related fields in this notification.
transactionId	String	20	Yes	Pre-dispute alert transaction ID generated by Onerway.
txnId	String	20	Yes	Original transaction ID from Onerway.
txnTime	String	/	Yes	Original transaction completion time. Format: `yyyy-MM-dd HH:mm:ss`
type	String	64	No	Alert service type.
website	String	256	Yes	Transaction website domain where the pre-dispute alert occurred.

通知处理流程

通知重试策略

Onerway实施自动重试机制，确保拒付预警通知的可靠传递：

重试策略

如果预警接口地址调用失败或者商户未能正确响应transactionId，Onerway将自动重试通知总共3次，每次间隔30分钟。

重试时间表：

初次尝试：立即发送
第1次重试：初次失败后30分钟
第2次重试：第1次重试失败后30分钟
最终尝试：第2次重试失败后30分钟

最终重试尝试失败后，将不再为该特定预警发送通知。

确保成功送达

为防止不必要的重试并确保正确处理预警：

实施正确的响应格式
- 始终响应通知的transactionId
- 返回HTTP状态码200表示成功处理
监控Webhook端点健康状况
- 确保您的端点可访问且响应正常
- 实施适当的错误处理和日志记录
设置监控
- 跟踪通知接收和处理情况
- 对失败的webhook传递进行告警
- 监控响应时间和错误率

预警响应策略

立即评估

收到拒付预警通知时：

验证预警真实性
- 验证通知签名
- 确认交易详情与您的记录匹配
- 检查预警原因代码的重要性
分析风险级别
- 审查 reasonCode 的争议类别
- 评估交易特征和客户历史
- 评估潜在争议责任
确定响应策略
- 考虑对高风险案例进行预防性退款
- 启动客户联系进行解决
- 为潜在正式争议准备文档

响应选项

响应策略

预防性退款

立即退款以预防正式争议
对欺诈相关预警最有效
减少争议费用和比率影响

客户参与

联系客户解决根本问题
提供额外的交易详情或收据
在争议升级前协商解决

文档准备

收集全面的交易证据
准备有说服力的案例材料
加强潜在争议防御的地位

监控和等待

跟踪预警状态的发展
保持快速响应的准备
适用于较低风险的情况

原因代码类别

了解预警原因代码有助于确定最佳响应策略。各卡网络使用不同的编码系统，具有不同的优先级和建议行动。

快速参考指南

卡网络	代码格式	主要类别	欺诈指示符
VISA	分层数字（`10.x`、`11.x`）	4个主要类别（10-13）	`10.x`系列
MasterCard	字母数字混合（`FR4`、`C02`、`37`）	系列式（FR、C、P、R + 数字）	`FR`系列
Discover	主要为字母（`UA01`、`RG`）	功能式（UA、RG、DP等）	`UA`系列

VISA原因代码

分层数字系统，组织为主要类别

🚨 严重 - 欺诈类别（10.x系列）

EMV责任转移（10.1、10.2）- 伪造/非伪造欺诈
环境欺诈（10.3、10.4）- 卡存在/缺失欺诈
监控程序（10.5）- VISA欺诈监控违规

📊 优先级：🔴 严重 | ⚡ 行动：考虑立即预防性退款

⚠️ 高优先级 - 授权类别（11.x系列）

卡片回收（11.1）- 卡片回收公告问题
授权问题（11.2、11.3）- 授权被拒或缺失

📊 优先级：🟠 高 | 🔍 行动：审查授权记录和流程

🔧 中等优先级 - 处理与消费者问题

处理错误（12.x系列）

技术问题：迟延提交、数据错误、重复处理

消费者争议（13.x系列）

服务/商品问题、取消、退款问题

📊 优先级：🟡 中等 | 🤝 行动：流程审查和客户参与

MasterCard原因代码

跨多个专业系列的字母数字代码

🚨 严重 - 欺诈系列

FR2 - 欺诈完全追偿计划
FR4 - 即时拒付计划
FR6 - 部分即时拒付计划

📊 优先级：🔴 严重 | ⚡ 行动：考虑立即预防性退款

⚠️ 高优先级 - 消费者与处理问题

消费者争议（C系列）

C02、C04、C05、C08 - 退款/商品/服务问题

处理错误（P系列）

P01、P03、P04、P05 - 技术处理错误

数字代码

8、12、31、34、37 - 授权、账户、欺诈问题

📊 优先级：🟠 高至 🟡 中等 | 🔍 行动：基于上下文的响应

Discover原因代码

带特定欺诈指示符的字母代码

🚨 严重 - 欺诈系列

UA01 - 欺诈（卡存在交易）
UA02 - 欺诈（卡不存在交易）
UA03 - 欺诈（处理错误）

📊 优先级：🔴 严重 | ⚡ 行动：考虑立即预防性退款

⚠️ 中到高优先级 - 服务与处理问题

服务问题

RG - 未收到商品/服务
RM - 质量争议
RN2 - 未处理退款

处理问题

DP - 重复记录
LP - 迟延提交
CD、AW - 退款/金额变更

一般争议

AA、AT、AP、CR - 识别、授权、循环付款

📊 优先级：🟠 高至 🟡 中等 | 🤝 行动：客户参与和流程审查

📚 完整参考

有关详细原因代码描述和全面的卡网络特定信息，请参阅拒付预警原因代码 →

预警管理最佳实践

主动监控

预防策略

设置实时预警：为关键预警配置即时通知
实施自动化工作流程：为常见预警场景创建规则
监控预警模式：跟踪预警频率和类型进行趋势分析
维护响应SLA：为不同预警类别建立目标响应时间

文档标准

保存预警数据：存储所有预警信息用于分析和报告
跟踪响应行动：记录响应预警采取的所有步骤
维护客户沟通：保留客户互动记录
监控结果：跟踪预警是否导致实际拒付

集成考虑

CRM集成：将预警链接到客户管理系统
风险评分：将预警纳入欺诈检测算法
自动退款：设置自动退款处理规则
报告仪表板：创建预警性能指标的可见性

常见错误场景

签名无效

问题：通知签名验证失败
解决方案：验证您的webhook端点使用正确的密钥

缺少交易数据

问题：在您的系统中找不到引用的交易
解决方案：检查交易ID映射和数据同步

重复通知

问题：收到同一预警的多个通知
原因：

Webhook端点未响应必需的 transactionId
响应格式不正确或缺失
网络问题导致重试尝试

解决方案：

确保您的webhook端点响应通知的 transactionId 以确认收到
使用 transactionId 或 predisputeId 实施幂等性检查
返回正确的HTTP状态码（200）和必需的响应格式
参见通知重试策略了解重试机制详情

服务配置问题

问题：service 和 type 字段为空
解决方案：联系Onerway启用特定预警服务配置

实施检查清单

实施前

配置Webhook URL：在Onerway后台设置端点
实施签名验证：确保通知真实性
设置预警路由：定义预警如何到达适当团队
建立响应程序：为不同预警类型创建工作流程

实施后

监控预警量：跟踪通知频率和模式
衡量响应效果：分析拒付预防率
优化工作流程：基于结果改进响应策略
定期测试：验证通知传递和处理

性能监控

响应时间跟踪：监控预警处理速度
预防率分析：衡量拒付预防成功率
成本效益评估：评估退款成本与拒付节省
趋势分析：识别预警类型和客户行为模式

与Onerway服务集成

使用Onerway的拒付预警服务时，此通知系统与以下服务无缝集成：

欺诈通知服务 - 全面欺诈检测
拒付查询API - 历史拒付数据
交易查询API - 交易数据查询
交易通知 - 支付状态更新

有关实施全面拒付预防策略的更多信息，请联系您的Onerway客户经理。

收银台

下单

WebSDK

Android

绑卡支付

本地支付

Ethoca

RDR

拒付预警通知

功能说明

通知接收配置

预警服务提供商

通知示例

通知字段说明

通知处理流程

通知重试策略

确保成功送达

预警响应策略

立即评估

响应选项

原因代码类别

快速参考指南

VISA原因代码

MasterCard原因代码

Discover原因代码

预警管理最佳实践

主动监控

文档标准

集成考虑

常见错误场景

签名无效

缺少交易数据

重复通知

服务配置问题

实施检查清单

实施前

实施后

性能监控

与Onerway服务集成

收银台

下单

WebSDK

Android

绑卡支付

本地支付

拒付预警通知 ​

功能说明 ​

通知接收配置 ​

预警服务提供商 ​

通知示例 ​

通知字段说明 ​

通知处理流程 ​

通知重试策略 ​

确保成功送达 ​

预警响应策略 ​

立即评估 ​

响应选项 ​

原因代码类别 ​

快速参考指南 ​

VISA原因代码 ​

MasterCard原因代码 ​

Discover原因代码 ​

预警管理最佳实践 ​

主动监控 ​

文档标准 ​

集成考虑 ​

常见错误场景 ​

签名无效 ​

缺少交易数据 ​

重复通知 ​

服务配置问题 ​

实施检查清单 ​

实施前 ​

实施后 ​

性能监控 ​

与Onerway服务集成 ​

拒付预警通知

功能说明

通知接收配置

预警服务提供商

通知示例

通知字段说明

通知处理流程

通知重试策略

确保成功送达

预警响应策略

立即评估

响应选项

原因代码类别

快速参考指南

VISA原因代码

MasterCard原因代码

Discover原因代码

预警管理最佳实践

主动监控

文档标准

集成考虑

常见错误场景

签名无效

缺少交易数据

重复通知

服务配置问题

实施检查清单

实施前

实施后

性能监控

与Onerway服务集成