Skip to main content
Version: 2.0

Financial Events Enrichment

Send financial events and entity updates to enrich Fraudio's dataset, without requesting an immediate fraud score.

Request method and URL
POST https://api.fraudio.com/v2/financial-events/enrichment

Typical request​

Use this endpoint for events that don't require a synchronous fraud recommendation, or to update entity context independently of transactions.

The request body contains a top-level events array and a top-level entities array. Events and entities are correlated through refs; there is no per-event entity nesting.

Request body
{
  "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": []
}

Typical response​

This endpoint does not return a fraud score. While it only responds with a simple acknowledgement, Fraudio stores and analyzes these enrichments in the background. Enrichments serve as context for subsequent events, support a data-rich experience in the Portal and enable powerful features for long-term fraud monitoring.

Response body
{
  "status": "ok"
}

Event types​

This endpoint accepts multiple event types using the same request structure. Below are common event.type values and example payloads.

card_network_transaction (authorization response)​

Use MTI 0110 to send the authorization response after a pre-auth scoring call. This enriches Fraudio's dataset with the outcome of the authorization and any post-auth fields that were not yet available at scoring time (e.g. event.details.response_code, event.details.eci, event.details.avs_result, event.details.cvv_result, event.details.cavv_result).

Link this event to the original 0100 using parent_event_id and/or lifecycle_rrn. sender, receiver, and event.details.amount, event.details.currency, event.details.currency_unit are optional if they were already sent on the original 0100 event.

event.details.transaction_type mirrors the value sent on the original card_network_transaction event (e.g. "purchase"). See the Financial Events Screening - Transaction types for the full mapping of transaction_type values and their relationship to ISO 8583 DE003.

Post-auth integrated clients

If your fraud checks are performed post-authorization, send the 0110 to the Financial Events Screening endpoint instead for scoring. In that case, include sender, receiver, and event.details.amount, event.details.currency, event.details.currency_unit since there is no prior event to inherit them from.

{
  "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": []
}

card_network_transaction (reversal advice)​

Use this for transaction reversals.

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "reversal-evt-001",
      "timestamp": 1770004500,
      "lifecycle_rrn": "123456789012",
      "parent_event_id": "a12c34def",
      "sender": { "refs": { "acquirer": "b-7610201" } },
      "receiver": { "refs": { "issuer": "b-450901" } },
      "details": {
        "mti": "0420",
        "transaction_type": "purchase",
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 42.1
      }
    }
  ],
  "entities": [
    { "type": "acquirer", "id": "b-7610201", "bin": "7610201", "name": "Example Acquirer", "country_code": "PRT" },
    { "type": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" }
  ]
}

dispute (pre-arbitration)​

Dispute events are typically less complete than transaction events but follow the same event/entities structure. Link them to the original transaction using parent_event_id and/or lifecycle_rrn.

Dispute events can represent different sources:

  • tc40: Visa fraud notification files (TC40), used to report confirmed or suspected fraud.
  • safe: Mastercard fraud notification files (SAFE), used to report confirmed or suspected fraud.
  • chargeback: Chargeback lifecycle events (1st/2nd chargeback, pre-arbitration, reversals, information supplied).

event.details.dispute_reason_code accepts reason codes from both Visa and Mastercard. Use the scheme-native format — Visa codes use dot notation (e.g. 10.4, 13.1) while Mastercard codes are numeric strings (e.g. 4853, 4863).

