Skip to main content
Version: 2.0

Changelog

Version 2.0​

Changes to API endpoints​

  • The Payment Fraud Score endpoint has been renamed to Financial Events Screening to better reflect its purpose of screening financial events rather than just providing a score. The score field in the response continues to represent the fraud risk assessment.
https://api.fraudio.com/v2/financial-events/screening
  • The Payment Events Enrichment endpoint has been renamed to Financial Events Enrichment.
https://api.fraudio.com/v2/financial-events/enrichment
  • Payment Post-Authorization Enrichment is no longer a separate endpoint in v2. Send post-authorization data (for example authorization response fields such as response_code, eci, avs_result, cvv_result, cavv_result) to Financial Events Enrichment as a card_network_transaction event with MTI 0110 (authorization response), linked to the original 0100 via lifecycle_id.

  • Merchant Account Information is no longer a separate endpoint in v2. Send merchant and other entity snapshots or updates via Financial Events Enrichment using an entities-only payload (events: []).

  • Merchant entities are renamed: use merchant_business for the selling business, and merchant_account for the acquiring account. The processor-assigned Merchant ID is the mid property on merchant_account (not a separate entity type). Registered MCCs go on merchant_account / sub_merchant (mccs); the as-processed code for a payment goes on the event (card_network_transaction.mcc or wallet_payment.mcc). sub_merchant is a PayFac-sponsored seller. Ultimate Beneficial Owners are ubo entities linked from merchant_business.refs.ubos (array).

  • The former event type transaction is renamed to the card_network_transaction payload key (card payment network messages such as authorization, capture, reversal, OCT). Type-specific fields live under the card_network_transaction object (including transaction_type).

  • Events no longer use co-dependent type + details fields. Each event carries exactly one event-type payload key (oneOf), e.g. card_network_transaction: { ... } or dispute: { ... }. Party and intermediary fields (sender, receiver, refs) live inside that payload object, not beside it on the event.

  • Paying a merchant from a wallet (not a card-network purchase) uses the wallet_payment payload on Financial Events Screening. Sender typically refs a wallet and/or bank_account; receiver typically refs a merchant entity. As-processed MCC goes on wallet_payment.mcc. The existing shape is unchanged; lifecycle fields also apply where useful (payment_reference, status / status_reason / status_reason_code, event-level lifecycle_id, optional sender.refs.author). Enrichment documents a thin status update linked by lifecycle_id (see Screening wallet_payment and Enrichment wallet_payment).

  • Wallet-to-wallet transfers (wallet_transfer) keep the existing Screening shape (sister_transaction_id, linked card/merchant parties, etc.) and add the same lifecycle fields as bank_transfer where they apply (payment_reference, status / status_reason / status_reason_code, event-level lifecycle_id, optional sender.refs.author). There is no clearing rail. Wallet holders may reuse accountholder via wallet.refs.accountholders; merchant wallets keep refs.merchant_business; the EMI / operator may use refs.institution. Enrichment documents a thin status update linked by lifecycle_id (see Screening wallet_transfer and Enrichment wallet_transfer).

  • Card entities are split: card_account (PAR / pan_fingerprint) and card (issued plastic/virtual instance). Opaque processor vault or CMS ids use a single card_reference on either entity (account-scoped vs instance-scoped). Legacy card_token / issuer-acquirer split refs map to card_reference. There is no digitized_card; do not send network token (DPAN) values. Keep card_group only as a degraded fallback. Ownership uses refs.cardholders on those entity payloads (array): many holders on an account; one or two embossed names on a plastic. Event-type payload sender.refs.cardholder stays singular for who acted.

  • Each entity in entities has exactly one entity-type key (oneOf). Prefer wrapper identity like events: { "id": "...", "timestamp": ..., "card": { ... } }. Nested id / timestamp inside the type object remain accepted but are deprecated; the screening API dual-writes so both places stay populated. timestamp is Unix seconds (may be fractional). An optional labels object is a sibling of the type key, not nested inside it.

  • Events and entities accept an optional labels object: a flat map of client-defined string keys to string values, with no Fraudio-defined key schema. On events, labels is a sibling of the event-type key; on entities, labels is a sibling of the entity-type key. Every entity can carry labels regardless of type. Nested objects, arrays, and non-string values are not allowed.

  • Entities no longer use a co-dependent top-level type field alongside attributes; the entity type is the object key.

  • The Merchant Evaluations endpoint has been removed in v2.

  • Dispute Events is no longer a separate endpoint in v2. Send disputes via Financial Events Enrichment with a dispute payload.

  • Account Bank Transfers is no longer a separate endpoint in v2. Send bank-to-bank transfers via Financial Events Screening or Financial Events Enrichment with a shared bank_transfer payload (rail, payment_reference, status / status_reason / status_reason_code, event-level lifecycle_id, optional sender.refs.author). Holders are accountholder entities linked from bank_account.refs.accountholders (array): natural-person KYC fields on the accountholder, or refs.merchant_account for corporates. monthly_turnover is on accountholder for natural persons and on merchant_business for corporates / merchants. There is no separate person entity; author identifying fields live on author. Enrichment documents a thin status update linked by lifecycle_id after a scored initiation; the full payload matches Screening (see Screening bank_transfer and Enrichment bank_transfer).

  • All other endpoints remain functionally similar but now use the v2 API path structure.

  • Currency and country codes are alphabetic ISO codes (3 letters): ISO 4217 for currency (e.g. EUR), ISO 3166-1 alpha-3 for country (e.g. NLD). Numeric codes are not used.

  • There is no parenttransactionid or parent_event_id field in v2. Chained events use lifecycle_id (see Transaction lifecycle). Card-network Retrieval Reference Number is card_network_transaction.rrn (not lifecycle_id). Event types with an amount also accept optional amount_in_base_currency. Optional card-network coverage includes success, channel, channel_subtype, recurring, recurring_lifecycle_id, dynamic_descriptor, and merchant_advice_code. BIN ranges are a bin entity (brand, card_type, country_code) linked from card / card_account via refs.bin. Do not put a string bin on issuer or acquirer. gateway and acceptor carry country_code when known. Sender and receiver parties share the same location field set next to ip: optional user_agent, then street_address, city, state_code, postal_code, country_code, and geocoordinates. A processor entity (payment processor / PSP) is referenced via event.<event_type>.refs.processor, distinct from acquirer and gateway. Shopper devices are a shopper_device entity linked from the shopper via shopper.refs.shopper_device (not under accountholder or other person-like entities).

