Skip to main content
Version: 2.0

Financial Events Screening

Evaluate a financial event and receive a fraud recommendation from the Payment Fraud Detection product.

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

Typical request​

The request body is split into a main event and its associated entities. The event may refer to multiple entities by their id.

Events and entities can also be sent via the Financial Events Enrichment endpoint, for cases where no immediate fraud rating is required.

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

Typical response​

The response body is a fraud risk assessment informed by fraud rules and/or AI models. Depending on the source of the recommendation, more information may be present in the full response.

Response body
{
  "score": 0.12,
  "recommendation": "green"
}

Request structure​

A request consists of a top-level event object and an entities array, as shown in the typical request above. The sections below describe variations on this structure.

Pre-registered entities​

You can also send entity information separately from events. Register or update entities via the Financial Events Enrichment endpoint (entities-only payload), then omit entities from subsequent screening requests.

Restrictions:

  • Entity references in events must be resolvable, i.e. match an entity sent prior to the event.
  • Keep at least 2 seconds between an entity update and an event (e.g. between merchant registration and the first transaction).

PEP/sanctions check​

The optional options.plugins field enables additional plugins to run alongside standard fraud screening.

  • The plugin "sanctions_cardholder" checks the cardholder against global sanctions lists.
  • The plugin "pep_cardholder" checks the cardholder against Politically Exposed Persons lists.

These are per-transaction checks that make additional fields available for rules, and they may also return additional information in the API response. For checks outside the transaction context, see event type due_diligence. Product overview for KYC, KYB and PEP & Sanctions is available here.

info

Plugins incur additional per-event costs and may increase latency, as they rely on trusted external providers.

Request body: with PEP/sanctions check
{
  "event": {
    "type": "card_network_transaction",
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "sender": { "refs": { "card": "c67876543", "cardholder": "c4rdh0ld" } },
    "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",
      "refs": { "issuer": "b-450901", "cardholder": "c4rdh0ld" }
    },
    { "type": "cardholder", "id": "c4rdh0ld", "name": "Ferdinand Solara", "email": "f.solara@example.com", "country_code": "NLD" },
    { "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" } }
  ],
  "options": {
    "plugins": ["sanctions_cardholder", "pep_cardholder"]
  }
}
Response body: with PEP/sanctions check
{
  "score": 0.12,
  "recommendation": "green",
  "plugins": {
    "sanctions_cardholder": { "match": false },
    "pep_cardholder": { "match": false }
  }
}

Event types​

Categorization​

The event.type field on an event is its primary categorization. It determines what the event represents and which additional fields apply to it.

ValueDescription
card_network_transactionA card payment network message (authorization, capture, reversal, etc.). See MTI and transaction type below.
wallet_transferA direct transfer between two wallets.
wallet_card_enrollmentA card being linked to a wallet.
merchant_registrationA merchant being registered with an acquirer.
wallet_withdrawalA withdrawal from a wallet to a bank account.
wallet_depositA deposit from a bank account into a wallet.
bank_transferA transfer between two bank accounts.
disputeA chargeback, TC40, SAFE, or other fraud notification linked to a prior transaction.
due_diligenceA KYC or KYB checks of an individual or business with various risk intelligence sources.

Note that event.details.mti and event.details.transaction_type are ISO 8583 protocol fields. ISO 8583 is the messaging standard used by card payment networks (Visa, Mastercard, and others) to represent authorization requests, financial messages, reversals, and their responses. These fields carry meaning that is specific to that protocol: mti identifies the message class and function, while transaction_type encodes the ISO 8583 DE003 processing code. Events of type wallet_transfer, bank_transfer, dispute, and others represent financial flows that do not originate from the card payment network. They have no concept of an MTI or processing code. Their categorization is fully expressed by the type field, and direction is conveyed through sender and receiver.

mti: Message Type Indicator​

Fraudio accepts either the readable string value or the raw 4-digit ISO 8583 MTI code:

Readable valueMTIDescription
authorization_request0100Authorization request
authorization_response0110Authorization response
financial_request0200Financial transaction (capture) request
financial_response0210Financial transaction (capture) response
reversal_request0400Reversal request
reversal_response0410Reversal response
reversal_advice0420Reversal advice (acquirer-initiated, no response expected)

transaction_type: DE003 (Visa field 3) processing code​