When migrating from the legacy v1/transactions/dispute-events payload, you can translate common fields like this:

  • transactionid → event.parent_event_id
  • merchant → event.receiver.refs.merchant_business (or include a merchant_business entity in entities; use merchant_account when sending the MID / registered MCCs)
  • chargebackid → event.details.dispute_id
  • chargebackreason → event.details.dispute_reason_code
  • reporttype (e.g. 1st chargeback, pre-arbitration) → event.details.dispute_stage
  • statusid → event.details.dispute_status
  • fraudimportdate → event.details.import_timestamp (timestamp when the dispute/notification was imported)
  • fraudreason → event.details.fraud_reason
{
  "events": [
    {
      "type": "dispute",
      "id": "dsp-evt-001",
      "timestamp": 1770100000,
      "lifecycle_rrn": "123456789012",
      "parent_event_id": "a12c34def",
      "sender": { "refs": { "issuer": "b-450901" } },
      "receiver": { "refs": { "merchant_business": "hotel-bristol" } },
      "refs": { "acquirer": "b-7610201" },
      "details": {
        "dispute_type": "chargeback",
        "dispute_stage": "pre_arbitration",
        "dispute_status": "pending",
        "dispute_id": "1003125",
        "dispute_reason_code": "10.4",
        "fraud_reason": "Suspicious account number used",
        "import_timestamp": 1602868410.143105,
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 42.1
      }
    }
  ],
  "entities": [
    {
      "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" }
    },
    { "type": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" },
    { "type": "acquirer", "id": "b-7610201", "bin": "7610201", "name": "Example Acquirer", "country_code": "PRT" }
  ]
}

wallet_withdrawal (wallet to bank)​

A merchant (or other account holder) withdraws funds from their wallet to their bank account. Note that it is necessary to link the wallet to the merchant, to use this information for MIF/AML monitoring.

{
  "events": [
    {
      "type": "wallet_withdrawal",
      "id": "ww-001",
      "timestamp": 1770005000,
      "sender": {
        "refs": {
          "wallet": "wallet-893067473928",
          "merchant_business": "hotel-bristol"
        }
      },
      "receiver": {
        "refs": {
          "bank_account": "NL51INGB40123456789876"
        }
      },
      "details": {
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 1500.00
      }
    }
  ],
  "entities": [
    {
      "type": "wallet",
      "id": "wallet-893067473928",
      "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" }
    },
    {
      "type": "bank_account",
      "id": "NL51INGB40123456789876",
      "bank_account_number": "NL51INGB40123456789876",
      "name": "ING Bank N.V."
    }
  ]
}

wallet_deposit (bank to wallet)​

A merchant (or other account holder) deposits funds from their bank account into their wallet. Note that it is necessary to link the wallet to the merchant, to use this information for MIF/AML monitoring.

{
  "events": [
    {
      "type": "wallet_deposit",
      "id": "wd-001",
      "timestamp": 1770005100,
      "sender": {
        "refs": {
          "bank_account": "NL51INGB40123456789876"
        }
      },
      "receiver": {
        "refs": {
          "wallet": "wallet-893067473928",
          "merchant_business": "hotel-bristol"
        }
      },
      "details": {
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 500.00
      }
    }
  ],
  "entities": [
    {
      "type": "bank_account",
      "id": "NL51INGB40123456789876",
      "bank_account_number": "NL51INGB40123456789876",
      "name": "ING Bank N.V."
    },
    {
      "type": "wallet",
      "id": "wallet-893067473928",
      "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" }
    }
  ]
}

card_network_transaction (payout — OCT)​

A merchant (or other wallet holder) transfers funds directly to a card via an Original Credit Transaction (OCT). Uses MTI 0200 with transaction_type: "oct". Note that it is necessary to link the wallet to the merchant, to use this information for MIF/AML monitoring.

{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "po-001",
      "timestamp": 1770005200,
      "sender": {
        "refs": {
          "wallet": "wallet-893067473928",
          "merchant_business": "hotel-bristol"
        }
      },
      "receiver": {
        "refs": {
          "card": "c67876543"
        }
      },
      "details": {
        "mti": "0200",
        "transaction_type": "oct",
        "currency": "EUR",
        "currency_unit": "major",
        "amount": 250.00
      }
    }
  ],
  "entities": [
    {
      "type": "wallet",
      "id": "wallet-893067473928",
      "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" }
    },
    {
      "type": "card",
      "id": "c67876543",
      "card_token": "67876543",
      "last_four_digits": "9876",
      "expiry_date": "1127",
      "refs": { "issuer": "b-450901", "cardholder": "c4rdh0ld" }
    },
    { "type": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" },
    { "type": "cardholder", "id": "c4rdh0ld", "name": "Ferdinand Solara", "email": "f.solara@example.com" }
  ]
}

