Mapping Guide

Integrating with Fraudio requires mapping your data to conform with our standardized schema. This guide will walk you through the key steps of the data mapping process to ensure optimal fraud detection results.

---

Why Data Mapping Matters

Fraudio uses a centralized schema that all integrations must follow. Proper data mapping is essential because:

• API Compatibility: Your data must conform to Fraudio's standardized schema for successful API integration
• Fraud Detection Accuracy: Our machine learning models and rule engine rely on consistent, well-formatted data
• Real-time Processing: Incorrect mapping can lead to API errors and delayed fraud detection
• Analytics & Reporting: Accurate data mapping ensures reliable insights in our portal
• Historical Analysis: Consistent mapping enables meaningful comparison between historical and live data

---

Mapping Process

Let's walk through an example of mapping a card expiry date from your system to Fraudio's schema.

1. Review Available Fields:

   • Fraudio's schema requires a cardexpirydate field in MM/YY format.
   • Your system has separate fields named card_expiry_month and card_expiry_year.

2. Map Your Data Fields:

   • Note field differences: Single cardexpirydate (Fraudio) vs split fields (Your system).
   • Document data transformations needed:
     • Combine year and month fields
     • Convert 4-digit year to 2-digit year if needed
     • Ensure month is zero-padded

3. Validate Data Types:

   • Ensure your transformed data matches our requirements:
     • Format must be MM/YY (e.g., "12/24" for December 2024)
     • Must be a string type
     • Length must be exactly 4 characters
   • Example transformation:

     # If your system has "2024" and "12"
     year = "2024"[2:]  # Get last 2 digits: "24"
     month = "12".zfill(2)  # Ensure 2 digits: "12"
     cardexpirydate = f"{month}/{year}"  # Result: "12/24"

4. Test, Verify, and Maintain:

   • Send test transactions with various expiry dates to our Sandbox environment.
   • Verify edge cases:
     • Single-digit months (e.g., January → "01")
     • Year rollovers (e.g., 2029 → "29", 2030 → "30")
   • Monitor for any truncation or formatting issues.

Need help with mapping? Contact your Fraudio representative for guidance and best practices specific to your integration.

---

Transaction Flow

Fraudio requires a diverse range of transaction types to detect fraudulent transactions and merchants with greater precision. Beyond regular payment data, we benefit from receiving bank transfers, wallet transfers, withdrawals, payouts, and other relevant deposits. This comprehensive data allows us to analyze merchant behavior more thoroughly, enhancing our ability to identify potential fraudulent activity and providing more effective fraud detection and prevention.

In payment transactions, a series of related events typically occur in sequence, such as authorization requests, authentication/authorization responses, captures, and refunds. To ensure accurate tracking and analysis, it's essential that we receive each of these transaction events as separate entries.

Card Transactions

When using Fraudio's recommendation within the authorization process (for example, to block transactions), you will need to send several request that can relate to the same purchase.

Pre-authorization request - Purchase

Before the transaction is authenticated and/or authorized, an API call should be made to the Fraud Score Endpoint. At this stage, it is known whether certain authentication checks are applied (identified by fields like cvvused and threedsused), but the results of these checks are not yet available: The API call will not include the authentication and authorization response details, such as success, responsecode, eci, cvvresult, etc.

View API Endpoint for Payment Fraud Score

{
"transactionid": "111",
"transactiontype": "auth",
"transactionintent": "purchase",
"channel": "ecom",
"cvvused": "true",
"threedsused": "true",
// other fields
}

Post-authorization request - Purchase

After processing the Fraudio's payment fraud score response and the authorization request, an authentication/authorization response should follow to enrich Fraudio's context. This response should have the same transaction ID as the original authorization request.

View API Endpoint for Payment Post Authorization Enrichment

{
  "transactionid": "111", //same as pre-authorization transactionid
  "transactiontype": "auth",
  "cvvresult": "S",
  "eci": "05",
  "responsecode": "00",
  "success": "true"
}

Dispute Events - Purchase

To ensure the accuracy of our scores and enhance our AI's learning capabilities, please consistently provide updates on any chargebacks or fraud reports you experience. Disputes should always be reported to the Dispute Events endpoint and they should be linked to the original transaction.

View API Endpoint for Dispute Events

{
"transactionid": "111", //same as pre-authorization transactionid
"reporttype": "1st chargeback",
"chargebackid": "888"
// other fields
}

Other transaction events - Purchase

For other transaction events that do not need any scoring, such as captures, reversals, refunds, voids, and incremental-auth we provide the Payments Events Enrichment Endpoint. These transaction events do not need to be split up in pre-authorization and post-authorization, as they don't need a response during the authorization process.

You can link these events to the original authorization request, by using the original transaction ID as the parenttransactionid.

View API Endpoint for Payment Events Enrichment

{
"transactionid" : "222",
"transactiontype" : "capture",
"transactionintent": "purchase",
"channel": "ecom",
"parenttransactionid" : "111", //same as pre-authorization transactionid
// other fields
}

Other transaction intents

While purchases are most common, Fraudio supports several distinct transaction intents to accurately categorize different types of card operations:

• purchase: the cardholder intends to make a purchase, such as buying goods or services.
• card_verification: the cardholder intends to confirm the card's validity or register the card for future transactions.
• withdrawal: the cardholder intends to withdraw funds, such as at an ATM or via a bank teller.
• deposit: the cardholder intends to deposit funds into an account.

These transaction intents follow the same transaction flow as purchases. An example of a deposit initiated by the cardholder, not the merchant (see Merchant Bank and Wallet Transactions), that is sent for scoring to the Payment Fraud Score endpoint.

View API Endpoint for Payment Fraud Score

{
"transactionid": "333",
"transactiontype": "auth",
"transactionintent": "withdrawal",
"channel": "atm",
"cvvused": "true",
"threedsused": "true",
// other fields
}

Merchant Bank and Wallet Transactions

info

This section covers transactions where you have visibility into merchant financial activity, including:

• Withdrawals from their platform balance to their bank account
• Transfers between merchant wallets
• Payouts to suppliers or contractors
• Settlement of marketplace transactions

Merchant bank and wallet transactions are crucial for monitoring merchants' financial activity, as it provides a comprehensive view of their financial operations.

Bank and Wallet Transfers

All bank transfers, wallet transfers, withdrawals, deposits and payouts are recorded from the merchant's perspective.

View API Endpoint for Account Bank Transfers

{
"transactionid" : "444",
"transactiontype" : "outgoing_bank_transfer",
"merchant": "Merchant A",
// other fields
}

Inter Account Transfers

In instances where wallet transfers occur between two known entities, such as a merchant sending funds to another recognized merchant, you can use the Inter Account Transfers endpoint.

View API Endpoint for Inter Account Transfers

 {
"sender_transactionid": "555",
"receiver_transactionid": "666",
"sender_merchant": "Merchant A",
"receiver_merchant": "Merchant B",
// other fields
}