• 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": "1952201341279666176",
    "fraudType": "Counterfeit Card Fraud",
    "createTime": "2025-08-04 10:54:04",
    "originTransactionId": "1952194039243997184",
    "txnAmount": "10.00",
    "cardBrand": "MASTERCARD",
    "chargebackStatus": "0",
    "refundStatus": "0",
    "merchantNo": "800209",
    "sign": "e85940bbb2af6060842508a1793420f061b8c5a1a2e6cbc6dd1a9447ca53f834"
}

Response

20000

Notification Parameters

Parameter	Type	Length	Signed	Description
notificationId	String	/	Yes	Unique identifier for the fraud notification event.
fraudType	String	/	Yes	Type of fraud detected by the monitoring system. For a complete list of fraud types, refer to the Fraud Type List section.
createTime	String	/	Yes	Timestamp when the notification was created.
originTransactionId	String	20	Yes	Original transaction ID from Onerway for reference transactions.
txnAmount	String	/	Yes	Transaction amount after currency conversion to settlement currency.
cardBrand	String	/	Yes	Payment method or card brand used in the transaction.
chargebackStatus	String	/	Yes	Chargeback status indicating dispute activity.
refundStatus	String	/	Yes	Current refund status of the transaction.
merchantNo	String	20	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
sign	String	/	No	Digital signature string for request verification and security. 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

Unified Signing/Verification Rules

1. Request signing and webhook verification use the same algorithm: ASCII sort -> concatenate values -> append secretKey -> SHA-256.
2. Use a simple default for request signing: exclude only sign, and include all other non-empty fields (that is, REQUEST_EXCLUDED_KEYS = ['sign']).
3. Webhook verification must dynamically exclude fields marked No in the Signature column. Do not hardcode a Yes whitelist.
4. Treat originTransactionId as included by default; exclude it only in webhook verification.

Current Webhook Excluded Fields

'originTransactionId', 'originMerchantTxnId', 'customsDeclarationAmount', 'customsDeclarationCurrency', 'paymentMethod', 'walletTypeName', 'periodValue', 'tokenExpireTime', 'sign'

Fraud webhook signature verification follows the same logic as transaction notifications. For complete code examples, see Transaction Notification - Webhook Verification Code Examples.

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