bank_transfer (bank account to bank account)​

Use this for transfers between bank accounts. The direction is expressed through sender and receiver. Include refs.merchant_business on the bank account entity that belongs to the merchant.

{
  "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": "DE89370400440532013000",
      "bank_account_number": "DE89370400440532013000",
      "name": "Deutsche Bank AG"
    },
    {
      "type": "bank_account",
      "id": "NL51INGB40123456789876",
      "bank_account_number": "NL51INGB40123456789876",
      "name": "ING Bank N.V.",
      "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" }
    }
  ]
}

Other events​

All event types supported by the scoring endpoint, are also supported for enrichment. See Financial Events Screening — Event types.

Entity types​

Supported entity types are the same as the scoring endpoint. See Financial Events Screening — Entity types.

Entities-only (pre-registration)​

Send entity snapshots or updates without any financial events by providing an empty events array. Use this on registration and whenever entity attributes change. Subsequent screening or enrichment calls can then reference these entities by id without re-sending full entity payloads.

Keep at least 2 seconds between an entity update and an event that references it (e.g. between merchant registration and the first transaction).

Request body: entities only
{
  "events": [],
  "entities": [
    {
      "type": "card",
      "id": "c67876543",
      "card_token": "67876543",
      "last_four_digits": "9876",
      "expiry_date": "1127",
      "refs": { "issuer": "b-450901", "cardholder": "c4rdh0ld" }
    },
    { "type": "cardholder", "id": "c4rdh0ld", "name": "Ferdinand Solara", "email": "f.solara@example.com" },
    {
      "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" }
    },
    { "type": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" }
  ]
}

Request parameters: Field Reference Table​

