Skip to main content
Version: 2.0

Financial Events Enrichment

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

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

Typical request​

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

The request body contains a top-level events array and a top-level entities array. Events and entities are correlated through refs; there is no per-event entity nesting. Events and entities may include an optional labels object: a flat map of client-defined string keys to string values, with no Fraudio-defined key schema. On entities, labels is a sibling of the entity-type key (not nested inside it) and is available for every entity type.

Request body
{
"events": [
{
"id": "auth-resp-001",
"timestamp": 1770004000.123,
"lifecycle_id": "123456789012",
"card_network_transaction": {
"mti": "0110",
"rrn": "123456789012",
"dynamic_descriptor": "HOTELBRISTOL*LONDON",
"transaction_type": "purchase",
"response_code": "00",
"eci": "02",
"avs_result": "Y",
"cvv_result": "M",
"cavv_result": "2"
}
}
],
"entities": []
}

Typical response​

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

Response body
{
"status": "ok"
}

Event types​

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

card_network_transaction (authorization response)​

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

Link this event to the original 0100 using lifecycle_id. events[].card_network_transaction.sender, events[].card_network_transaction.receiver, and events[].card_network_transaction.amount, events[].card_network_transaction.currency, events[].card_network_transaction.currency_unit are optional if they were already sent on the original 0100 event.

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

Post-auth integrated clients

If your fraud checks are performed post-authorization, send the 0110 to the Financial Events Screening endpoint instead for scoring. In that case, include 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 since there is no prior event to inherit them from.

{
"events": [
{
"id": "auth-resp-001",
"timestamp": 1770004000.123,
"lifecycle_id": "123456789012",
"card_network_transaction": {
"mti": "0110",
"rrn": "123456789012",
"dynamic_descriptor": "HOTELBRISTOL*LONDON",
"transaction_type": "purchase",
"response_code": "00",
"eci": "02",
"avs_result": "Y",
"cvv_result": "M",
"cavv_result": "2"
}
}
],
"entities": []
}

card_network_transaction (reversal advice)​

Use this for transaction reversals.

{
"events": [
{
"id": "reversal-evt-001",
"timestamp": 1770004500,
"lifecycle_id": "123456789012",
"card_network_transaction": {
"sender": { "refs": { "acquirer": "b-7610201" } },
"receiver": { "refs": { "issuer": "b-450901" } },
"mti": "0420",
"transaction_type": "purchase",
"currency": "EUR",
"currency_unit": "major",
"amount": 42.1,
"amount_in_base_currency": 42.1
}
}
],
"entities": [
{ "id": "b-7610201", "timestamp": 1770004500, "acquirer": { "name": "Example Acquirer", "country_code": "PRT" } },
{ "id": "450901", "timestamp": 1770000000.123, "bin": { "brand": "visa", "card_type": "credit", "country_code": "PRT" } },
{ "id": "b-450901", "timestamp": 1770004500, "issuer": { "name": "Example Issuer", "country_code": "PRT" } }
]
}

dispute (pre-arbitration)​

Dispute events are typically less complete than transaction events but follow the same event/entities structure. Link them to the original transaction using lifecycle_id. Each stage is a new event with its own event.id and dispute_stage. See Transaction lifecycle.

Dispute events can represent different sources:

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

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

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

  • transactionid → event.lifecycle_id
  • merchant → event.dispute.receiver.refs.merchant_account (prefer the account; link the business via merchant_account.refs.merchant_business)
  • chargebackreason → event.dispute.dispute_reason_code
  • reporttype (e.g. 1st chargeback, pre-arbitration) → event.dispute.dispute_stage
  • statusid → event.dispute.dispute_status
  • fraudimportdate → event.dispute.import_timestamp (timestamp when the dispute/notification was imported)
  • fraudreason → event.dispute.fraud_reason
{
"events": [
{
"id": "dsp-evt-001",
"timestamp": 1770100000,
"lifecycle_id": "123456789012",
"dispute": {
"sender": { "refs": { "issuer": "b-450901" } },
"receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },
"refs": { "acquirer": "b-7610201" },
"dispute_type": "chargeback",
"dispute_stage": "pre_arbitration",
"dispute_status": "pending",
"dispute_reason_code": "10.4",
"fraud_reason": "Suspicious account number used",
"import_timestamp": 1602868410.143105,
"currency": "EUR",
"currency_unit": "major",
"amount": 42.1,
"amount_in_base_currency": 42.1
}
}
],
"entities": [
{
"id": "hotel-bristol",
"timestamp": 1770100000,
"merchant_business": {
"name": "Hotel Bristol B.V.",
"url": "www.hotelbristol.example",
"country_code": "NLD"
}
},
{
"id": "hotel-bristol-front",
"timestamp": 1770100000,
"merchant_account": {
"mid": "8842101000123",
"mccs": ["7011"],
"refs": { "merchant_business": "hotel-bristol" }
}
},
{ "id": "450901", "timestamp": 1770000000.123, "bin": { "brand": "visa", "card_type": "credit", "country_code": "PRT" } },
{ "id": "b-450901", "timestamp": 1770100000, "issuer": { "name": "Example Issuer", "country_code": "PRT" } },
{ "id": "b-7610201", "timestamp": 1770100000, "acquirer": { "name": "Example Acquirer", "country_code": "PRT" } }
]
}