Version 1.1​

Attention:

We've updated our API endpoints with new names and an additional route. However: All previous endpoints remain operational and supported, facilitating a seamless transition.

For help navigating the legacy endpoints, please refer to the Version 1.0 documentation or select version 1.0 directly from the top navigation dropdown.

Changes to API endpoints​

  • The "Fraud Score" endpoint has been renamed to Payment Fraud Score.
https://api.fraudio.com/v1/transactions/payment-fraud-score
  • The "Post-Authorization Backfill" endpoint has been renamed to Payment Post-Authorization Enrichment.
https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment
  • The endpoints "Fraud Notifications Enrichment" and "Chargebacks" are aliases for the new Dispute Events endpoint.
https://api.fraudio.com/v1/transactions/dispute-events
  • The Payment Events Enrichment endpoint is brand-new, and is designed as a supplement to the Payment Fraud Score endpoint, supporting additional data on both pre-auth and post-auth integrations.
https://api.fraudio.com/v1/transactions/payment-events-enrichment
tip

Note on the difference between Payment Events Enrichment and Payment Post-Authorization Enrichment:

  • Payment Events Enrichment supports both pre-auth and post-auth integrations in the context of real-time fraud detection.
  • Payment Post-Authorization Enrichment is all about enriching existing pre-auth transactions with new data, and is specialized for pre-auth setups, letting you backfill post-auth fields like eci and cavvresult, which the first endpoint doesn't accommodate.

Added Rules Management API Endpoints​

We've introduced new API endpoints for Rules Management. These endpoints allow customers to create, read, update, and archive transaction rules. These additions provide more granular control for fraud detection and transaction processing. Please refer to the updated documentation sections on Rules Management for detailed information on each endpoint and its usage.

New and modified fields​

  • The fields originalamount and iban have been renamed in all endpoints where they existed:
    • originalamount is now amount.
    • iban is now bankaccountnumber.
  • currencyunit now allows you to specify the currency unit (minor / major).