event.details.transaction_type corresponds to the first two digits of ISO 8583 DE003 (the processing code). The remaining digits of DE003 (account type from digits 3–4, account type to digits 5–6) are expressed as sender.account_type and receiver.account_type on the event.

For transaction_type, Fraudio accepts either the readable string value or the raw ISO 8583 DE003 code:

Readable valueDE003 digits 1–2Description
purchase00Goods and services purchase
atm_withdrawal01ATM cash withdrawal
refund20Refund / return
oct26Original Credit Transaction (payout to card)
pin_change94PIN change / unblock

For processing codes not listed here, send the raw DE003 code directly.

Similarly, sender.account_type and receiver.account_type accept either a readable string or the raw DE003 subfield code:

ValueDE003 subfieldDescription
default00Unspecified (most common for merchants)
savings10Savings account
checking20Checking / current account
credit30Credit card account
revolving_credit90Revolving credit account

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

card_network_transaction (purchase auth)​

Authorization request. Use MTI 0100 and transaction_type: "purchase". This is the most common event to score, as the fraud check typically happens at auth time. See Transaction types for the full mapping.

{
  "event": {
    "type": "card_network_transaction",
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "lifecycle_rrn": "123456789012",
    "sender": { "account_type": "credit", "refs": { "card": "c67876543", "shopper": "5h0pp3r" } },
    "receiver": { "refs": { "merchant_business": "hotel-bristol", "merchant_account": "hotel-bristol-front", "acceptor": "terminal-zxcvb12" } },
    "refs": { "gateway": "molley", "acquirer": "b-7610201" },
    "details": {
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "type": "card",
      "id": "c67876543",
      "card_token": "67876543",
      "card_type": "credit",
      "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": "shopper", "id": "5h0pp3r", "name": "Catherine Solara", "email": "c.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": "acceptor", "id": "terminal-zxcvb12", "name": "Payment terminal 3", "make": "SumUp", "model": "Solo", "terminal_type": "cat9" },
    { "type": "acquirer", "id": "b-7610201", "bin": "7610201", "name": "Example Acquirer", "country_code": "PRT" },
    { "type": "gateway", "id": "molley", "name": "Molley Payment Gateway" },
    { "type": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" }
  ]
}

card_network_transaction (authorization response post-auth)​

For clients integrated post-authorization, the 0110 authorization response can be sent directly to this endpoint for screening. Use this when your fraud check happens after authorization, for example when you only have access to the response leg of the transaction.

Because no prior 0100 event exists in Fraudio's dataset, include the full transaction context: sender, receiver, and event.details.amount, event.details.currency, event.details.currency_unit. Link to the authorization request where possible using parent_event_id and/or lifecycle_rrn.

Pre-auth integrated clients

If you score the 0100 at authorization time, send the 0110 to the Financial Events Enrichment endpoint instead: sender, receiver, and event.details.amount, event.details.currency, event.details.currency_unit can be omitted there since they are established on the original event.

{
  "event": {
    "type": "card_network_transaction",
    "id": "auth-resp-001",
    "timestamp": 1770004000.123,
    "sender": { "refs": { "card": "c67876543" } },
    "receiver": { "refs": { "merchant_business": "hotel-bristol", "merchant_account": "hotel-bristol-front" } },
    "refs": { "acquirer": "b-7610201" },
    "details": {
      "mti": "0110",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "response_code": "00",
      "eci": "02",
      "avs_result": "Y",
      "cvv_result": "M",
      "cavv_result": "2"
    }
  },
  "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": "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" }
  ]
}

card_network_transaction (purchase capture)​

Financial transaction completing a prior auth. Use MTI 0200 and transaction_type: "purchase". Link to the auth using lifecycle_rrn and parent_event_id.

{
  "event": {
    "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" } },
    "refs": { "acquirer": "b-7610201" },
    "details": {
      "mti": "0200",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543" },
    { "type": "merchant_business", "id": "hotel-bristol" },
    { "type": "merchant_account", "id": "hotel-bristol-front", "mid": "8842101000123" },
    { "type": "acquirer", "id": "b-7610201" }
  ]
}

card_network_transaction (refund)​

Refund/return credited back to the cardholder. Use transaction_type: "refund". Most refunds are standalone financial messages (MTI 0200) with no prior auth. If your network requires a refund authorization cycle, send a 0100 first and then the 0200, both with transaction_type: "refund". Link to the original purchase using parent_event_id and/or lifecycle_rrn.

