Mapping Guide

Integrating with Fraudio requires mapping your data to conform with our standardized schema. Proper data mapping is essential for several reasons:

• 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.

This guide will walk you through the key steps of the data mapping process to ensure optimal fraud detection results.

---

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:

   • Build unit tests to automate the verification of data transformations and ensure they meet the required format.
   • 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.

Cardholder Transactions

This section covers transactions initiated by cardholders, such as purchases and fund transfers using payment cards. For transactions initiated by merchants, refer to the "Merchant Bank and Wallet Transactions" section.

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

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

• 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 initiates a cash withdrawal from an account. An example of a deposit initiated by the cardholder, not the merchant, is sent for scoring to the Payment Fraud Score endpoint (see Merchant Bank and Wallet Transactions).

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
}

Automated Fuel Dispenser (AFD) Transactions

AFD transactions occur at unattended fuel dispensers where cardholders authorize fuel purchases. These transactions have unique authorization flows that require specific data mapping considerations. The primary types of AFD transactions include:

• Exact Amount Authorization: When the cardholder specifies the exact fuel amount before pumping.
• $1.00 Status Check (Hold): A nominal amount (e.g., $1.00) is authorized to verify the card before fueling.
• Estimated Authorization with Real-Time Clearing (RTC): An estimated amount is authorized, with real-time clearing adjustments post-fueling.

Each type of transaction requires specific mapping to ensure accurate processing and fraud detection.

Exact Amount Authorization

In this scenario, the cardholder specifies the exact fuel amount before pumping. You should set transactiontype to auth, transactionintent to purchase, and include the exact amount.

Hold Transaction

{
  "transactionid": "txn_afdeax_001",
  "transactiontype": "auth",
  "transactionintent": "purchase",
  "amount": 50.00,
  "currency": 840,
  "channel": "pos",
  "mcc": "5542",
  "parenttransactionid": null
  // other fields
}

Clearing Transaction

{
  "transactionid": "txn_afdcap_001",
  "transactiontype": "capture",
  "transactionintent": "purchase",
  "amount": 50.00,
  "currency": 840,
  "channel": "pos",
  "mcc": "5542",
  "parenttransactionid": "txn_afdeax_001"
  // other fields
}

$1.00 Status Check (Hold)

In this scenario, a nominal amount (e.g., $1.00) is authorized to verify the card before fueling. Set transactiontype to auth, transactionintent to card_verification, and amount to 1.00. Follow up with an auth_capture transaction reflecting the final amount.

Hold Transaction

{
  "transactionid": "txn_afdsts_001",
  "transactiontype": "auth", //auth_capture in the case where the amount is deducted from the cardholder's account
  "transactionintent": "card_verification",
  "amount": 1.00,
  "currency": 840,
  "channel": "pos",
  "mcc": "5542",
  "parenttransactionid": null
  // other fields
}

Clearing Transaction

{
  "transactionid": "txn_afdcap_002",
  "transactiontype": "auth_capture",
  "transactionintent": "purchase",
  "amount": 45.00,
  "currency": 840,
  "channel": "pos",
  "mcc": "5542",
  "parenttransactionid": "txn_afdsts_001"
  // other fields
}

Estimated Authorization with Real-Time Clearing (RTC)

In this scenario, an estimated amount is authorized, with real-time clearing adjustments post-fueling. Set transactiontype to auth, transactionintent to purchase, and amount to the estimated value. Subsequently, send a capture transaction with the actual amount.

Hold Transaction

{
  "transactionid": "txn_afdest_001",
  "transactiontype": "auth",
  "transactionintent": "purchase",
  "amount": 40.00,
  "currency": 840,
  "channel": "pos",
  "mcc": "5542",
  "parenttransactionid": null
  // other fields
}

Clearing Transaction

{
  "transactionid": "txn_afdcap_003",
  "transactiontype": "capture",
  "transactionintent": "purchase",
  "amount": 32.50,
  "currency": 840,
  "channel": "pos",
  "mcc": "5542",
  "parenttransactionid": "txn_afdest_001"
  // other fields
}