• Fraud Notification
  • Feature Overview
  • Notification Configuration
    • Fraud Type List
  • Notification Example
  • Notification Parameters
  • Notification Processing Flow
  • Notification Receipt Confirmation
  • Notification Signature Verification
  • Fraud Risk Handling Recommendations
  • Important Considerations

Fraud Notification

This document describes how to receive and process fraud notifications. Onerway pushes fraud alert information in real-time via Webhook to help merchants promptly identify and handle potentially fraudulent transactions, reducing chargeback risks and financial losses.

Feature Overview

The fraud notification service provides:

• Real-time fraud alert information push
• Detailed transaction and fraud type data
• Quick identification of high-risk transactions
• Chargeback status and refund status information
• Support for timely risk control measures

Notification Configuration

To receive fraud notifications, merchants need to configure a Webhook URL in the Onerway merchant dashboard. The system will push fraud alert information to this URL via HTTP POST. Configuration steps:

1. Log in to Onerway merchant dashboard
2. Navigate to "Developers" > "Notification Settings"
3. Configure the "Fraud Notification" receiving address
4. Test that notification reception works properly

Fraud Type List

Fraud Types

The following are common fraud types for merchant reference:

• Lost - Lost card
• Stolen - Stolen card
• NRI - Never received card
• Fraud Application - Fraudulent application
• Counterfeit - Counterfeit card
• Miscellaneous - Other types
• Fraudulent Use of Account Number - Fraudulent use of account number
• Card Not Present Fraud - Card not present fraud
• Account Takeover Fraud - Account takeover fraud
• First-Party Fraud - First-party fraud
• Bust-out Collusive Merchant - Bust-out collusive merchant

Notification Example

Notification Example

{
  "notificationId": "123456762",
  "fraudType": "Card Not Present Fraud",
  "createTime": "2025-04-30 10:33:17",
  "originTransactionId": "1907624215008641024",
  "txnAmount": 20.00,
  "cardBrand": "PIX",
  "chargebackStatus": 0,
  "refundStatus": 0,
  "merchantNo": "800550",
  "sign": "6bf3a6260ec5794031beace10c46dd7e09d4f58c4086a2e314cdb235cb9aa647"
}

Response

{
  "20000"
}

Notification Parameters

Parameter	Type	Length	Required	Signed	Description
notificationId	String	/	Yes	Yes	Unique identifier for fraud notification
fraudType	String	/	Yes	Yes	Type of fraud detected. For a common list of fraud types, refer to the Fraud Type List section
createTime	String	/	Yes	Yes	Notification creation time. Format: yyyy-MM-dd HH:mm:ss
originTransactionId	String	20	Conditional	Yes	Original transaction ID from Onerway
txnAmount	String	/	Yes	Yes	Order amount after conversion to settlement currency
cardBrand	String	/	Yes	Yes	Payment method (card brand), such as: VISA, MASTERCARD, PIX, etc.
chargebackStatus	String	/	No	Yes	Chargeback status: 0 - No chargeback on source transaction 1 - Chargeback occurred on source transaction
refundStatus	Number	/	Yes	Yes	Refund status: 0 - No refund 1 - Full refund 2 - Partial refund
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
sign	String	/	Yes	No	Digital signature string for request verification. Please refer to Signature for signature generation method.

Notification Processing Flow

Notification Receipt Confirmation

Important Notes

1. Ensure your notification receiving server is stable and reliable, capable of receiving notifications 24/7
2. After receiving a notification, return 20000 to indicate successful receipt
3. If notification sending fails, the system will retry according to the following strategy:

• Total of 6 attempts
• Initial sending interval of 5 seconds
• Each sending interval grows exponentially (doubling each time)
• Maximum sending interval of 60 seconds
• Sending interval sequence: 5s → 10s → 20s → 40s → 60s

4. Notification content should be treated as confidential information, properly stored and processed
5. Recommend saving all received notification records for subsequent tracking and analysis

Notification Signature Verification

To ensure notification authenticity, merchants should verify the signature of received notifications:

1. Extract the sign field from the notification
2. Follow the signature verification logic in Transaction Notification to calculate signatures for other fields
3. Compare the calculated signature with the sign in the notification
4. If inconsistent, reject processing of the notification

Fraud Risk Handling Recommendations

After receiving fraud notifications, merchants should take different measures based on risk levels:

Handling Strategies

1. High-risk Transaction Processing

• Immediately suspend order shipment or service provision
• Consider proactively initiating refunds to avoid subsequent chargebacks
• Add customers to risk monitoring lists
• Preserve relevant transaction evidence

2. Account Security Measures

• Consider implementing temporary security restrictions on involved accounts
• Require users to re-verify their identity
• Check accounts for other suspicious activities

3. Subsequent Prevention

• Analyze fraud patterns and adjust risk control rules
• Enhance verification requirements for similar transactions
• Consider implementing additional verification for specific payment methods or regions

Important Considerations

Important Notes

1. Ensure Webhook receiving servers are stable and reliable to avoid missing notifications
2. Verify the signature of each notification to prevent forged requests
3. Implement idempotent processing to avoid duplicate processing from repeated notifications
4. Transactions with chargeback status 1 should be prioritized to reduce potential losses

Best Practices

1. Establish dedicated fraud notification processing workflows and teams
2. Prioritize high-risk transactions, especially high-value transactions
3. Save all notification records for subsequent analysis and auditing
4. Promptly initiate full refunds for suspicious transactions to reduce chargeback risks
5. Establish comprehensive transaction documentation management systems
6. Regularly analyze fraud data and trends to adjust risk control strategies
7. Consider using machine learning models for automated risk scoring