{
  "event": {
    "type": "card_network_transaction",
    "id": "c55a99xyz",
    "timestamp": 1770086400.000,
    "lifecycle_rrn": "123456789012",
    "parent_event_id": "a12c34def",
    "sender": { "refs": { "merchant_business": "hotel-bristol", "merchant_account": "hotel-bristol-front" } },
    "receiver": { "refs": { "card": "c67876543" } },
    "refs": { "acquirer": "b-7610201" },
    "details": {
      "mti": "0200",
      "transaction_type": "refund",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    { "type": "merchant_business", "id": "hotel-bristol" },
    { "type": "merchant_account", "id": "hotel-bristol-front", "mid": "8842101000123" },
    { "type": "card", "id": "c67876543" },
    { "type": "acquirer", "id": "b-7610201" }
  ]
}

card_network_transaction (ATM withdrawal)​

ATM cash withdrawals use transaction_type: "atm_withdrawal" and are sent as financial messages (MTI 0200). There is no counterparty receiving funds: the cardholder withdraws cash from their own account, so only sender is set, similar to a PIN change. The ATM terminal is contextual metadata referenced via refs. If your network performs an auth/financial cycle, send MTI 0100 first with the same transaction_type, then the 0200 linked via lifecycle_rrn.

{
  "event": {
    "type": "card_network_transaction",
    "id": "atm-evt-001",
    "timestamp": 1770090000.000,
    "lifecycle_rrn": "234567890123",
    "sender": { "refs": { "card": "c67876543" } },
    "refs": { "acquirer": "b-7610201", "acceptor": "atm-terminal-001" },
    "details": {
      "mti": "0200",
      "transaction_type": "atm_withdrawal",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 200.00
    }
  },
  "entities": [
    { "type": "card", "id": "c67876543" },
    { "type": "acceptor", "id": "atm-terminal-001", "name": "Example Bank ATM", "country_code": "NLD", "terminal_type": "cat1" },
    { "type": "acquirer", "id": "b-7610201" }
  ]
}

card_network_transaction (PIN change)​

PIN changes have an ISO-8583 DE003 processing code. Although it is not a fund transfer like most other transactions, it still has event type card_network_transaction with transaction_type: "pin_change". Note that there is no receiver. For events like these, the sender property denotes who initiated the transaction.

{
  "event": {
    "type": "card_network_transaction",
    "id": "pin-evt-001",
    "timestamp": 1770000123.456,
    "sender": { "refs": { "card": "c67876543" } },
    "details": {
      "mti": "0200",
      "transaction_type": "pin_change"
    }
  },
  "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": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" }
  ]
}

wallet_transfer (direct wallet-to-wallet)​

Use this for direct wallet-to-wallet transfers. The wallet is the instrument, but the actual party may be a linked card, merchant, or cardholder. Include that entity in sender.refs/receiver.refs alongside the wallet when funds move from or to a specific linked account rather than the wallet balance itself.

Sometimes, a single transfer is represented by two records (a sending and receiving transaction, e.g. when migrating from v1/transactions/inter-account-transfers). In this case, use the sender-side ID as the event id and carry the receiver-side ID in event.details.sister_transaction_id.

{
  "event": {
    "type": "wallet_transfer",
    "id": "cd99e97e-bb58-4148-caed-af26effefffd",
    "timestamp": 1770001000,
    "lifecycle_rrn": "123456789012",
    "sender": { "refs": { "wallet": "wallet-111", "card": "c67876543" } },
    "receiver": { "refs": { "wallet": "wallet-222" } },
    "details": {
      "sister_transaction_id": "d6a7b747-474f-bc95-98da-72b01855ba5b",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 125.5
    }
  },
  "entities": [
    { "type": "wallet", "id": "wallet-111" },
    { "type": "card", "id": "c67876543" },
    { "type": "wallet", "id": "wallet-222", "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" } }
  ]
}

wallet_card_enrollment (enrolling a card to a wallet)​

Use this for linking cards to wallets. Note that there is no "receiver", since the event is not related to the movement of funds.

{
  "event": {
    "type": "wallet_card_enrollment",
    "id": "reg-evt-001",
    "timestamp": 1770002000,
    "sender": { "refs": { "card": "c67876543", "wallet": "wlt-001" } }
  },
  "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": "issuer", "id": "b-450901", "bin": "450901", "name": "Example Issuer", "country_code": "PRT" },
    { "type": "wallet", "id": "wlt-001" }
  ]
}

