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:

   • On a card entity, Fraudio expects expiry_date as a 4-digit MMYY string (for example "1127" for November 2027). See Fraudio Data Schema.
   • Your system has separate fields named card_expiry_month and card_expiry_year.

2. Map Your Data Fields:

   • Note field differences: single entities[].expiry_date (Fraudio) vs split month/year 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
     • Do not include a slash or other separator

3. Validate Data Types:

   • Ensure your transformed data matches our requirements:
     • Format must be MMYY (e.g. "1224" 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"
     expiry_date = f"{month}{year}"  # Result: "1224"

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 Financial Events Screening endpoint. At this stage, it is known whether certain authentication checks are applied, but the results of these checks are not yet available: the request will not include post-auth fields such as response_code, eci, cvv_result, or avs_result.

View API Endpoint for Financial Events Screening

{
  "event": {
    "type": "card_network_transaction",
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "sender": { "refs": { "card": "c67876543" } },
    "receiver": { "refs": { "merchant_business": "hotel-bristol", "merchant_account": "hotel-bristol-front" } },
    "details": {
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543", "card_token": "67876543", "last_four_digits": "9876", "expiry_date": "1127" },
    { "type": "merchant_business", "id": "hotel-bristol", "name": "Hotel Bristol B.V.", "country_code": "NLD" },
    { "type": "merchant_account", "id": "hotel-bristol-front", "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } }
  ]
}

Post-authorization response - Purchase

After processing the Financial Events Screening response and the authorization request, send the authorization response to enrich Fraudio's context. Use Financial Events Enrichment with MTI 0110, linked to the original 0100 via parent_event_id and/or lifecycle_rrn.

View API Endpoint for Financial Events Enrichment (authorization response)

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "auth-resp-001",
      "timestamp": 1770004000.123,
      "lifecycle_rrn": "123456789012",
      "parent_event_id": "a12c34def",
      "details": {
        "mti": "0110",
        "transaction_type": "purchase",
        "response_code": "00",
        "eci": "02",
        "avs_result": "Y",
        "cvv_result": "M",
        "cavv_result": "2"
      }
    }
  ],
  "entities": []
}

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. Dispute events are sent via Financial Events Enrichment (event type dispute) and should be linked to the original transaction.

View API Endpoint for Financial Events Enrichment (dispute)

{
  "events": [
    {
      "type": "dispute",
      "id": "dsp-evt-001",
      "timestamp": 1770100000,
      "parent_event_id": "a12c34def",
      "details": {
        "dispute_type": "chargeback",
        "dispute_stage": "1st_chargeback",
        "dispute_id": "888"
      }
    }
  ],
  "entities": []
}

Other transaction events - Purchase

For other transaction events that do not need scoring, such as captures, reversals, and refunds, use Financial Events Enrichment. These events do not need to be split into pre-authorization and post-authorization, as they don't need a response during the authorization process.

Link them to the original authorization request using parent_event_id and/or lifecycle_rrn.

View API Endpoint for Financial Events Enrichment

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "b99f12abc",
      "timestamp": 1770000300.456,
      "lifecycle_rrn": "123456789012",
      "parent_event_id": "a12c34def",
      "sender": { "refs": { "card": "c67876543" } },
      "receiver": { "refs": { "merchant_business": "hotel-bristol", "merchant_account": "hotel-bristol-front" } },
      "details": {
        "mti": "0200",
        "transaction_type": "purchase",
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 42.1
      }
    }
  ],
  "entities": []
}

Other transaction intents

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

• purchase: The cardholder intends to make a purchase, such as buying goods or services.
• atm_withdrawal: The cardholder initiates a cash withdrawal from an account.
• refund: A refund or return credited back to the cardholder.

View API Endpoint for Financial Events Screening