wallet_withdrawal (wallet to bank)​

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

{
"events": [
{
"id": "ww-001",
"timestamp": 1770005000,
"wallet_withdrawal": {
"sender": {
"refs": {
"wallet": "wallet-893067473928",
"merchant_account": "hotel-bristol-front"
}
},
"receiver": {
"refs": {
"bank_account": "NL51INGB40123456789876"
}
},
"currency": "EUR",
"currency_unit": "major",
"amount": 1500.00,
"amount_in_base_currency": 1500.00
}
}
],
"entities": [
{
"id": "wallet-893067473928",
"timestamp": 1770005000,
"wallet": {
"refs": { "merchant_business": "hotel-bristol" }
}
},
{
"id": "hotel-bristol",
"timestamp": 1770005000,
"merchant_business": {
"name": "Hotel Bristol B.V.",
"url": "www.hotelbristol.example",
"country_code": "NLD"
}
},
{
"id": "hotel-bristol-front",
"timestamp": 1770005000,
"merchant_account": {
"mid": "8842101000123",
"mccs": ["7011"],
"refs": { "merchant_business": "hotel-bristol" }
}
},
{
"id": "NL51INGB40123456789876",
"timestamp": 1770005000,
"bank_account": {
"bank_account_number": "NL51INGB40123456789876",
"name": "ING Bank N.V."
}
}
]
}

wallet_deposit (bank to wallet)​

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

{
"events": [
{
"id": "wd-001",
"timestamp": 1770005100,
"wallet_deposit": {
"sender": {
"refs": {
"bank_account": "NL51INGB40123456789876"
}
},
"receiver": {
"refs": {
"wallet": "wallet-893067473928",
"merchant_account": "hotel-bristol-front"
}
},
"currency": "EUR",
"currency_unit": "major",
"amount": 500.00,
"amount_in_base_currency": 500.00
}
}
],
"entities": [
{
"id": "NL51INGB40123456789876",
"timestamp": 1770005100,
"bank_account": {
"bank_account_number": "NL51INGB40123456789876",
"name": "ING Bank N.V."
}
},
{
"id": "wallet-893067473928",
"timestamp": 1770005100,
"wallet": {
"refs": { "merchant_business": "hotel-bristol" }
}
},
{
"id": "hotel-bristol",
"timestamp": 1770005100,
"merchant_business": {
"name": "Hotel Bristol B.V.",
"url": "www.hotelbristol.example",
"country_code": "NLD"
}
},
{
"id": "hotel-bristol-front",
"timestamp": 1770005100,
"merchant_account": {
"mid": "8842101000123",
"mccs": ["7011"],
"refs": { "merchant_business": "hotel-bristol" }
}
}
]
}

card_network_transaction (payout — OCT)​

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