merchant_registration (registering a merchant with an acquirer)​

Use this when a merchant is onboarded or registered with an acquirer. The registration is the event; send the merchant_business and the merchant_account as associated entities. Registered MCCs belong on the merchant_account. Note that there is no receiver, since the event is not related to the movement of funds.

{
  "event": {
    "type": "merchant_registration",
    "id": "merch-reg-001",
    "timestamp": 1770002500,
    "sender": { "refs": { "merchant_business": "hotel-bristol", "merchant_account": "hotel-bristol-front", "acquirer": "b-7610201" } }
  },
  "entities": [
    {
      "type": "merchant_business",
      "id": "hotel-bristol",
      "name": "Hotel Bristol B.V.",
      "email": "support@hotelbristol.example",
      "url": "www.hotelbristol.example",
      "country_code": "NLD",
      "city": "Amsterdam",
      "registered_timestamp": 1770002500
    },
    {
      "type": "merchant_account",
      "id": "hotel-bristol-front",
      "mid": "8842101000123",
      "mccs": ["7011"],
      "refs": { "merchant_business": "hotel-bristol", "acquirer": "b-7610201" }
    },
    {
      "type": "acquirer",
      "id": "b-7610201",
      "bin": "7610201",
      "name": "Example Acquirer",
      "country_code": "PRT"
    }
  ]
}

due_diligence (KYC / KYB checks)​

Use this event type to retrieve identity or business information about a customer or business from trusted external providers. Unlike the "sanctions_cardholder" and "pep_cardholder" plugins on a card_network_transaction event, which check the parties involved in a specific payment, due_diligence is a standalone request focused on understanding who an entity is, rather than what they are doing. It can be sent at onboarding or at any later point, including periodic or event-driven reviews such as a significant change in merchant volume or industry.

For due diligence checks, sender is the entity being assessed. The plugins field specifies which type of due diligence to perform: use "kyc_cardholder" for individuals (e.g. a cardholder) and "kyb_merchant" for businesses (e.g. a merchant_business). Additional due diligence types may be supported in future plugins.

Product-level documentation for KYC, KYB and PEP & Sanctions is available here.

KYC and KYB responses have different shapes, reflecting how external providers work in practice:

  • KYC providers verify an identity claim and return a clear outcome: whether the individual was found and whether the check passed. The response includes match and status fields.
  • KYB providers primarily return raw business information — registration details, directors, ownership structure — without a pass/fail assessment. The response is a details payload only.
info

Plugins incur additional per-event costs and may increase latency, as they rely on trusted external providers.

Request body: KYC due diligence
{
  "event": {
    "type": "due_diligence",
    "id": "dd-evt-001",
    "timestamp": 1770003000,
    "sender": { "refs": { "cardholder": "c4rdh0ld" } }
  },
  "entities": [
    { "type": "cardholder", "id": "c4rdh0ld", "name": "Ferdinand Solara", "email": "f.solara@example.com", "country_code": "NLD" }
  ],
  "options": {
    "plugins": ["kyc_cardholder"]
  }
}
Response body: KYC due diligence
{
  "score": 0.12,
  "recommendation": "green",
  "plugins": {
    "kyc_cardholder": {
      "match": true,
      "status": "refer",
      "full_name": "Ferdinand Solara",
      "date_of_birth": "1985-06-15",
      "nationality": "NLD",
      "address": "Damrak 1, 1011 AB Amsterdam, NL",
      "document_type": "passport",
      "document_number": "NL1234567",
      "document_expiry": "2030-06-14"
    }
  }
}
Request body: KYB due diligence
{
  "event": {
    "type": "due_diligence",
    "id": "dd-evt-002",
    "timestamp": 1770003000,
    "sender": { "refs": { "merchant_business": "hotel-bristol" } }
  },
  "entities": [
    { "type": "merchant_business", "id": "hotel-bristol", "name": "Hotel Bristol B.V.", "country_code": "NLD" }
  ],
  "options": {
    "plugins": ["kyb_merchant"]
  }
}
Response body: KYB due diligence
{
  "score": 0.12,
  "recommendation": "green",
  "plugins": {
    "kyb_merchant": {
      "details": {
        "legal_name": "Hotel Bristol B.V.",
        "registration_number": "12345678",
        "registration_date": "2015-03-12",
        "status": "active",
        "company_type": "BV",
        "country_code": "NLD",
        "registered_address": "Damrak 1, 1011 AB Amsterdam, NL",
        "industry_codes": ["7011"],
        "directors": [
          { "name": "Jane Doe", "role": "director", "appointed_date": "2015-03-12" }
        ],
        "ubos": [
          { "name": "Jane Doe", "ownership_percentage": 100 }
        ]
      }
    }
  }
}