{
  "event": {
    "type": "card_network_transaction",
    "id": "atm-evt-001",
    "timestamp": 1770090000.000,
    "sender": { "refs": { "card": "c67876543" } },
    "details": {
      "mti": "0200",
      "transaction_type": "atm_withdrawal",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 200.00
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543" }
  ]
}

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. Send bank-to-bank transfers via Financial Events Enrichment with event type bank_transfer. Related wallet flows use wallet_withdrawal, wallet_deposit, wallet_transfer, or OCT card_network_transaction events on the same endpoint.

View API Endpoint for Financial Events Enrichment (bank_transfer)

{
  "events": [
    {
      "type": "bank_transfer",
      "id": "bt-001",
      "timestamp": 1770005300,
      "sender": {
        "refs": { "bank_account": "DE89370400440532013000" }
      },
      "receiver": {
        "refs": {
          "bank_account": "NL51INGB40123456789876",
          "merchant_business": "hotel-bristol"
        }
      },
      "details": {
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 3000.00
      }
    }
  ],
  "entities": [
    {
      "type": "bank_account",
      "id": "NL51INGB40123456789876",
      "bank_account_number": "NL51INGB40123456789876",
      "refs": { "merchant_business": "hotel-bristol" }
    },
    { "type": "merchant_business", "id": "hotel-bristol", "name": "Hotel Bristol B.V.", "country_code": "NLD" },
    { "type": "merchant_account", "id": "hotel-bristol-front", "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } }
  ]
}

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. Use Financial Events Screening for the authorization request (0100) and Financial Events Enrichment for follow-up financial messages (for example capture 0200), linked with parent_event_id and/or lifecycle_rrn.

Exact Amount Authorization

In this scenario, the cardholder specifies the exact fuel amount before pumping. Score the authorization request with transaction_type "purchase" and the exact amount, then enrich with the matching capture when clearing completes.

Hold (authorization request)

{
  "event": {
    "type": "card_network_transaction",
    "id": "txn_afdeax_001",
    "timestamp": 1770000000.123,
    "sender": { "refs": { "card": "c67876543" } },
    "receiver": { "refs": { "merchant_business": "orbit-fuel", "merchant_account": "orbit-afd" } },
    "details": {
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "USD",
      "currency_unit": "major",
      "amount": 50.0,
      "mcc": "5542"
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543", "card_token": "67876543", "last_four_digits": "9876", "expiry_date": "1127" },
    { "type": "merchant_business", "id": "orbit-fuel", "name": "Tankstation Orbit B.V.", "country_code": "NLD" },
    { "type": "merchant_account", "id": "orbit-afd", "mid": "5542101000789", "mccs": ["5542"], "refs": { "merchant_business": "orbit-fuel" } }
  ]
}

Clearing (capture)

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "txn_afdcap_001",
      "timestamp": 1770004000.123,
      "parent_event_id": "txn_afdeax_001",
      "details": {
        "mti": "0200",
        "transaction_type": "purchase",
        "currency": "USD",
        "currency_unit": "major",
        "amount": 50.0,
        "mcc": "5542"
      }
    }
  ]
}

$1.00 Status Check (Hold)

In this scenario, a nominal amount (e.g., $1.00) is authorized to verify the card before fueling. Score an authorization request with a small amount, then enrich with a follow-up financial message for the final purchase amount.

Hold (authorization request)

{
  "event": {
    "type": "card_network_transaction",
    "id": "txn_afdsts_001",
    "timestamp": 1770000000.123,
    "sender": { "refs": { "card": "c67876543" } },
    "receiver": { "refs": { "merchant_business": "orbit-fuel", "merchant_account": "orbit-afd" } },
    "details": {
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "USD",
      "currency_unit": "major",
      "amount": 1.0,
      "mcc": "5542"
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543", "card_token": "67876543", "last_four_digits": "9876", "expiry_date": "1127" },
    { "type": "merchant_business", "id": "orbit-fuel", "name": "Tankstation Orbit B.V.", "country_code": "NLD" },
    { "type": "merchant_account", "id": "orbit-afd", "mid": "5542101000789", "mccs": ["5542"], "refs": { "merchant_business": "orbit-fuel" } }
  ]
}

Clearing (final amount)

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "txn_afdcap_002",
      "timestamp": 1770004000.123,
      "parent_event_id": "txn_afdsts_001",
      "details": {
        "mti": "0200",
        "transaction_type": "purchase",
        "currency": "USD",
        "currency_unit": "major",
        "amount": 45.0,
        "mcc": "5542"
      }
    }
  ]
}

Estimated Authorization with Real-Time Clearing (RTC)

In this scenario, an estimated amount is authorized, with real-time clearing adjustments post-fueling. Score the estimated authorization, then enrich with a capture for the actual amount.

Hold (authorization request)

{
  "event": {
    "type": "card_network_transaction",
    "id": "txn_afdest_001",
    "timestamp": 1770000000.123,
    "sender": { "refs": { "card": "c67876543" } },
    "receiver": { "refs": { "merchant_business": "orbit-fuel", "merchant_account": "orbit-afd" } },
    "details": {
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "USD",
      "currency_unit": "major",
      "amount": 40.0,
      "mcc": "5542"
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543", "card_token": "67876543", "last_four_digits": "9876", "expiry_date": "1127" },
    { "type": "merchant_business", "id": "orbit-fuel", "name": "Tankstation Orbit B.V.", "country_code": "NLD" },
    { "type": "merchant_account", "id": "orbit-afd", "mid": "5542101000789", "mccs": ["5542"], "refs": { "merchant_business": "orbit-fuel" } }
  ]
}

Clearing (actual amount)

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "txn_afdcap_003",
      "timestamp": 1770004000.123,
      "parent_event_id": "txn_afdest_001",
      "details": {
        "mti": "0200",
        "transaction_type": "purchase",
        "currency": "USD",
        "currency_unit": "major",
        "amount": 32.5,
        "mcc": "5542"
      }
    }
  ]
}