FieldData TypePayment Fraud (Issuer)Payment Fraud (Acquirer / Processor)Merchant Fraud / AMLDescription
events[].typeStringRequiredRequiredRequired
Event type to enrich. Examples: card_network_transaction, refund, void, capture, reversal, chargeback, dispute, wallet_withdrawal, wallet_deposit, payout, bank_transfer, wallet_transfer.
events[].idStringRequiredRequiredRequired
Unique identifier of the event.
events[].timestampDoubleRequiredRequiredRequired
UTC time of the event as a Unix timestamp (seconds; may be fractional).
events[].parent_event_idStringOptionalOptionalOptional
Direct parent transaction/event ID for chained events.
events[].lifecycle_rrnStringOptionalOptionalOptional
Lifecycle identifier shared across chained transactions (RRN).
events[].details.mtiStringOptionalOptionalOptional
ISO 8583 MTI when applicable.
events[].details.transaction_typeStringOptionalOptionalOptional
ISO 8583 DE003 transaction type when applicable.
events[].details.currencyStringOptionalOptionalOptional
3-digit ISO currency code.
events[].details.currency_unitStringOptionalOptionalOptional
major or minor.
events[].details.amountDoubleOptionalOptionalOptional
Amount in the currency and unit provided.
events[].details.response_codeStringOptionalOptionalOptional
Authorization or financial response code from the issuer/network (for example ISO 8583 DE039). Typical on 0110 / post-auth events.
events[].details.eciStringOptionalOptionalOptional
Electronic Commerce Indicator from 3-D Secure or equivalent authentication.
events[].details.avs_resultStringOptionalOptionalOptional
Address Verification System (AVS) result code.
events[].details.cvv_resultStringOptionalOptionalOptional
Card verification value (CVV/CVC) check result.
events[].details.cavv_resultStringOptionalOptionalOptional
Cardholder Authentication Verification Value (CAVV) or equivalent authentication result.
events[].details.sister_transaction_idStringOptionalOptionalOptional
ID of the counterpart record for the same transfer, used when a single transfer is represented by two records (e.g. one per side). When migrating from v1/transactions/inter-account-transfers, map receiver_transactionid here.
events[].details.pos_entry_modeStringOptionalOptionalOptional
ISO POS entry mode when applicable.
events[].details.pos_condition_codeStringOptionalOptionalOptional
ISO POS condition code when applicable.
events[].details.mccStringOptionalOptionalOptional
Merchant category code as processed on this event/transaction. Distinct from registered MCCs on a merchant_account or sub_merchant entity.
events[].sender.refs.cardStringOptionalOptionalOptional
Reference to a card entity when applicable.
events[].sender.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when the wallet is the sender (e.g., wallet withdrawal, payout events).
events[].sender.refs.merchant_businessStringOptionalOptionalOptional
Reference to a merchant_business entity when the merchant is the initiating party (e.g., wallet withdrawal, payout, chargeback lifecycle). Should be included alongside wallet reference for wallet-based events.
events[].sender.refs.bank_accountStringn.a.n.a.Optional
Reference to a bank_account entity when the bank account is the sender (e.g., wallet deposit events).
events[].receiver.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when the wallet is the receiver (e.g., wallet deposit events).
events[].receiver.refs.merchant_businessStringOptionalOptionalOptional
Reference to a merchant_business entity when the merchant is the receiving party. Should be included alongside wallet reference for wallet deposit events.
events[].receiver.refs.bank_accountStringn.a.n.a.Optional
Reference to a bank_account entity when the bank account is the receiver (e.g., wallet withdrawal events).
events[].receiver.refs.acceptorStringOptionalOptionalOptional
Reference to an acceptor entity when applicable.
events[].refs.gatewayStringOptionalOptionalOptional
Reference to the payment gateway (intermediary).
events[].refs.acquirerStringOptionalOptionalOptional
Reference to the acquirer (intermediary).
entities[]ArrayOptionalOptionalOptional
Top-level array of entity objects. Entities are correlated to events through refs, not by nesting.
entities[].typeStringOptionalOptionalOptional
Entity type, e.g. merchant_business, merchant_account, sub_merchant, card, wallet, acquirer, payfac, etc.
entities[].idStringOptionalOptionalOptional
Stable entity identifier.
entities[].nameStringOptionalOptionalOptional
Entity name when available.
entities[].country_codeStringOptionalOptionalOptional
Entity country code when available.
entities[].limitprofileStringOptionalOptionalOptional
Merchant limit profile (can be partial update; null to clear).
entities[].mccsArrayOptionalOptionalOptional
Registered / assigned MCC list on a merchant_account or sub_merchant entity. Do not send on merchant_business; use event.details.mcc for the as-processed code on a transaction.
entities[].midStringOptionalOptionalOptional
Processor- or acquirer-assigned Merchant ID on a merchant_account entity.
entities[].terminal_typeStringOptionalOptionalOptional
Cardholder-Activated Terminal (CAT) type on an acceptor entity (e.g. cat1, cat2, cat6, cat9).
entities[].type=bank_accountStringn.a.n.a.Optional
A bank account entity. Used as sender or receiver in wallet withdrawal and deposit events. The entity id is a stable identifier for the account.
entities[].ibanStringn.a.n.a.Optional
IBAN (or equivalent national account number) for bank_account entities.
entities[].refs.merchant_businessStringn.a.n.a.Optional
Reference from another entity to a merchant_business (e.g. wallet or bank account belonging to the merchant).

Response Parameters​

Status CodeStatus MessageDescriptionSchema
200OKStandard response for successful HTTP requests.200 OK - Financial Events Enrichment response
4xx, 500, 501, 502, 503, 504errorVarious error messages for unsuccessful HTTP requests.Problem response

Code Samples​

curl -X POST 'https://api.fraudio.com/v2/financial-events/enrichment' \
    -H 'Content-Type: application/json' \
    -H "authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{
  "events": [
    {
      "type": "card_network_transaction",
      "id": "auth-resp-001",
      "timestamp": 1770004000.123,
      "lifecycle_rrn": "123456789012",
      "parent_event_id": "a12c34def",
      "sender": { "refs": { "card": "c67876543" } },
      "receiver": { "refs": { "merchant_business": "hotel-bristol" } },
      "refs": { "acquirer": "b-7610201", "gateway": "molley" },
      "details": { "mti": "0110", "transaction_type": "purchase", "response_code": "00", "eci": "02", "avs_result": "Y", "cvv_result": "M", "cavv_result": "2" }
    }
  ],
  "entities": []
}'