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 acard_network_transactionevent with MTI0110(authorization response), linked to the original0100vialifecycle_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_businessfor the selling business, andmerchant_accountfor the acquiring account. The processor-assigned Merchant ID is themidproperty onmerchant_account(not a separate entity type). Registered MCCs go onmerchant_account/sub_merchant(mccs); the as-processed code for a payment goes on the event (card_network_transaction.mccorwallet_payment.mcc).sub_merchantis a PayFac-sponsored seller. Ultimate Beneficial Owners areuboentities linked frommerchant_business.refs.ubos(array). -
The former event type
transactionis renamed to thecard_network_transactionpayload key (card payment network messages such as authorization, capture, reversal, OCT). Type-specific fields live under thecard_network_transactionobject (includingtransaction_type). -
Events no longer use co-dependent
type+detailsfields. Each event carries exactly one event-type payload key (oneOf), e.g.card_network_transaction: { ... }ordispute: { ... }. 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_paymentpayload on Financial Events Screening. Sender typically refs awalletand/orbank_account; receiver typically refs a merchant entity. As-processed MCC goes onwallet_payment.mcc. The existing shape is unchanged; lifecycle fields also apply where useful (payment_reference,status/status_reason/status_reason_code, event-levellifecycle_id, optionalsender.refs.author). Enrichment documents a thin status update linked bylifecycle_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 asbank_transferwhere they apply (payment_reference,status/status_reason/status_reason_code, event-levellifecycle_id, optionalsender.refs.author). There is no clearingrail. Wallet holders may reuseaccountholderviawallet.refs.accountholders; merchant wallets keeprefs.merchant_business; the EMI / operator may userefs.institution. Enrichment documents a thin status update linked bylifecycle_id(see Screening wallet_transfer and Enrichment wallet_transfer). -
Card entities are split:
card_account(PAR /pan_fingerprint) andcard(issued plastic/virtual instance). Opaque processor vault or CMS ids use a singlecard_referenceon either entity (account-scoped vs instance-scoped). Legacycard_token/ issuer-acquirer split refs map tocard_reference. There is nodigitized_card; do not send network token (DPAN) values. Keepcard_grouponly as a degraded fallback. Ownership usesrefs.cardholderson those entity payloads (array): many holders on an account; one or two embossed names on a plastic. Event-type payloadsender.refs.cardholderstays singular for who acted. -
Each entity in
entitieshas exactly one entity-type key (oneOf). Prefer wrapper identity like events:{ "id": "...", "timestamp": ..., "card": { ... } }. Nestedid/timestampinside the type object remain accepted but are deprecated; the screening API dual-writes so both places stay populated.timestampis Unix seconds (may be fractional). An optionallabelsobject is a sibling of the type key, not nested inside it. -
Events and entities accept an optional
labelsobject: a flat map of client-defined string keys to string values, with no Fraudio-defined key schema. On events,labelsis a sibling of the event-type key; on entities,labelsis a sibling of the entity-type key. Every entity can carrylabelsregardless of type. Nested objects, arrays, and non-string values are not allowed. -
Entities no longer use a co-dependent top-level
typefield 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
disputepayload. -
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_transferpayload (rail,payment_reference,status/status_reason/status_reason_code, event-levellifecycle_id, optionalsender.refs.author). Holders areaccountholderentities linked frombank_account.refs.accountholders(array): natural-person KYC fields on the accountholder, orrefs.merchant_accountfor corporates.monthly_turnoveris onaccountholderfor natural persons and onmerchant_businessfor corporates / merchants. There is no separatepersonentity; author identifying fields live onauthor. Enrichment documents a thin status update linked bylifecycle_idafter 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
parenttransactionidorparent_event_idfield in v2. Chained events uselifecycle_id(see Transaction lifecycle). Card-network Retrieval Reference Number iscard_network_transaction.rrn(notlifecycle_id). Event types with anamountalso accept optionalamount_in_base_currency. Optional card-network coverage includessuccess,channel,channel_subtype,recurring,recurring_lifecycle_id,dynamic_descriptor, andmerchant_advice_code. BIN ranges are abinentity (brand,card_type,country_code) linked fromcard/card_accountviarefs.bin. Do not put a stringbinonissueroracquirer.gatewayandacceptorcarrycountry_codewhen known. Sender and receiver parties share the same location field set next toip: optionaluser_agent, thenstreet_address,city,state_code,postal_code,country_code, andgeocoordinates. Aprocessorentity (payment processor / PSP) is referenced viaevent.<event_type>.refs.processor, distinct fromacquirerandgateway. Shopper devices are ashopper_deviceentity linked from theshopperviashopper.refs.shopper_device(not underaccountholderor other person-like entities).
Version 1.1
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
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
eciandcavvresult, which the first endpoint doesn't accommodate.