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": {
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01" } },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770000000.123,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
      }
    },
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770000000.123,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
      }
    },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770000000.123, "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770000000.123, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770000000.123, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } },
    { "issuer": { "id": "b-450901", "timestamp": 1770000000.123, "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).

Labels​

Events and entities may include an optional labels object: a flat map of client-defined string keys to string values. Fraudio does not define a schema for the keys. Nested objects, arrays, and non-string values are not allowed.

Use this for values that have no first-class field, such as a hotel PMS confirmation number or that merchant's own loyalty member id.

Request body: with labels
{
  "event": {
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "labels": {
      "opera_conf_no": "8745123",
      "opera_folio": "11804"
    },
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01" } },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "cardholder": {
        "id": "c4rdh0ld",
        "timestamp": 1770000000.123,
        "name": "Ferdinand Solara",
        "email": "f.solara@example.com",
        "labels": {
          "bristol_loyalty_no": "HB-441908",
          "opera_name_id": "N-902184"
        }
      }
    }
  ]
}

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": {
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01", "cardholder": "c4rdh0ld" } },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770000000.123,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
      }
    },
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770000000.123,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
      }
    },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770000000.123, "name": "Ferdinand Solara", "email": "f.solara@example.com", "country_code": "NLD" } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770000000.123, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770000000.123, "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​

An event carries exactly one event-type payload key (oneOf semantics), for example card_network_transaction or dispute. That key is the event's primary categorization: it names what the event represents and holds the type-specific fields.

Payload keyDescription
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_paymentA payment to a merchant from a wallet, not a card-network purchase.
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.card_network_transaction.mti and event.card_network_transaction.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 with payload keys such as wallet_payment, wallet_transfer, bank_transfer, or dispute 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 payload key, and direction is conveyed through sender and receiver on that payload.

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.card_network_transaction.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 event.card_network_transaction.sender.account_type and event.card_network_transaction.receiver.account_type.

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, event.card_network_transaction.sender.account_type and event.card_network_transaction.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 payload keys 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": {
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "lifecycle_rrn": "123456789012",
    "card_network_transaction": {
      "sender": { "account_type": "credit", "refs": { "card": "card-ferdinand-01", "shopper": "5h0pp3r" } },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front", "acceptor": "terminal-zxcvb12" } },
      "refs": { "gateway": "molley", "acquirer": "b-7610201" },
      "mti": "0100",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770000000.123,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
      }
    },
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770000000.123,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
      }
    },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770000000.123, "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
    { "shopper": { "id": "5h0pp3r", "timestamp": 1770000000.123, "name": "Catherine Solara", "email": "c.solara@example.com" } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770000000.123, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770000000.123, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } },
    { "acceptor": { "id": "terminal-zxcvb12", "timestamp": 1770000000.123, "name": "Payment terminal 3", "make": "SumUp", "model": "Solo", "terminal_type": "cat9" } },
    { "acquirer": { "id": "b-7610201", "timestamp": 1770000000.123, "bin": "7610201", "name": "Example Acquirer", "country_code": "PRT" } },
    { "gateway": { "id": "molley", "timestamp": 1770000000.123, "name": "Molley Payment Gateway" } },
    { "issuer": { "id": "b-450901", "timestamp": 1770000000.123, "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: event.card_network_transaction.sender, event.card_network_transaction.receiver, and event.card_network_transaction.amount, event.card_network_transaction.currency, event.card_network_transaction.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: event.card_network_transaction.sender, event.card_network_transaction.receiver, and event.card_network_transaction.amount, event.card_network_transaction.currency, event.card_network_transaction.currency_unit can be omitted there since they are established on the original event.

{
  "event": {
    "id": "auth-resp-001",
    "timestamp": 1770004000.123,
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01" } },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "refs": { "acquirer": "b-7610201" },
      "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": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770004000.123,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
      }
    },
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770004000.123,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
      }
    },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770004000.123, "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770004000.123, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770004000.123, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } },
    { "acquirer": { "id": "b-7610201", "timestamp": 1770004000.123, "bin": "7610201", "name": "Example Acquirer", "country_code": "PRT" } },
    { "issuer": { "id": "b-450901", "timestamp": 1770004000.123, "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": {
    "id": "b99f12abc",
    "timestamp": 1770000300.456,
    "lifecycle_rrn": "123456789012",
    "parent_event_id": "a12c34def",
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01" } },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "refs": { "acquirer": "b-7610201" },
      "mti": "0200",
      "transaction_type": "purchase",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    { "card_account": { "id": "ca-ferdinand", "timestamp": 1770000300.456 } },
    { "card": { "id": "card-ferdinand-01", "timestamp": 1770000300.456, "refs": { "card_account": "ca-ferdinand" } } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770000300.456 } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770000300.456, "mid": "8842101000123", "refs": { "merchant_business": "hotel-bristol" } } },
    { "acquirer": { "id": "b-7610201", "timestamp": 1770000300.456 } }
  ]
}

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": {
    "id": "c55a99xyz",
    "timestamp": 1770086400.000,
    "lifecycle_rrn": "123456789012",
    "parent_event_id": "a12c34def",
    "card_network_transaction": {
      "sender": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "receiver": { "refs": { "card": "card-ferdinand-01" } },
      "refs": { "acquirer": "b-7610201" },
      "mti": "0200",
      "transaction_type": "refund",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770086400.000 } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770086400.000, "mid": "8842101000123", "refs": { "merchant_business": "hotel-bristol" } } },
    { "card_account": { "id": "ca-ferdinand", "timestamp": 1770086400.000 } },
    { "card": { "id": "card-ferdinand-01", "timestamp": 1770086400.000, "refs": { "card_account": "ca-ferdinand" } } },
    { "acquirer": { "id": "b-7610201", "timestamp": 1770086400.000 } }
  ]
}

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": {
    "id": "atm-evt-001",
    "timestamp": 1770090000.000,
    "lifecycle_rrn": "234567890123",
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01" } },
      "refs": { "acquirer": "b-7610201", "acceptor": "atm-terminal-001" },
      "mti": "0200",
      "transaction_type": "atm_withdrawal",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 200.00
    }
  },
  "entities": [
    { "card_account": { "id": "ca-ferdinand", "timestamp": 1770090000.000 } },
    { "card": { "id": "card-ferdinand-01", "timestamp": 1770090000.000, "refs": { "card_account": "ca-ferdinand" } } },
    { "acceptor": { "id": "atm-terminal-001", "timestamp": 1770090000.000, "name": "Example Bank ATM", "country_code": "NLD", "terminal_type": "cat1" } },
    { "acquirer": { "id": "b-7610201", "timestamp": 1770090000.000 } }
  ]
}

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 uses the card_network_transaction payload with transaction_type: "pin_change". Note that there is no receiver. For events like these, the sender property denotes who initiated the transaction.