{
"events": [
{
"id": "po-001",
"timestamp": 1770005200,
"lifecycle_id": "123456789012",
"card_network_transaction": {
"sender": {
"refs": {
"wallet": "wallet-893067473928",
"merchant_account": "hotel-bristol-front"
}
},
"receiver": {
"refs": {
"card": "card-ferdinand-01"
}
},
"mti": "0200",
"rrn": "123456789012",
"dynamic_descriptor": "HOTELBRISTOL*LONDON",
"transaction_type": "oct",
"currency": "EUR",
"currency_unit": "major",
"amount": 250.00,
"amount_in_base_currency": 250.00
}
}
],
"entities": [
{
"id": "wallet-893067473928",
"timestamp": 1770005200,
"wallet": {
"refs": { "merchant_business": "hotel-bristol" }
}
},
{
"id": "hotel-bristol",
"timestamp": 1770005200,
"merchant_business": {
"name": "Hotel Bristol B.V.",
"url": "www.hotelbristol.example",
"country_code": "NLD"
}
},
{
"id": "hotel-bristol-front",
"timestamp": 1770005200,
"merchant_account": {
"mid": "8842101000123",
"mccs": ["7011"],
"refs": { "merchant_business": "hotel-bristol" }
}
},
{
"id": "ca-ferdinand",
"timestamp": 1770005200,
"card_account": {
"par": "5001ABCDEFGHIJKLMNOPQRSTUV",
"pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
"refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
}
},
{
"id": "card-ferdinand-01",
"timestamp": 1770005200,
"card": {
"card_sequence_number": "01",
"card_reference": "iss-card-77881234",
"last_four_digits": "9876",
"expiry_date": "1127",
"activated_at": 1767225600,
"refs": { "bin": "450901", "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
}
},
{ "id": "450901", "timestamp": 1770000000.123, "bin": { "brand": "visa", "card_type": "credit", "country_code": "PRT" } },
{ "id": "b-450901", "timestamp": 1770005200, "issuer": { "name": "Example Issuer", "country_code": "PRT" } },
{ "id": "c4rdh0ld", "timestamp": 1770005200, "cardholder": { "name": "Ferdinand Solara", "email": "f.solara@example.com" } }
]
}

bank_transfer (bank account to bank account)​

Use this for account-to-account fund movements that do not need a synchronous fraud score, or to enrich a transfer that was already scored.

The payload shape matches Financial Events Screening — bank_transfer: rail, tenant_role, payment_reference, status / status_reason / status_reason_code, bank_account.refs.accountholders → accountholder, optional sender.refs.author. tenant_role is sender when your tenant is the sender, receiver when your tenant is the receiving side, and on_us when both the sender and the receiver belong to your tenant. Link related messages in the same payment lifecycle with lifecycle_id.

Status updates after screening. If you already scored the initiation (often with status: "pending"), send a follow-up enrichment with the later status. Include lifecycle_id so Fraudio can join it to the original event. The example is the rejection of the Screening initiation that uses the same lifecycle_id. You can omit sender, receiver, amount, currency, currency_unit, rail, tenant_role, and payment_reference when those were already sent on the scored event. Fields typically available only later:

  • status
    • accepted: the transfer is authorised and the funds are reserved.
    • completed: the transfer settled and the funds are deducted.
    • rejected: the transfer is refused, before acceptance or by the counterparty.
    • returned: after settlement, the counterparty sends the funds back.
  • status_reason
  • status_reason_code
{
"events": [
{
"id": "bt-outcome-001",
"timestamp": 1758186000,
"lifecycle_id": "20260918123045001234",
"bank_transfer": {
"status": "rejected",
"status_reason": "account_closed",
"status_reason_code": "AC04"
}
}
],
"entities": []
}

If enrichment is the only call (no prior screening), send the same full bank_transfer payload as on Screening. Entity field detail lives on the Screening entity pages.

wallet_transfer (wallet to wallet)​

Use this for wallet-to-wallet fund movements that do not need a synchronous fraud score, or to enrich a transfer that was already scored.

The payload shape matches Financial Events Screening — wallet_transfer, including existing fields such as sister_transaction_id when used. Also supported: payment_reference, status / status_reason / status_reason_code, wallet.refs.accountholders → accountholder (or refs.merchant_business for merchant wallets), optional sender.refs.author. Link related messages in the same payment lifecycle with lifecycle_id.

Status updates after screening. If you already scored the initiation (often with status: "pending"), send a follow-up enrichment with the later status. Include lifecycle_id so Fraudio can join it to the original event. You can omit sender, receiver, amount, currency, currency_unit, and payment_reference when those were already sent on the scored event. Fields typically available only later:

  • status
    • accepted: the transfer is authorised and the funds are reserved.
    • completed: the transfer settled and the funds are deducted.
    • rejected: the transfer is refused, before acceptance or by the counterparty.
    • returned: after settlement, the counterparty sends the funds back.
  • status_reason
  • status_reason_code
{
"events": [
{
"id": "wt-outcome-001",
"timestamp": 1770004600,
"lifecycle_id": "WT-20260918-001234",
"wallet_transfer": {
"status": "completed"
}
}
],
"entities": []
}

If enrichment is the only call (no prior screening), send the same full wallet_transfer payload as on Screening. Entity field detail lives on the Screening entity pages.

wallet_payment (wallet to merchant)​

Use this for wallet-to-merchant payments that do not need a synchronous fraud score, or to enrich a payment that was already scored.

The payload shape matches Financial Events Screening — wallet_payment, including existing fields such as mcc. Also supported: payment_reference, status / status_reason / status_reason_code, wallet.refs.accountholders → accountholder, optional sender.refs.author. Link related messages in the same payment lifecycle with lifecycle_id.

Status updates after screening. If you already scored the initiation (often with status: "pending"), send a follow-up enrichment with the later status. Include lifecycle_id so Fraudio can join it to the original event. You can omit sender, receiver, amount, currency, currency_unit, mcc, and payment_reference when those were already sent on the scored event. Fields typically available only later:

  • status
    • accepted: the payment is authorised and the funds are reserved.
    • completed: the payment settled and the funds are deducted.
    • rejected: the payment is refused, before acceptance or by the counterparty.
    • returned: after settlement, the counterparty sends the funds back.
  • status_reason
  • status_reason_code
{
"events": [
{
"id": "wp-outcome-001",
"timestamp": 1770004700,
"lifecycle_id": "WP-20260918-00421",
"wallet_payment": {
"status": "completed"
}
}
],
"entities": []
}

If enrichment is the only call (no prior screening), send the same full wallet_payment payload as on Screening. Entity field detail lives on the Screening entity pages.

Other events​

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

Entity types​

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

Entities-only (pre-registration)​

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

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

Request body: entities only
{
"events": [],
"entities": [
{
"id": "ca-ferdinand",
"timestamp": 1770000000,
"card_account": {
"par": "5001ABCDEFGHIJKLMNOPQRSTUV",
"pan_fingerprint": "fp-9f3a2c1b8e7d6a5",
"refs": { "issuer": "b-450901", "cardholders": ["c4rdh0ld"] }
}
},
{
"id": "card-ferdinand-01",
"timestamp": 1770000000,
"card": {
"card_sequence_number": "01",
"card_reference": "iss-card-77881234",
"last_four_digits": "9876",
"expiry_date": "1127",
"activated_at": 1767225600,
"refs": { "bin": "450901", "card_account": "ca-ferdinand", "cardholders": ["c4rdh0ld"], "issuer": "b-450901" }
}
},
{ "id": "c4rdh0ld", "timestamp": 1770000000, "cardholder": { "name": "Ferdinand Solara", "email": "f.solara@example.com" } },
{
"id": "hotel-bristol",
"timestamp": 1770000000,
"merchant_business": {
"name": "Hotel Bristol B.V.",
"url": "www.hotelbristol.example",
"country_code": "NLD"
}
},
{
"id": "hotel-bristol-front",
"timestamp": 1770000000,
"merchant_account": {
"mid": "8842101000123",
"mccs": ["7011"],
"refs": { "merchant_business": "hotel-bristol" }
}
},
{ "id": "450901", "timestamp": 1770000000.123, "bin": { "brand": "visa", "card_type": "credit", "country_code": "PRT" } },
{ "id": "b-450901", "timestamp": 1770000000, "issuer": { "name": "Example Issuer", "country_code": "PRT" } }
]
}

Request parameters: Field Reference Table​

FieldData TypePayment Fraud (Issuer)Payment Fraud (Acquirer / Processor)Merchant Fraud / AMLDescription
events[].<event_type>ObjectRequiredRequiredRequired
Exactly one event-type payload key on each event (oneOf), e.g. card_network_transaction, wallet_payment, wallet_transfer, bank_transfer, dispute. The key names the event kind; its object holds type-specific fields.
events[].idStringRequiredRequiredRequired
Unique identifier of the event.
events[].timestampDoubleRequiredRequiredRequired
UTC Unix timestamp (seconds; may be fractional) of the event.
events[].lifecycle_idStringOptionalOptionalOptional
Client lifecycle identifier shared across chained events in the same payment lifecycle. When omitted, it defaults to the event id. Repeat the same value on every related message, including follow-up card-network messages, transfer status updates, and dispute events that refer back to the payment. For the card-network Retrieval Reference Number (ISO 8583 DE037), use card_network_transaction.rrn.
events[].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.
events[].card_network_transaction.mtiStringOptionalOptionalOptional
ISO 8583 MTI when applicable.
events[].card_network_transaction.rrnStringOptionalOptionalOptional
Retrieval Reference Number (ISO 8583 DE037) for this card-network message when available. Distinct from event-level lifecycle_id, which links related events across a payment lifecycle.
events[].card_network_transaction.transaction_typeStringOptionalOptionalOptional
ISO 8583 DE003 transaction type when applicable.
events[].card_network_transaction.currencyStringOptionalOptionalOptional
ISO 4217 alphabetic currency code (3 letters, e.g. EUR).
events[].card_network_transaction.currency_unitStringOptionalOptionalOptional
major or minor.
events[].card_network_transaction.amountDoubleOptionalOptionalOptional
Amount in the currency and unit provided.
events[].card_network_transaction.amount_in_base_currencyDoubleOptionalOptionalOptional
Amount converted to the client's base currency (same unit as currency_unit when that field applies). Optional when the event currency already is the base currency, or when FX conversion is unavailable.
events[].card_network_transaction.successStringOptionalOptionalOptional
Overall result of the transaction. Accepted values: true (fully completed without technical or non-technical failures); false (any part failed or did not meet criteria); none (outcome uncertain or not yet known). Use true only for fully successful transactions.
events[].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.
events[].card_network_transaction.eciStringOptionalOptionalOptional
Electronic Commerce Indicator from 3-D Secure or equivalent authentication.
events[].card_network_transaction.avs_resultStringOptionalOptionalOptional
Address Verification System (AVS) result code.
events[].card_network_transaction.cvv_resultStringOptionalOptionalOptional
Card verification value (CVV/CVC) check result.
events[].card_network_transaction.cavv_resultStringOptionalOptionalOptional
Cardholder Authentication Verification Value (CAVV) or equivalent authentication result.
events[].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). Same semantics as Screening.
events[].wallet_transfer.statusStringOptionalOptionalOptional
Transfer status.
- pending: the transfer request is created.
- accepted: the transfer is authorised and the funds are reserved.
- completed: the transfer settled and the funds are deducted.
- rejected: the transfer is refused, before acceptance or by the counterparty. Put the cause in status_reason.
- returned: after settlement, the counterparty sends the funds back.
On a status-only enrichment, send the later status here.
events[].wallet_transfer.status_reasonStringOptionalOptionalOptional
Normalized reason for the status when applicable (e.g. insufficient_funds).
events[].wallet_transfer.status_reason_codeStringOptionalOptionalOptional
Scheme or client reason code when applicable.
events[].wallet_transfer.payment_referenceStringOptionalOptionalOptional
Free-text payment reason / narrative. Omit on a status-only enrichment when already sent on the scored event.
events[].wallet_transfer.sender.refs.authorStringOptionalOptionalOptional
Reference to an author entity when someone other than a wallet holder created the payment. Same shape as Screening.
events[].bank_transfer.currencyStringOptionalOptionalOptional
ISO 4217 alphabetic currency code (3 letters, e.g. EUR) for a bank_transfer. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.currency_unitStringOptionalOptionalOptional
major or minor. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.amountDoubleOptionalOptionalOptional
Transfer amount. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.amount_in_base_currencyDoubleOptionalOptionalOptional
Amount converted to the client's base currency (same unit as currency_unit when that field applies). Optional when the event currency already is the base currency, or when FX conversion is unavailable. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.railStringOptionalOptionalOptional
Clearing path for the transfer, e.g. sepa, sepa_inst, faster_payments, swift. Extensible string. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.tenant_roleStringOptionalOptionalOptional
Role of your tenant in the transfer. sender when your tenant is the sender, receiver when your tenant is the receiving side, on_us when both the sender and the receiver belong to your tenant. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.statusStringOptionalOptionalOptional
Transfer status.
- pending: the transfer request is created.
- accepted: the transfer is authorised and the funds are reserved.
- completed: the transfer settled and the funds are deducted.
- rejected: the transfer is refused, before acceptance or by the counterparty. Put the cause in status_reason.
- returned: after settlement, the counterparty sends the funds back.
Typical enrichment-only field when the initiation was scored earlier.
events[].bank_transfer.status_reasonStringOptionalOptionalOptional
Normalized reason for a non-success status, e.g. account_closed. Typical enrichment-only field.
events[].bank_transfer.status_reason_codeStringOptionalOptionalOptional
Scheme or client reason code when applicable (e.g. ISO 20022 AC04). Typical enrichment-only field.
events[].bank_transfer.payment_referenceStringOptionalOptionalOptional
Free-text payment reason / narrative supplied by the payer. Omit on a status-only enrichment when already sent on the scored event.
events[].bank_transfer.sender.refs.authorStringOptionalOptionalOptional
Reference to an author entity on the debit / sender side when someone other than an account holder created the payment. Omit when the holder created the payment, or on a status-only enrichment.
events[].wallet_payment.currencyStringOptionalOptionalOptional
ISO 4217 alphabetic currency code (3 letters, e.g. EUR).
events[].wallet_payment.currency_unitStringOptionalOptionalOptional
major or minor.
events[].wallet_payment.amountDoubleOptionalOptionalOptional
Amount in the currency and unit provided.
events[].wallet_payment.amount_in_base_currencyDoubleOptionalOptionalOptional
Amount converted to the client's base currency (same unit as currency_unit when that field applies). Optional when the event currency already is the base currency, or when FX conversion is unavailable.
events[].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.
events[].wallet_payment.statusStringOptionalOptionalOptional
Payment status.
- pending: the payment request is created.
- accepted: the payment is authorised and the funds are reserved.
- completed: the payment settled and the funds are deducted.
- rejected: the payment is refused, before acceptance or by the counterparty. Put the cause in status_reason.
- returned: after settlement, the counterparty sends the funds back.
On a status-only enrichment, send the later status here.
events[].wallet_payment.status_reasonStringOptionalOptionalOptional
Normalized reason for the status when applicable (e.g. insufficient_funds).
events[].wallet_payment.status_reason_codeStringOptionalOptionalOptional
Scheme or client reason code when applicable.
events[].wallet_payment.payment_referenceStringOptionalOptionalOptional
Free-text payment reason / narrative. Omit on a status-only enrichment when already sent on the scored event.
events[].wallet_payment.sender.refs.authorStringOptionalOptionalOptional
Reference to an author entity when someone other than a wallet holder created the payment. Same shape as Screening.
events[].card_network_transaction.pos_entry_modeStringOptionalOptionalOptional
ISO POS entry mode when applicable. When channel is omitted, Fraudio derives it from this field and pos_condition_code: pos_condition_code 08/09 map to moto; pos_entry_mode 010/10/011/11/012/12 map to ecom; other entry modes map to pos; missing or 00 entry mode is treated as ecom.
events[].card_network_transaction.pos_condition_codeStringOptionalOptionalOptional
ISO POS condition code when applicable. Codes 08/09 map to channel moto (see pos_entry_mode for the full channel derivation).
events[].card_network_transaction.channelStringOptionalOptionalOptional
Channel of the card payment. Accepted values: ecom (ecommerce), pos (in person), moto (mail or telephone order), atm (ATM).
events[].card_network_transaction.channel_subtypeStringOptionalOptionalOptional
Channel subtype when known. Accepted values: paymentlink (PayByLink), telephoneorder, mailorder.
events[].card_network_transaction.recurringStringOptionalOptionalOptional
Whether the payment is recurring. Accepted values: true, false, none (unknown).
events[].card_network_transaction.recurring_lifecycle_idStringOptionalOptionalOptional
lifecycle_id of the first payment in the recurring series. Repeat it on every cycle. When it equals this event's lifecycle_id, this is the initial recurring transaction.
events[].card_network_transaction.dynamic_descriptorStringOptionalOptionalOptional
Dynamic descriptor returned by the processor; text that appears on the cardholder bank statement.
events[].card_network_transaction.merchant_advice_codeStringOptionalOptionalOptional
Merchant advice code from the payment processor: reason for a decline and how the merchant may retry.
events[].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.
events[].<event_type>.sender.refs.cardStringOptionalOptionalOptional
Reference to a card entity when applicable.
events[].<event_type>.sender.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when the wallet is the sender (e.g. wallet payment, wallet withdrawal, payout events).
events[].<event_type>.sender.refs.merchant_businessStringOptionalOptionalOptional
Reference to a merchant_business entity when the merchant is the initiating party (e.g., wallet withdrawal, payout, chargeback lifecycle). Should be included alongside wallet reference for wallet-based events.
events[].<event_type>.sender.refs.bank_accountStringn.a.n.a.Optional
Reference to a bank_account entity when the bank account is the sender (e.g. wallet deposit, or a wallet_payment funded from a linked bank account).
events[].<event_type>.sender.ipStringOptionalOptionalOptional
Sender IP address when applicable.
events[].<event_type>.sender.user_agentStringOptionalOptionalOptional
HTTP User-Agent string of the sender when the interaction is browser- or app-based.
events[].<event_type>.sender.street_addressStringOptionalOptionalOptional
Street address associated with the sender location when known.
events[].<event_type>.sender.cityStringOptionalOptionalOptional
City associated with the sender location when known.
events[].<event_type>.sender.state_codeStringOptionalOptionalOptional
State, province, or region code associated with the sender location when known.
events[].<event_type>.sender.postal_codeStringOptionalOptionalOptional
Postal / ZIP code associated with the sender location when known.
events[].<event_type>.sender.country_codeStringOptionalOptionalOptional
Country of the sender on the transaction payload (ISO 3166-1 alpha-3, e.g. NLD). Applies to every event type that has a sender, including card_network_transaction, bank_transfer, wallet_transfer, and wallet_payment.
events[].<event_type>.receiver.refs.walletStringOptionalOptionalOptional
Reference to a wallet entity when the wallet is the receiver (e.g., wallet deposit events).
events[].<event_type>.receiver.refs.merchant_businessStringOptionalOptionalOptional
Reference to a merchant_business entity when the merchant is the receiving party. Should be included alongside wallet reference for wallet deposit events.
events[].<event_type>.receiver.refs.bank_accountStringn.a.n.a.Optional
Reference to a bank_account entity when the bank account is the receiver (e.g., wallet withdrawal events).
events[].<event_type>.receiver.refs.acceptorStringOptionalOptionalOptional
Reference to an acceptor entity when applicable.
events[].<event_type>.refs.gatewayStringOptionalOptionalOptional
Reference to the payment gateway (intermediary).
events[].<event_type>.refs.acquirerStringOptionalOptionalOptional
Reference to the acquirer (intermediary).
events[].<event_type>.refs.processorStringOptionalOptionalOptional
Reference to a processor entity (payment processor / PSP intermediary appointed to handle transactions for merchant acquiring). Distinct from acquirer and gateway.
events[].<event_type>.receiver.ipStringOptionalOptionalOptional
Receiver IP address when applicable.
events[].<event_type>.receiver.user_agentStringOptionalOptionalOptional
HTTP User-Agent string of the receiver when the interaction is browser- or app-based.
events[].<event_type>.receiver.street_addressStringOptionalOptionalOptional
Street address associated with the receiver location when known.
events[].<event_type>.receiver.cityStringOptionalOptionalOptional
City associated with the receiver location when known.
events[].<event_type>.receiver.state_codeStringOptionalOptionalOptional
State, province, or region code associated with the receiver location when known.
events[].<event_type>.receiver.postal_codeStringOptionalOptionalOptional
Postal / ZIP code associated with the receiver location when known.
events[].<event_type>.receiver.country_codeStringOptionalOptionalOptional
Country of the receiver on the transaction payload (ISO 3166-1 alpha-3, e.g. NLD). Applies to every event type that has a receiver, including card_network_transaction, bank_transfer, wallet_transfer, and wallet_payment.
events[].<event_type>.receiver.geocoordinatesStringOptionalOptionalOptional
Receiver geocoordinates.
entities[]ArrayOptionalOptionalOptional
Top-level array of entity objects. Entities are correlated to events through refs, not by nesting.
entities[].<entity_type>ObjectOptionalOptionalOptional
Exactly one entity-type payload key on the array item (oneOf), e.g. card_account, card, shopper, shopper_device, bin, merchant_account, sub_merchant, processor. The key names the entity kind; its object holds entity fields (id, timestamp, …).
entities[].<entity_type>.idStringOptionalOptionalOptional
Stable entity identifier.
entities[].<entity_type>.timestampDoubleRequiredRequiredRequired
UTC Unix timestamp (seconds; may be fractional) at which this entity snapshot was observed / is valid.
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>.nameStringOptionalOptionalOptional
Entity name when available.
entities[].<entity_type>.country_codeStringOptionalOptionalOptional
Country code when available (ISO 3166-1 alpha-3, e.g. NLD). Applies to location-bearing entities including issuer, acquirer, gateway, processor, acceptor, merchant_business, merchant_account, sub_merchant, and institution.
entities[].<entity_type>.limitprofileStringOptionalOptionalOptional
Merchant limit profile (can be partial update; null to clear).
entities[].<entity_type>.mccsArrayOptionalOptionalOptional
Registered / assigned MCC list on a merchant_account or sub_merchant entity. On a sponsored seller this is entities[].sub_merchant.mccs. 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[].sub_merchantObjectOptionalOptionalOptional
Sponsored seller that accepts payments under a Payment Facilitator. Uses the standard entity id and timestamp. Reference it from the event with receiver.refs.sub_merchant.
entities[].sub_merchant.nameStringOptionalOptionalOptional
Name of the sponsored seller.
entities[].sub_merchant.country_codeStringOptionalOptionalOptional
Country of the sponsored seller (ISO 3166-1 alpha-3, e.g. NLD).
entities[].sub_merchant.mccsArrayOptionalOptionalOptional
Registered / assigned MCC list for this sponsored seller. The MCC used on a specific payment stays on the event.
entities[].sub_merchant.refs.payfacStringOptionalOptionalOptional
Id of the Payment Facilitator (payfac) this seller processes under.
entities[].sub_merchant.refs.merchant_businessStringOptionalOptionalOptional
Id of the merchant_business for this sponsored seller, when you send one.
entities[].merchant_account.midStringOptionalOptionalOptional
Processor- or acquirer-assigned Merchant ID on a merchant_account entity.
entities[].acceptor.terminal_typeStringOptionalOptionalOptional
Cardholder-Activated Terminal (CAT) type on an acceptor entity (e.g. cat1, cat2, cat6, cat9).
entities[].acceptor.country_codeStringOptionalOptionalOptional
Country where the acceptor (terminal / ATM) is located (ISO 3166-1 alpha-3).
entities[].acceptor.street_addressStringOptionalOptionalOptional
Street address of the acceptor (terminal / ATM) when known.
entities[].acceptor.cityStringOptionalOptionalOptional
City where the acceptor (terminal / ATM) is located when known.
entities[].acceptor.state_codeStringOptionalOptionalOptional
State, province, or region code of the acceptor location when known.
entities[].acceptor.postal_codeStringOptionalOptionalOptional
Postal / ZIP code of the acceptor location when known.
entities[].card.activated_atDoubleOptionalOptionalOptional
UTC Unix timestamp (seconds; may be fractional) when this card instance was activated.
entities[].binObjectOptionalOptionalOptional
BIN (IIN) entity payload under the bin key. id is the BIN/IIN value. Link from card / card_account via refs.bin.
entities[].bin.brandStringOptionalOptionalOptional
Card scheme / brand for this BIN range (e.g. visa, mastercard).
entities[].bin.country_codeStringOptionalOptionalOptional
Country associated with the BIN range (ISO 3166-1 alpha-3).
entities[].bin.card_typeStringOptionalOptionalOptional
Card type for this BIN range (e.g. credit, debit).
entities[].shopper_deviceObjectOptionalOptionalOptional
Shopper device entity payload under the shopper_device key. Correlate only via entities[].shopper.refs.shopper_device.
entities[].shopper_device.osStringOptionalOptionalOptional
Operating system of the shopper device (e.g. ios, android, windows). Any OS string is accepted.
entities[].processorObjectOptionalOptionalOptional
Payment processor entity payload under the processor key. Correlate via events[]..refs.processor.
entities[].processor.nameStringOptionalOptionalOptional
Display name of the payment processor.
entities[].processor.country_codeStringOptionalOptionalOptional
Country of the payment processor (ISO 3166-1 alpha-3) when known.
entities[].gatewayObjectOptionalOptionalOptional
Payment gateway entity payload under the gateway key. Correlate via events[]..refs.gateway.
entities[].gateway.nameStringOptionalOptionalOptional
Display name of the payment gateway.
entities[].gateway.country_codeStringOptionalOptionalOptional
Country of the payment gateway (ISO 3166-1 alpha-3) when known.
entities[].acquirer.country_codeStringOptionalOptionalOptional
Country of the acquiring institution (ISO 3166-1 alpha-3) when known.
entities[].bank_accountStringn.a.n.a.Optional
Bank account entity payload under the bank_account key (IBAN or equivalent national account number fields).
entities[].bank_account.ibanStringn.a.n.a.Optional
Legacy IBAN field for bank_account entities. Prefer account_number with account_number_scheme: "iban" (see Screening bank_account).
entities[].<entity_type>.refs.merchant_businessStringn.a.n.a.Optional
Reference from another entity to a merchant_business (e.g. wallet or bank account belonging to the merchant).
entities[].<entity_type>.refs.binStringOptionalOptionalOptional
On card or card_account: id of the linked bin entity (Bank Identification Number / IIN range). Do not put BIN on acquirer or issuer; use the bin entity instead.
entities[].shopper.refs.shopper_deviceStringOptionalOptionalOptional
On a shopper entity: id of the linked shopper_device when known.
entities[].merchant_business.refs.ubosArrayOptionalOptionalOptional
Ids of linked ubo entities for this merchant business (one or many). Same shape as Screening.
entities[].merchant_business.urlStringOptionalOptionalOptional
Primary website URL of the merchant business when known.
entities[].wallet.statusStringOptionalOptionalOptional
Wallet relationship status when known (e.g. active). Same shape as Screening.
entities[].wallet.refs.accountholdersArray[String]OptionalOptionalOptional
Ids of accountholder entities who hold this wallet. Same shape as Screening.
entities[].wallet.refs.institutionStringOptionalOptionalOptional
Id of the institution (EMI / wallet operator) that books this wallet. Same shape as Screening.
entities[].wallet.refs.merchant_businessStringOptionalOptionalOptional
Id of the linked merchant_business for a merchant or corporate wallet. Same shape as Screening.

Response Parameters​

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

Code Samples​

curl -X POST 'https://api.fraudio.com/v2/financial-events/enrichment' \
-H 'Content-Type: application/json' \
-H "authorization: Bearer $ACCESS_TOKEN" \
--data-raw '{
"events": [
{
"id": "auth-resp-001",
"timestamp": 1770004000.123,
"lifecycle_id": "123456789012",
"card_network_transaction": {"sender": { "refs": { "card": "card-ferdinand-01" } },"receiver": { "refs": { "merchant_account": "hotel-bristol-front" } },"refs": { "acquirer": "b-7610201", "gateway": "molley", "processor": "proc-adyen" }, "mti": "0110", "rrn": "123456789012", "dynamic_descriptor": "HOTELBRISTOL*LONDON", "transaction_type": "purchase", "response_code": "00", "eci": "02", "avs_result": "Y", "cvv_result": "M", "cavv_result": "2" }
}
],
"entities": []
}'