Entity types​

A request can include entity snapshots or partial updates in the entities array. Each entity must have a type and a stable id. Note that entity IDs are expected to be unique. If there is no pre-existing entity ID, you can often use a natural key (e.g. card_token), a deterministic hash, or even a composite natural key to identify an entity (e.g. <device_make>-<device_model>-<device_serial_code>).

The following entity types are supported.

  • card: A payment card entity (or tokenized representation).
  • card_group: A proxy identifier used when a unique per-card ID is not available. See Card groups below.
  • cardholder: The cardholder entity (person or account holder).
  • shopper: The shopper/payer (can differ from the cardholder).
  • merchant_business: The merchant business (legal/commercial entity that sells). See Merchant business below.
  • merchant_account: A merchant account with an acquiring relationship; carries the processor-assigned mid. See Merchant account below.
  • sub_merchant: A sponsored merchant that processes under a Payment Facilitator. See Sub-merchant below.
  • acceptor: The accepting device/terminal entity.
  • wallet: A wallet entity (for wallet-to-wallet transfers or card registrations).
  • bank_account: A bank account entity (IBAN or equivalent).
  • issuer: Issuing bank/entity.
  • acquirer: Acquiring bank/entity. See Acquirer below.
  • merchant_service_provider: An Independent Sales Organisation (ISO) or similar intermediary that manages the merchant account. See Merchant Service Provider below.
  • payfac: A Payment Facilitator that aggregates sub-merchants under a master merchant account. See Payment Facilitator below.
  • ubo: The Ultimate Beneficial Owner of the merchant. See UBO below.
  • gateway: Payment gateway/intermediary.

Merchant category codes (MCCs) are modelled as follows:

  • Assigned / registered MCCs live on the account-like entity: merchant_account (direct account) or sub_merchant (PayFac-sponsored seller), via mccs.
  • As-processed MCC for a specific payment lives on the event, via event.details.mcc (or events[].details.mcc on enrichment).
  • Do not put mccs on the merchant_business entity. One business can hold several merchant_accounts, each with its own MCC(s).

Merchant business​

A merchant_business entity represents the merchant business: the legal or commercial party that sells goods or services. It carries descriptive and risk-relevant attributes such as name, country of registration, KYC level, and limit profile.

A single merchant_business can have multiple merchant_account entities, for example hotel-bristol-front (front desk / lodging) and hotel-bristol-resto (hotel restaurant). Registered MCCs belong on those account entities (or on a sub_merchant under a PayFac), not on the business itself.

merchant_business entities can be sent as full snapshots alongside a transaction, or as standalone partial updates whenever attributes change, for example when a merchant is onboarded or its limit profile is updated.

Example:

{
  "entities": [
    {
      "type": "merchant_business",
      "id": "hotel-bristol",
      "name": "Hotel Bristol B.V.",
      "email": "support@hotelbristol.example",
      "url": "www.hotelbristol.example",
      "ip": "34.231.107.3",
      "country_code": "NLD",
      "city": "Amsterdam",
      "state_code": "NH",
      "postal_code": "1011 AB",
      "street_address": "Damrak 1",
      "geo_coordinates": "+52.3676+004.9041/",
      "limit_profile": "2000",
      "kyc_level": "3",
      "kyc_level_norm": 0.6,
      "ocpt_enabled": true,
      "turnover": 50000,
      "registered_timestamp": 1760000000,
      "refs": {
        "wallet": "wlt-hotel-bristol",
        "ubo": "ubo-jdoe"
      }
    }
  ]
}

Card groups​

Card references are usually explicit. If you have a stable per-card identifier, use event.sender.refs.card. If you do not (which can be the case for some clients), you can use event.sender.refs.card_group as a proxy.

  • Meaning: A card_group represents a group of cards that share context when you cannot uniquely identify a single card.
  • Limitations:
    • Not unique per card (context is shared across cards in the group)
    • No additional entity attributes should be sent on card_group (e.g. there is no single cardholder)
    • An ID for the group is still required. If you do not have one, take a collision-resistant hash of the BIN, last 4 digits and expiry date.

