Pre-Dispute Notification
This document describes how to receive and process pre-dispute notifications. Onerway pushes pre-dispute risk warning information in real-time via Webhook to help merchants identify and respond to potential dispute threats before they become actual chargebacks, reducing financial losses and improving dispute prevention.
Terminology
Pre-dispute notifications (also known as chargeback alerts) are early warning signals sent before a formal dispute or chargeback is filed. This proactive approach allows merchants to take preventive action and avoid the costs and complications of formal dispute processes.
Feature Overview
The pre-dispute notification service provides:
- Real-time pre-dispute risk warning information push
- Early detection of potential dispute activity
- Detailed transaction and alert reason data
- Proactive dispute prevention capabilities
- Integration with major pre-dispute alert services
- Comprehensive alert metadata for risk assessment
Notification Configuration
To receive pre-dispute notifications, merchants need to configure a Webhook URL in the Onerway merchant dashboard. The system will push pre-dispute alert information to this URL via HTTP POST. Configuration steps:
- Log in to Onerway merchant dashboard
- Navigate to "Developers" > "Notification Settings"
- Configure the "Pre-Dispute Notification" receiving address
- Test that notification reception works properly
Alert Service Providers
Alert Services
Pre-dispute alert services are provided by third-party risk management companies:
- Ethoca Alerts - Real-time dispute prevention network
- Verifi RDR - Rapid Dispute Resolution service
- Custom Alert Services - Contact Onerway for specialized configurations
To enable specific alert services, please contact your Onerway account manager.
Notification Example
{
"notifyType": "PRE_DISPUTE", // Notification type
"transactionId": "1948584185883394048", // Alert transaction ID
"merchantNo": "800626", // Merchant number
"timeZone": "+08:00",
"predisputeId": "1948584185883394048", // Alert ID
"service": null, // Alert service provider (optional)
"type": null, // Service type (optional)
"createdTime": "2025-07-25 10:21:06", // Alert creation time
"receivedTime": "2025-07-25 11:20:48", // Onerway receipt time
"amount": "0.01", // Alert amount
"currency": "GBP", // Alert currency
"source": "Issuer", // Alert source
"reasonCode": "10.1", // Reason code
"txnId": "1948582879735185408", // Original transaction ID
"merchantTxnId": "1753413333000", // Merchant transaction ID
"txnTime": "2025-07-25 11:15:36", // Original transaction time
"orderAmount": "15.40", // Original order amount
"orderCurrency": "USD", // Original order currency
"paymentMethod": "VISA", // Payment method
"chargebackStatus": "0", // Current chargeback status
"refundStatus": "0", // Current refund status
"eci": null, // Electronic Commerce Indicator
"website": "voidmain", // Transaction website
"email": "", // Customer email
"sign": "15ad79c150560aa07baffd32f1e0ac0088af7acc00cb9b4f8d46563139e906f5"
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
1948584185883394048 // transactionIdNotification Parameters
| 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: |
currency | String | 8 | Yes | |
eci | String | / | Yes | Electronic Commerce Indicator for 3DS authentication status. |
String | 256 | Yes | Customer email address for transaction notifications and receipts. | |
merchantNo | String | 20 | Yes | Merchant number assigned by |
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 NotifyTypeEnumfor all available types. |
orderAmount | String | 19 | Yes | Transaction amount in the specified currency, formatted as a decimal string. |
orderCurrency | String | 8 | Yes | |
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 | |
receivedTime | String | / | Yes | Time when Onerway received the alert. Format: |
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: |
type | String | 64 | No | Alert service type. |
website | String | 256 | Yes | Transaction website domain where the pre-dispute alert occurred. |
Notification Processing Flow
Notification Retry Strategy
Onerway implements an automatic retry mechanism to ensure reliable delivery of pre-dispute notifications:
Retry Policy
If the webhook endpoint call fails or the merchant does not respond with the correct transactionId, Onerway will automatically retry the notification 3 times total with 30-minute intervals between each attempt.
Retry Schedule:
- Initial attempt: Immediate delivery
- 1st retry: 30 minutes after initial failure
- 2nd retry: 30 minutes after 1st retry failure
- Final attempt: 30 minutes after 2nd retry failure
After the final retry attempt fails, no further notifications will be sent for that specific alert.
Ensuring Successful Delivery
To prevent unnecessary retries and ensure proper alert handling:
Implement Proper Response Format
- Always respond with the notification's
transactionId - Return HTTP status code 200 for successful processing
- Always respond with the notification's
Monitor Webhook Endpoint Health
- Ensure your endpoint is accessible and responsive
- Implement proper error handling and logging
Set Up Monitoring
- Track notification receipt and processing
- Alert on failed webhook deliveries
- Monitor response times and error rates
Alert Response Strategies
Immediate Assessment
When receiving a pre-dispute notification:
Validate Alert Authenticity
- Verify the notification signature
- Confirm the transaction details match your records
- Check the alert reason code significance
Analyze Risk Level
- Review the
reasonCodefor dispute category - Assess transaction characteristics and customer history
- Evaluate potential chargeback liability
- Review the
Determine Response Strategy
- Consider preemptive refund for high-risk cases
- Initiate customer contact for resolution
- Prepare documentation for potential formal disputes
Response Options
Response Strategies
Preemptive Refund
- Issue immediate refund to prevent formal dispute
- Most effective for fraud-related alerts
- Reduces dispute fees and ratio impact
Customer Engagement
- Contact customer to resolve underlying issue
- Provide additional transaction details or receipts
- Negotiate resolution before dispute escalation
Documentation Preparation
- Gather comprehensive transaction evidence
- Prepare compelling case materials
- Strengthen position for potential dispute defense
Monitor and Wait
- Track alert status for developments
- Maintain readiness for rapid response
- Suitable for lower-risk scenarios
Reason Code Categories
Understanding alert reason codes helps determine the best response strategy. Each card network uses different coding systems with varying priority levels and recommended actions.
Quick Reference Guide
| Card Network | Code Format | Main Categories | Fraud Indicators |
|---|---|---|---|
| VISA | Hierarchical numeric (10.x, 11.x) | 4 main categories (10-13) | 10.x series |
| MasterCard | Alphanumeric mixed (FR4, C02, 37) | Series-based (FR, C, P, R + numeric) | FR series |
| Discover | Primarily alphabetic (UA01, RG) | Function-based (UA, RG, DP, etc.) | UA series |
🏛️ VISA Reason Codes
Hierarchical numeric system organized into main categories
🚨 Critical - Fraud Category (10.x series)
- EMV Liability Shift (
10.1,10.2) - Counterfeit/non-counterfeit fraud - Environment-Based Fraud (
10.3,10.4) - Card present/absent fraud - Monitoring Program (
10.5) - VISA fraud monitoring violations
📊 Priority: 🔴 Critical | ⚡ Action: Consider immediate preemptive refund
⚠️ High Priority - Authorization Category (11.x series)
- Card Recovery (
11.1) - Card recovery bulletin issues - Authorization Problems (
11.2,11.3) - Declined or missing authorization
📊 Priority: 🟠 High | 🔍 Action: Review authorization records and processes
🔧 Medium Priority - Processing & Consumer Issues
Processing Errors (12.x series)
- Technical issues: Late presentment, incorrect data, duplicate processing
Consumer Disputes (13.x series)
- Service/merchandise issues, cancellations, credit problems
📊 Priority: 🟡 Medium | 🤝 Action: Process review and customer engagement
💳 MasterCard Reason Codes
Alphanumeric codes across multiple specialized series
🚨 Critical - Fraud Series
FR2- Fraud Full Recourse ProgramFR4- Immediate Chargeback ProgramFR6- Partial Immediate Chargeback Program
📊 Priority: 🔴 Critical | ⚡ Action: Consider immediate preemptive refund
⚠️ High Priority - Consumer & Processing Issues
Consumer Disputes (C series)
C02,C04,C05,C08- Credit/goods/services issues
Processing Errors (P series)
P01,P03,P04,P05- Technical processing errors
Numeric Codes
8,12,31,34,37- Authorization, account, fraud issues
📊 Priority: 🟠 High to 🟡 Medium | 🔍 Action: Context-dependent response
🔍 Discover Reason Codes
Alphabetic codes with specific fraud indicators
🚨 Critical - Fraud Series
UA01- Fraud (Card Present Transaction)UA02- Fraud (Card Not Present Transaction)UA03- Fraud (Processing Error)
📊 Priority: 🔴 Critical | ⚡ Action: Consider immediate preemptive refund
⚠️ Medium to High Priority - Service & Processing Issues
Service Issues
RG- Non-receipt of goods/servicesRM- Quality disputesRN2- Credit not processed
Processing Issues
DP- Duplicate postingLP- Late presentationCD,AW- Credit/amount alterations
General Disputes
AA,AT,AP,CR- Recognition, authorization, recurring payments
📊 Priority: 🟠 High to 🟡 Medium | 🤝 Action: Customer engagement and process review
📚 Complete Reference
For detailed reason code descriptions and comprehensive card network-specific information, see Pre-Dispute Alert Reason Codes →
Best Practices for Alert Management
Proactive Monitoring
Prevention Strategies
- Set up Real-time Alerts: Configure immediate notifications for critical alerts
- Implement Automated Workflows: Create rules for common alert scenarios
- Monitor Alert Patterns: Track alert frequency and types for trend analysis
- Maintain Response SLAs: Establish target response times for different alert categories
Documentation Standards
- Preserve Alert Data: Store all alert information for analysis and reporting
- Track Response Actions: Document all steps taken in response to alerts
- Maintain Customer Communications: Keep records of customer interactions
- Monitor Outcomes: Track whether alerts resulted in actual chargebacks
Integration Considerations
- CRM Integration: Link alerts to customer management systems
- Risk Scoring: Incorporate alerts into fraud detection algorithms
- Automated Refunds: Set up rules for automatic refund processing
- Reporting Dashboards: Create visibility into alert performance metrics
Common Error Scenarios
Invalid Signature
Problem: Notification signature verification fails
Solution: Verify your webhook endpoint is using the correct secret key
Missing Transaction Data
Problem: Referenced transaction not found in your system
Solution: Check transaction ID mapping and data synchronization
Duplicate Notifications
Problem: Receiving multiple notifications for the same alert
Causes:
- Webhook endpoint does not respond with the required
transactionId - Response format is incorrect or missing
- Network issues causing retry attempts
Solution:
- Ensure your webhook endpoint responds with the notification's
transactionIdto confirm receipt - Implement idempotency checks using
transactionIdorpredisputeId - Return proper HTTP status codes (200) with the required response format
- See Notification Retry Strategy for retry mechanism details
Service Configuration Issues
Problem: service and type fields are null
Solution: Contact Onerway to enable specific alert service configurations
Implementation Checklist
Pre-Implementation
- Configure Webhook URL: Set up endpoint in Onerway dashboard
- Implement Signature Verification: Ensure notification authenticity
- Set up Alert Routing: Define how alerts reach appropriate teams
- Establish Response Procedures: Create workflows for different alert types
Post-Implementation
- Monitor Alert Volume: Track notification frequency and patterns
- Measure Response Effectiveness: Analyze chargeback prevention rates
- Optimize Workflows: Refine response strategies based on outcomes
- Regular Testing: Verify notification delivery and processing
Performance Monitoring
- Response Time Tracking: Monitor how quickly alerts are processed
- Prevention Rate Analysis: Measure chargeback prevention success
- Cost-Benefit Assessment: Evaluate refund costs vs. chargeback savings
- Trend Analysis: Identify patterns in alert types and customer behavior
Integration with Onerway Services
When using Onerway's pre-dispute alert services, this notification system integrates seamlessly with:
- Fraud Notification Services - Comprehensive fraud detection
- Chargeback Query API - Historical chargeback data
- Transaction Query API - Transaction data query
- Transaction Notifications - Payment status updates
For more information about implementing comprehensive chargeback prevention strategies, contact your Onerway account manager.