{
  "event": {
    "id": "pin-evt-001",
    "timestamp": 1770000123.456,
    "card_network_transaction": {
      "sender": { "refs": { "card": "card-ferdinand-01" } },
      "mti": "0200",
      "transaction_type": "pin_change"
    }
  },
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770000123.456,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
      }
    },
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770000123.456,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
      }
    },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770000123.456, "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
    { "issuer": { "id": "b-450901", "timestamp": 1770000123.456, "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 event.wallet_transfer.sender.refs/event.wallet_transfer.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.wallet_transfer.sister_transaction_id.

{
  "event": {
    "id": "cd99e97e-bb58-4148-caed-af26effefffd",
    "timestamp": 1770001000,
    "lifecycle_rrn": "123456789012",
    "wallet_transfer": {
      "sender": { "refs": { "wallet": "wallet-111", "card": "card-ferdinand-01" }, "ip": "203.0.113.10", "geocoordinates": "+52.3676+004.9041/" },
      "receiver": { "refs": { "wallet": "wallet-222" }, "ip": "198.51.100.42", "geocoordinates": "+38.7223-009.1393/" },
      "sister_transaction_id": "d6a7b747-474f-bc95-98da-72b01855ba5b",
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 125.5
    }
  },
  "entities": [
    { "wallet": { "id": "wallet-111", "timestamp": 1770001000 } },
    { "card_account": { "id": "ca-ferdinand", "timestamp": 1770001000 } },
    { "card": { "id": "card-ferdinand-01", "timestamp": 1770001000, "refs": { "card_account": "ca-ferdinand" } } },
    { "wallet": { "id": "wallet-222", "timestamp": 1770001000, "refs": { "merchant_business": "hotel-bristol" } } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770001000, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770001000, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } }
  ]
}

wallet_payment (wallet to merchant)​

Use this when a payer pays a merchant from a wallet, not via the card payment network. Do not send these flows as card_network_transaction.

Sender typically references a wallet and/or a bank_account (when the payment is funded from a linked bank account rather than wallet balance). Receiver typically references merchant_account, merchant_business, or sub_merchant. Send the as-processed MCC on event.wallet_payment.mcc; registered MCCs still belong on the merchant entity.

{
  "event": {
    "id": "wp-evt-001",
    "timestamp": 1770001100,
    "wallet_payment": {
      "sender": { "refs": { "wallet": "wallet-111" }, "ip": "203.0.113.10", "geocoordinates": "+52.3676+004.9041/" },
      "receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    { "wallet": { "id": "wallet-111", "timestamp": 1770001100 } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770001100, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770001100, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } }
  ]
}

wallet_card_enrollment (enrolling a card to a wallet)​

Use this when a plastic/virtual card is provisioned into a wallet. Link the card and wallet on the event; the card entity should point at its card_account via refs. Do not send network token values (DPAN); Fraudio only accepts opaque processor card_reference ids, PAR, and fingerprints. Note that there is no receiver, since the event is not related to the movement of funds.

{
  "event": {
    "id": "reg-evt-001",
    "timestamp": 1770002000,
    "wallet_card_enrollment": {
      "sender": {
        "refs": {
          "card": "card-ferdinand-01",
          "wallet": "wlt-001"
        }
      }
    }
  },
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770002000,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
      }
    },
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770002000,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
      }
    },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770002000, "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
    { "issuer": { "id": "b-450901", "timestamp": 1770002000, "bin": "450901", "name": "Example Issuer", "country_code": "PRT" } },
    { "wallet": { "id": "wlt-001", "timestamp": 1770002000 } }
  ]
}

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": {
    "id": "merch-reg-001",
    "timestamp": 1770002500,
    "merchant_registration": {
      "sender": { "refs": { "merchant_account": "hotel-bristol-front", "acquirer": "b-7610201" } }
    }
  },
  "entities": [
    {
      "merchant_business": {
        "id": "hotel-bristol",
        "timestamp": 1770002500,
        "name": "Hotel Bristol B.V.",
        "email": "support@hotelbristol.example",
        "url": "www.hotelbristol.example",
        "country_code": "NLD",
        "city": "Amsterdam",
        "registered_timestamp": 1770002500
      }
    },
    {
      "merchant_account": {
        "id": "hotel-bristol-front",
        "timestamp": 1770002500,
        "mid": "8842101000123",
        "mccs": ["7011"],
        "refs": { "merchant_business": "hotel-bristol", "acquirer": "b-7610201" }
      }
    },
    {
      "acquirer": {
        "id": "b-7610201",
        "timestamp": 1770002500,
        "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": {
    "id": "dd-evt-001",
    "timestamp": 1770003000,
    "due_diligence": {
      "sender": { "refs": { "cardholder": "c4rdh0ld" } }
    }
  },
  "entities": [
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770003000, "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": {
    "id": "dd-evt-002",
    "timestamp": 1770003000,
    "due_diligence": {
      "sender": { "refs": { "merchant_business": "hotel-bristol" } }
    }
  },
  "entities": [
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770003000, "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 array item is a single-key object whose key is the entity type (oneOf), e.g. { "card_account": { ... } }. The nested object must have a stable id and a timestamp (when the snapshot was observed / is valid). An optional labels object may carry client-defined string key-value pairs that have no first-class schema field. 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. par, card_reference), 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_account: The underlying payment account (PAN/PAR level). See Card account below.
  • card: An issued plastic or virtual card instance under a card_account. See Card below.
  • card_group: Degraded fallback when account/card ids are unavailable. See Card groups below.
  • cardholder: The cardholder (person). Link to accounts and plastics via refs.cardholders on those entities (M:N at account level; one or two names on a plastic).
  • 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 payments, 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.

Card identifiers are modelled as follows:

  • card_account: stable account identity via par (preferred) and/or pan_fingerprint; optional opaque card_reference when the client's processor vault token is PAN/account-scoped; holders via refs.cardholders.
  • card: a specific issued instance under that account (e.g. card_sequence_number); opaque card_reference when the client's id is instance-scoped; embossed names via refs.cardholders (1–2).
  • card_reference: a single processor-scoped opaque vault or CMS id (issuing or acquiring side). Put it on the entity that matches what the vault bound. Never send PAN or network token (DPAN) values.
  • On a payment event, prefer card (or card_group as a degraded fallback) in the event-type payload's sender/receiver refs; link the account via card.refs.card_account on the entity rather than also putting card_account on the event. Prefer merchant_account over also putting merchant_business on the event; link the business via merchant_account.refs.merchant_business. Use singular sender.refs.cardholder when naming who initiated the payment. Wallet flows add wallet alongside card.

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.card_network_transaction.mcc or event.wallet_payment.mcc (or the enrichment equivalents).
  • Do not put mccs on the merchant_business entity. One business can hold several merchant_accounts, each with its own MCC(s).

Card account​

A card_account entity represents the underlying payment account (the PAN/PAR level). Prefer par when available; otherwise pan_fingerprint. When your processor vault token is bound to the PAN (typical acquiring/PSP card-on-file), also send card_reference. One account can have multiple cardholders (shared accounts) and multiple card instances. Link holders with refs.cardholders (array of cardholder entity ids).

Example (issuer-side, PAR known):

{
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770000000,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "refs": {
          "issuer": "b-450901",
          "cardholders": ["c4rdh0ld"]
        }
      }
    }
  ]
}

Example (acquiring/PSP vault token at account level):

{
  "entities": [
    {
      "card_account": {
        "id": "ca-ferdinand",
        "timestamp": 1770000000,
        "par": "5001ABCDEFGHIJKLMNOPQRSTUV",
        "pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
        "card_reference": "pm_tok_9f3a2c1b",
        "refs": {
          "cardholders": ["c4rdh0ld"]
        }
      }
    }
  ]
}

Card​

A card entity represents an issued plastic or virtual instance under a card_account (for example distinguished by card_sequence_number). When your opaque id is instance-scoped (typical issuer CMS / CSN-level card id), send it as card_reference. Link embossed names with refs.cardholders: one id for a single-name plastic, or two ids when the plastic carries two names. Do not send more than two on a card.

Example (single name):

{
  "entities": [
    {
      "card": {
        "id": "card-ferdinand-01",
        "timestamp": 1770000000,
        "card_sequence_number": "01",
        "card_reference": "iss-card-77881234",
        "bin": "450901",
        "last_four_digits": "9876",
        "expiry_date": "1127",
        "card_type": "credit",
        "refs": {
          "card_account": "ca-ferdinand",
          "cardholders": ["c4rdh0ld"],
          "issuer": "b-450901"
        }
      }
    }
  ]
}

Example (dual name on one plastic):

{
  "entities": [
    {
      "card": {
        "id": "card-joint-01",
        "timestamp": 1770000000,
        "card_sequence_number": "01",
        "card_reference": "iss-card-99110022",
        "bin": "450901",
        "last_four_digits": "4455",
        "expiry_date": "0828",
        "card_type": "debit",
        "refs": {
          "card_account": "ca-joint",
          "cardholders": ["c4rdh0ld", "ch-partner"],
          "issuer": "b-450901"
        }
      }
    }
  ]
}

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": [
    {
      "merchant_business": {
        "id": "hotel-bristol",
        "timestamp": 1770000000,
        "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​

Use card_group only as a degraded fallback when you cannot send card_account or card. Prefer those entities whenever possible.

  • Meaning: A proxy built from coarse PAN metadata (typically a collision-resistant hash of BIN, last 4 digits, and expiry).
  • Limitations:
    • Not unique per account or plastic (context is shared across cards that share those fields)
    • No cardholder / account linkage beyond that hash
    • Still requires a stable id

Example using card_group:

{
  "event": {
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "card_network_transaction": {
      "sender": {
        "refs": {
          "card_group": "2178912839821380189023190"
        }
      },
      "receiver": {
        "refs": {
          "merchant_account": "hotel-bristol-front"
        }
      },
      "currency": "EUR",
      "currency_unit": "major",
      "amount": 42.1,
      "mcc": "7011"
    }
  },
  "entities": [
    {
      "card_group": {
        "id": "2178912839821380189023190",
        "timestamp": 1770000000.123,
        "bin": "450901",
        "expiry_date": "1127",
        "last_four_digits": "9876"
      }
    },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770000000.123, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770000000.123, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } }
  ]
}

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": [
    {
      "acquirer": {
        "id": "acquirer-x",
        "timestamp": 1770000000,
        "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 event as card_network_transaction.mcc or wallet_payment.mcc.

Reference a merchant_account from events with event.<event_type>.sender.refs.merchant_account / event.<event_type>.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": [
    {
      "merchant_business": {
        "id": "hotel-bristol",
        "timestamp": 1770000000,
        "name": "Hotel Bristol B.V.",
        "country_code": "NLD"
      }
    },
    {
      "merchant_account": {
        "id": "hotel-bristol-front",
        "timestamp": 1770000000,
        "mid": "8842101000123",
        "mccs": ["7011"],
        "refs": {
          "merchant_business": "hotel-bristol",
          "acquirer": "acquirer-x",
          "merchant_service_provider": "msp-abc"
        }
      }
    },
    {
      "merchant_account": {
        "id": "hotel-bristol-resto",
        "timestamp": 1770000000,
        "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 event as card_network_transaction.mcc or wallet_payment.mcc.

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

Example:

{
  "entities": [
    {
      "merchant_business": {
        "id": "bloom-florist-bv",
        "timestamp": 1770000000,
        "name": "Bloom Florist B.V.",
        "country_code": "NLD"
      }
    },
    {
      "sub_merchant": {
        "id": "bloom-florist",
        "timestamp": 1770000000,
        "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": [
    {
      "merchant_service_provider": {
        "id": "msp-abc",
        "timestamp": 1770000000,
        "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": [
    {
      "payfac": {
        "id": "payfac-xyz",
        "timestamp": 1770000000,
        "name": "XYZ Payment Facilitator",
        "country_code": "DEU",
        "refs": {
          "acquirer": "acquirer-x",
          "merchant_account": "payfac-xyz-master"
        }
      }
    },
    {
      "merchant_account": {
        "id": "payfac-xyz-master",
        "timestamp": 1770000000,
        "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": [
    {
      "ubo": {
        "id": "ubo-jdoe",
        "timestamp": 1770000000,
        "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": [
    {
      "merchant_business": {
        "id": "hotel-bristol",
        "timestamp": 1770000000,
        "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": {
    "id": "dd-evt-002",
    "timestamp": 1770003000,
    "due_diligence": {
      "sender": { "refs": { "merchant_business": "hotel-bristol" } }
    }
  },
  "entities": [
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770003000, "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.<event_type>ObjectRequiredRequiredRequired
Exactly one event-type payload key on the event (oneOf), e.g. card_network_transaction, wallet_payment, wallet_transfer, dispute, due_diligence. The key names the event kind; its object holds type-specific fields (formerly under details).
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.labelsObject[String, String]OptionalOptionalOptional
Optional flat map of client-defined string keys to string values. Keys have no Fraudio-defined schema. Nested objects, arrays, and non-string values are not allowed.
event.card_network_transaction.mtiStringOptionalOptionalOptional
ISO 8583 MTI when applicable.
event.card_network_transaction.transaction_typeStringOptionalOptionalOptional
ISO 8583 DE003 transaction type when applicable.
event.card_network_transaction.currencyStringOptionalOptionalOptional
3-digit ISO currency code.
event.card_network_transaction.currency_unitStringOptionalOptionalOptional
major or minor.
event.card_network_transaction.amountDoubleOptionalOptionalOptional
Amount in the currency and unit provided.
event.card_network_transaction.response_codeStringOptionalOptionalOptional
Authorization or financial response code from the issuer/network (for example ISO 8583 DE039). Typical on 0110 / post-auth events.
event.card_network_transaction.eciStringOptionalOptionalOptional
Electronic Commerce Indicator from 3-D Secure or equivalent authentication.
event.card_network_transaction.avs_resultStringOptionalOptionalOptional
Address Verification System (AVS) result code.
event.card_network_transaction.cvv_resultStringOptionalOptionalOptional
Card verification value (CVV/CVC) check result.
event.card_network_transaction.cavv_resultStringOptionalOptionalOptional
Cardholder Authentication Verification Value (CAVV) or equivalent authentication result.
event.wallet_transfer.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.wallet_payment.currencyStringOptionalOptionalOptional
3-digit ISO currency code.
event.wallet_payment.currency_unitStringOptionalOptionalOptional
major or minor.
event.wallet_payment.amountDoubleOptionalOptionalOptional
Amount in the currency and unit provided.
event.wallet_payment.mccStringOptionalOptionalOptional
Merchant category code as processed on this wallet payment. Distinct from registered MCCs on a merchant_account or sub_merchant entity. Do not use card_network_transaction for wallet-to-merchant payments.
event.card_network_transaction.pos_entry_modeStringOptionalOptionalOptional
ISO POS entry mode when applicable.
event.card_network_transaction.pos_condition_codeStringOptionalOptionalOptional
ISO POS condition code when applicable.
event.card_network_transaction.mccStringOptionalOptionalOptional
Merchant category code as processed on this event/transaction. Distinct from registered MCCs on a merchant_account or sub_merchant entity.
event.<event_type>.sender.refs.cardStringOptionalOptionalOptional
Reference to a card (issued plastic/virtual instance) when that credential was used.
event.<event_type>.sender.refs.card_accountStringOptionalOptionalOptional
Reference to a card_account (PAR/PAN-level payment account) when known.
event.<event_type>.sender.refs.card_groupStringOptionalOptionalOptional
Degraded fallback reference to a card_group when card_account / card are unavailable.
event.<event_type>.sender.refs.shopperStringOptionalOptionalOptional
Reference to a shopper entity when applicable.
event.<event_type>.sender.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when applicable.
event.<event_type>.sender.refs.bank_accountStringOptionalOptionalOptional
Reference to a bank_account entity when applicable (for example a wallet_payment funded from a linked bank account).
event.<event_type>.sender.ipStringOptionalOptionalOptional
Sender IP address when applicable.
event.<event_type>.sender.geocoordinatesStringOptionalOptionalOptional
Sender geocoordinates.
event.<event_type>.receiver.refs.merchant_businessStringOptionalOptionalOptional
Reference to a merchant_business entity when applicable.
event.<event_type>.receiver.refs.merchant_accountStringOptionalOptionalOptional
Reference to a merchant_account entity when applicable.
event.<event_type>.receiver.refs.sub_merchantStringOptionalOptionalOptional
Reference to a sub_merchant entity when the seller processes under a Payment Facilitator.
event.<event_type>.receiver.refs.acceptorStringOptionalOptionalOptional
Reference to an acceptor (terminal/device) entity when applicable.
event.<event_type>.receiver.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when applicable.
event.<event_type>.receiver.ipStringOptionalOptionalOptional
Receiver IP address when applicable.
event.<event_type>.receiver.geocoordinatesStringOptionalOptionalOptional
Receiver geocoordinates.
event.<event_type>.refs.gatewayStringOptionalOptionalOptional
Reference to the payment gateway (intermediary).
event.<event_type>.refs.acquirerStringOptionalOptionalOptional
Reference to the acquirer (intermediary).
entities[]ArrayOptionalOptionalOptional
Optional entity objects included alongside the event.
entities[].<entity_type>ObjectOptionalOptionalOptional
Exactly one entity-type payload key on the array item (oneOf), e.g. card_account, card, merchant_account. The key names the entity kind; its object holds entity fields (id, timestamp, …).
entities[].<entity_type>.idStringOptionalOptionalOptional
Stable entity identifier.
entities[].<entity_type>.timestampDoubleOptionalOptionalOptional
UTC time at which this entity snapshot was observed / is valid, as a Unix timestamp (seconds; may be fractional). Defaults to the event timestamp.
entities[].<entity_type>.labelsObject[String, String]OptionalOptionalOptional
Optional flat map of client-defined string keys to string values. Keys have no Fraudio-defined schema. Nested objects, arrays, and non-string values are not allowed.
entities[].<entity_type>.refsObjectOptionalOptionalOptional
Optional nested references to other entities.
entities[].<entity_type>.refs.cardholdersArray[String]OptionalOptionalOptional
On card_account or card: ids of linked cardholder entities. Account-level sharing is M:N. On a plastic card, use one id for a single embossed name, or two for a dual-name plastic (not more than two).
event.<event_type>.sender.refs.cardholderStringOptionalOptionalOptional
Singular reference to the cardholder who initiated or is assessed for this event (not ownership of the plastic).
entities[].<entity_type>.parStringOptionalOptionalOptional
Payment Account Reference on a card_account (preferred stable account id).
entities[].<entity_type>.pan_fingerprintStringOptionalOptionalOptional
Non-reversible fingerprint of the PAN on a card_account when PAR is unavailable.
entities[].<entity_type>.card_sequence_numberStringOptionalOptionalOptional
EMV card sequence number on a card (distinguishes plastics under the same account).
entities[].<entity_type>.card_referenceStringOptionalOptionalOptional
Opaque processor-scoped vault or CMS id on card_account (when PAN/account-scoped) or card (when instance-scoped). Issuing and acquiring clients each send their own token namespace in this single field. Never a PAN or network token (DPAN).
entities[].<entity_type>.last_four_digitsStringOptionalOptionalOptional
Last 4 digits when sending full card entity.
entities[].<entity_type>.expiry_dateStringOptionalOptionalOptional
Expiry date when sending full card entity.
entities[].<entity_type>.registered_onDoubleOptionalOptionalOptional
Registration timestamp for merchant when available.
entities[].<entity_type>.limitprofileStringOptionalOptionalOptional
Merchant limit profile when available.
entities[].<entity_type>.mccsArrayOptionalOptionalOptional
Registered / assigned MCC list on a merchant_account or sub_merchant entity. Do not send on merchant_business; use event.card_network_transaction.mcc or event.wallet_payment.mcc for the as-processed code on a payment.
entities[].<entity_type>.midStringOptionalOptionalOptional
Processor- or acquirer-assigned Merchant ID on a merchant_account entity.
entities[].<entity_type>.terminal_typeStringOptionalOptionalOptional
Cardholder-Activated Terminal (CAT) type on an acceptor entity (e.g. cat1, cat2, cat6, cat9).
entities[].<entity_type>.binStringOptionalOptionalOptional
BIN for issuer/acquirer entities when available.
entities[].<entity_type>.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": {
    "id": "a12c34def",
    "timestamp": 1770000000.123,
    "card_network_transaction": {"sender": { "refs": { "card": "card-ferdinand-01" } },"receiver": { "refs": { "merchant_account": "hotel-bristol-front" } }, "mti": "0100", "transaction_type": "purchase", "currency": "EUR", "currency_unit": "major", "amount": 42.1 }
  },
  "entities": [
    { "card_account": { "id": "ca-ferdinand", "timestamp": 1770000000.123, "par": "5001ABCDEFGHIJKLMNOPQRSTUV", "pan_fingerprint": "fp-9f3a2c1b8e7d6a5", "refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] } } }, { "card": { "id": "card-ferdinand-01", "timestamp": 1770000000.123, "card_sequence_number": "01", "card_reference": "iss-card-77881234", "bin": "450901", "last_four_digits": "9876", "expiry_date": "1127", "card_type": "credit", "refs": { "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" } } },
    { "cardholder": { "id": "c4rdh0ld", "timestamp": 1770000000.123, "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
    { "merchant_business": { "id": "hotel-bristol", "timestamp": 1770000000.123, "name": "Hotel Bristol B.V.", "country_code": "NLD" } },
    { "merchant_account": { "id": "hotel-bristol-front", "timestamp": 1770000000.123, "mid": "8842101000123", "mccs": ["7011"], "refs": { "merchant_business": "hotel-bristol" } } },
    { "issuer": { "id": "b-450901", "timestamp": 1770000000.123, "bin": "450901", "name": "Example Issuer", "country_code": "PRT" } }
  ]
}'