Example using card_group:

{
  "event": {
    "type": "card_network_transaction",
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "sender": {
      "refs": {
        "card_group": "2178912839821380189023190"
      }
    },
    "receiver": {
      "refs": {
        "merchant_business": "hotel-bristol"
      }
    },
    "details": {
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "type": "card_group",
      "id": "2178912839821380189023190",
      "bin": "7610201",
      "expiry_date": "1127",
      "last_four_digits": "9876"
    }
  ]
}

Acquirer​

An acquirer entity represents the acquiring bank or payment processor that settles card payments on behalf of a merchant account. When sending account information that includes acquirer details, those fields should be sent as a separate acquirer entity and referenced from the merchant_account (or from a sub_merchant / payfac relationship) via refs.acquirer.

Example:

{
  "entities": [
    {
      "type": "acquirer",
      "id": "acquirer-x",
      "name": "Acquirer X",
      "country_code": "BEL"
    }
  ]
}

Merchant account​

A merchant_account entity represents a merchant account: the acquiring relationship under which card payments are processed. The processor- or acquirer-assigned Merchant ID is the mid property on this entity; it is not a separate entity type and does not uniquely identify the merchant business. A single merchant_business can have multiple merchant_account entities (for example one for front desk / lodging and one for the hotel restaurant).

Registered / assigned MCCs for that account belong here as mccs (typically the primary MCC for the account; additional codes only when the account is legitimately multi-MCC). The MCC that rode on a specific payment belongs on the transaction as details.mcc.

Reference a merchant_account from events with sender.refs.merchant_account / receiver.refs.merchant_account, and link it to the business with refs.merchant_business. Acquirer, merchant service provider, and related account parties are usually referenced from the merchant_account as well.

Example (one business, two accounts):

{
  "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",
        "acquirer": "acquirer-x",
        "merchant_service_provider": "msp-abc"
      }
    },
    {
      "type": "merchant_account",
      "id": "hotel-bristol-resto",
      "mid": "8842101000456",
      "mccs": ["5812"],
      "refs": {
        "merchant_business": "hotel-bristol",
        "acquirer": "acquirer-x"
      }
    }
  ]
}

Sub-merchant​

A sub_merchant entity represents a sponsored merchant that accepts payments under a Payment Facilitator (payfac) rather than under its own direct merchant account. Traffic typically clears under the PayFac's master MID; the sub-merchant is identified separately for network reporting, chargebacks, and risk.

Registered / assigned MCCs for the sponsored seller belong here as mccs. The MCC used on a specific payment still belongs on the transaction as details.mcc.

Reference a sub_merchant from events with sender.refs.sub_merchant / receiver.refs.sub_merchant, and link it to the PayFac (and optionally the merchant business) via refs.

Example:

{
  "entities": [
    {
      "type": "merchant_business",
      "id": "bloom-florist-bv",
      "name": "Bloom Florist B.V.",
      "country_code": "NLD"
    },
    {
      "type": "sub_merchant",
      "id": "bloom-florist",
      "name": "Bloom Florist",
      "country_code": "NLD",
      "mccs": ["5992"],
      "refs": {
        "payfac": "payfac-xyz",
        "merchant_business": "bloom-florist-bv"
      }
    }
  ]
}

Merchant Service Provider​

A merchant_service_provider entity represents an Independent Sales Organisation (ISO) or similar intermediary that manages the merchant account on behalf of the acquiring bank.

Example:

{
  "entities": [
    {
      "type": "merchant_service_provider",
      "id": "msp-abc",
      "name": "ABC Sales Organisation",
      "country_code": "NLD"
    }
  ]
}

Payment Facilitator​

A payfac entity represents a Payment Facilitator: an organisation that onboards and aggregates sponsored sellers (sub_merchant) under its own master merchant_account with an acquirer. The PayFac typically holds that master account (with its own mid); sub-merchants do not each receive a bank-issued MID.

Example:

{
  "entities": [
    {
      "type": "payfac",
      "id": "payfac-xyz",
      "name": "XYZ Payment Facilitator",
      "country_code": "DEU",
      "refs": {
        "acquirer": "acquirer-x",
        "merchant_account": "payfac-xyz-master"
      }
    },
    {
      "type": "merchant_account",
      "id": "payfac-xyz-master",
      "mid": "PFAC000991122",
      "refs": {
        "acquirer": "acquirer-x"
      }
    }
  ]
}

UBO​

A ubo entity represents the Ultimate Beneficial Owner - the individual who is registered as the owner of the merchant account.

Example:

{
  "entities": [
    {
      "type": "ubo",
      "id": "ubo-jdoe",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "phone_number": "+31612345678",
      "country_code": "NLD",
      "street_address": "Keizersgracht 123, Amsterdam"
    }
  ]
}

Partial entity updates​

Entities can be sent either as full snapshots or as partial updates.

  • Partial update: send type + id, plus only the fields that changed.
  • Unspecified fields: treated as unchanged.
  • Clearing a field: send it as null.

Example (partial update clearing a merchant limit_profile):

{
  "entities": [
    {
      "type": "merchant_business",
      "id": "hotel-bristol",
      "limit_profile": null
    }
  ]
}

Plugins and workflows​

Supported plugins​

Plugins are normally provided as a simple list in the request field options.plugins.

{
  "event": {...}
  "options": {
    "plugins": ["pep_cardholder"]
  }
}

The following plugins are supported.

  • kyb_merchant: Know Your Business (KYB) check for a merchant.
  • kyc_cardholder: Know Your Customer (KYC) check for a cardholder.
  • pep_cardholder: Politically Exposed Person (PEP) check for a cardholder.
  • pep_ubo: Politically Exposed Person (PEP) check for an ultimate business owner (UBO).
  • sanctions_cardholder: Sanctions check for a cardholder.
  • sanctions_ubo: Sanctions check for an ultimate business owner (UBO).

Workflows​

Some checks may use multiple plugins, where one plugin is a prerequisite for another. For example, a kyb_merchant check followed by a pep_ubo check on the business owner. In these cases, you can use the optional options.workflow field instead of the options.plugins field. Each workflow step must provide a list of dependencies, and they are executed in that order. Whenever possible, the steps are executed in parallel to minimize latency.

info

Workflows may not have circular dependencies. If they do occur, the workflow is invalid and no plugins are executed.

Request body: KYB due diligence
{
  "event": {
    "type": "due_diligence",
    "id": "dd-evt-002",
    "timestamp": 1770003000,
    "sender": { "refs": { "merchant_business": "hotel-bristol" } }
  },
  "entities": [
    { "type": "merchant_business", "id": "hotel-bristol", "name": "Hotel Bristol B.V.", "country_code": "NLD" }
  ],
  "options": {
    "workflow": {
      "kyb_merchant": [],
      "pep_ubo": ["kyb_merchant"]
    }
  }
}
Response body: KYB due diligence
{
  "score": 0.12,
  "recommendation": "green",
  "plugins": {
    "kyb_merchant": {
      "details": {
        "legal_name": "Hotel Bristol B.V.",
        "registration_number": "12345678",
        "registration_date": "2015-03-12",
        "status": "active",
        "company_type": "BV",
        "country_code": "NLD",
        "registered_address": "Damrak 1, 1011 AB Amsterdam, NL",
        "industry_codes": ["7011"],
        "directors": [
          { "name": "Jane Doe", "role": "director", "appointed_date": "2015-03-12" }
        ],
        "ubos": [
          { "name": "Jane Doe", "ownership_percentage": 100 }
        ]
      }
    },
    "pep_ubo": { "match": false }
  }
}

Fields reference table​

FieldData TypePayment Fraud (Issuer)Payment Fraud (Acquirer / Processor)Merchant Fraud / AMLDescription
event.typeStringRequiredRequiredRequired
Event type. For payment fraud scoring use types such as card_network_transaction. For standalone KYC/KYB use due_diligence. PEP/sanctions plugins can run on card_network_transaction (parties in the payment) or on due_diligence / workflow steps.
event.idStringRequiredRequiredRequired
Unique identifier of the event.
event.timestampDoubleRequiredRequiredRequired
UTC time of the event as a Unix timestamp (seconds; may be fractional).
event.lifecycle_rrnStringOptionalOptionalOptional
Lifecycle identifier shared across chained transactions (RRN).
event.parent_event_idStringOptionalOptionalOptional
Direct parent transaction/event ID for chained events (backwards compatibility).
event.details.mtiStringOptionalOptionalOptional
ISO 8583 MTI when applicable.
event.details.transaction_typeStringOptionalOptionalOptional
ISO 8583 DE003 transaction type when applicable.
event.details.currencyStringOptionalOptionalOptional
3-digit ISO currency code.
event.details.currency_unitStringOptionalOptionalOptional
major or minor.
event.details.amountDoubleOptionalOptionalOptional
Amount in the currency and unit provided.
event.details.response_codeStringOptionalOptionalOptional
Authorization or financial response code from the issuer/network (for example ISO 8583 DE039). Typical on 0110 / post-auth events.
event.details.eciStringOptionalOptionalOptional
Electronic Commerce Indicator from 3-D Secure or equivalent authentication.
event.details.avs_resultStringOptionalOptionalOptional
Address Verification System (AVS) result code.
event.details.cvv_resultStringOptionalOptionalOptional
Card verification value (CVV/CVC) check result.
event.details.cavv_resultStringOptionalOptionalOptional
Cardholder Authentication Verification Value (CAVV) or equivalent authentication result.
event.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.
event.details.pos_entry_modeStringOptionalOptionalOptional
ISO POS entry mode when applicable.
event.details.pos_condition_codeStringOptionalOptionalOptional
ISO POS condition code when applicable.
event.details.mccStringOptionalOptionalOptional
Merchant category code as processed on this event/transaction. Distinct from registered MCCs on a merchant_account or sub_merchant entity.
event.sender.refs.cardStringOptionalOptionalOptional
Reference to a card entity when available.
event.sender.refs.card_groupStringOptionalOptionalOptional
Reference to a card_group proxy when no unique card ID is available.
event.sender.refs.shopperStringOptionalOptionalOptional
Reference to a shopper entity when applicable.
event.sender.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when applicable.
event.sender.ipStringOptionalOptionalOptional
Sender IP address when applicable.
event.sender.geocoordinatesStringOptionalOptionalOptional
Sender geocoordinates.
event.receiver.refs.merchant_businessStringOptionalOptionalOptional
Reference to a merchant_business entity when applicable.
event.receiver.refs.merchant_accountStringOptionalOptionalOptional
Reference to a merchant_account entity when applicable.
event.receiver.refs.sub_merchantStringOptionalOptionalOptional
Reference to a sub_merchant entity when the seller processes under a Payment Facilitator.
event.receiver.refs.acceptorStringOptionalOptionalOptional
Reference to an acceptor (terminal/device) entity when applicable.
event.receiver.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when applicable.
event.receiver.ipStringOptionalOptionalOptional
Receiver IP address when applicable.
event.receiver.geocoordinatesStringOptionalOptionalOptional
Receiver geocoordinates.
event.refs.gatewayStringOptionalOptionalOptional
Reference to the payment gateway (intermediary).
event.refs.acquirerStringOptionalOptionalOptional
Reference to the acquirer (intermediary).
entities[]ArrayOptionalOptionalOptional
Optional entity objects included alongside the event.
entities[].typeStringOptionalOptionalOptional
Entity type, e.g. card, card_group, merchant_business, merchant_account, sub_merchant, wallet, acceptor, issuer, acquirer, payfac, gateway, cardholder, shopper.
entities[].idStringOptionalOptionalOptional
Stable entity identifier.
entities[].refsObjectOptionalOptionalOptional
Optional nested references to other entities.
entities[].card_tokenStringOptionalOptionalOptional
Card token when sending full card entity.
entities[].last_four_digitsStringOptionalOptionalOptional
Last 4 digits when sending full card entity.
entities[].expiry_dateStringOptionalOptionalOptional
Expiry date when sending full card entity.
entities[].registered_onDoubleOptionalOptionalOptional
Registration timestamp for merchant when available.
entities[].limitprofileStringOptionalOptionalOptional
Merchant limit profile when available.
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[].binStringOptionalOptionalOptional
BIN for issuer/acquirer entities when available.
entities[].country_codeStringOptionalOptionalOptional
Country code for issuer/acquirer/merchant when available.

Response codes​

Status CodeStatus MessageDescriptionSchema
200OKStandard response for successful HTTP requests.200 OK - Screening 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/screening' \
    -H 'Content-Type: application/json' \
    -H "authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{
  "event": {
    "type": "card_network_transaction",
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "sender": { "refs": { "card": "c67876543" } },
    "receiver": { "refs": { "merchant_business": "hotel-bristol" } },
    "details": { "mti": "0100", "transaction_type": "purchase", "currency": "EUR", "currency_unit": "major", "amount": 42.1 }
  },
  "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" }
  ]
}'