Batch Transfer
Batch transfers are applicable for doing a historical backfill or batch integration:
Historical Backfill: Upload historical transaction data to enrich Fraudio's context and improve model training and historical data analysis, leading to better-tuned fraud detection for your specific needs.
Batch Integration: While real-time API integration is always the preferred method and highly recommended, doing a batch integration provides an alternative way to send transaction data in bulk on a scheduled basis when API integration is not feasible. Please note that batch integration is not recommended as it may not provide the same level of accuracy and timeliness as real-time API integration.
Historical Backfill
Requirements
Consistency of Data Quality: Ensure that the quality of historical data is consistent with the transactions sent to the API. It is important to avoid differences in data distributions between historical and live data to ensure consistency and accuracy in our fraud detection models. This includes maintaining uniformity in data fields, data formats, field values, and metadata to prevent discrepancies that could affect fraud detection accuracy.
Data Volume: It is recommended to send at least 24 months of historical data. Ensure that there are no gaps in the data by verifying that transactions are present for each day to maintain completeness.
RFC-4180 CSV Format: Batch data must be provided in CSV format, conforming to the RFC-4180 specification. This ensures reliable parsing of all fields and prevents common data formatting issues.
Minimized Gap Between Historical Data and Live Data: To maintain the highest level of accuracy, it is recommended to minimize the time gap between sending historical data and starting to send live transactions to the fraud score endpoint. This ensures continuity and accuracy in our fraud scoring models, providing effective fraud protection.
tip
Before sending the entire historical dataset, it is advisable to first send a sample of the data. This allows for quick validation and reduces the risk of unnecessary delay.
Batch Data Schemas
The batch data that is sent should follow the same data schemas as the data that is sent to the API. For every transaction type that is sent to the API, we would like to receive the historical data in batch. So if you are sending inter account transfers, you should also send the historical data for inter account transfers. Therefore it is important to align with the data that is sent to the API.
Payment Events
To send payments in a historical batch, we recommend following the schema of the Payment Events Enrichment endpoint. For historical data batches, it is not necessary to split payment events by transactions that require scoring, post-backfill enrichment, or payment events enrichment. Hereby it is important that the data is sent with post-auth information for complete context.
If you prefer, you may also send transaction events separately, as suggested by the individual endpoints. This approach typically involves more effort and is generally not necessary for batch processing. In that case, you can follow the Fraud Score Endpoint and the Post Backfill Enrichment Endpoint.
View API Endpoint for Payment Events Enrichment
Toggle to view the batch schema for Payment events
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| transactionid | String | Critical & Required | Critical & Required | Critical & Required | The unique identifier of the transaction event. Every transaction event, so auth, capture, auth_capture, etc., has its own unique ID. |
| transactiontype | String | Critical & Required | Critical & Required | Critical & Required | The type of transaction event, for events that do not need scoring. Accepted values are: - auth: An authorization reserves funds on the customer's card without yet deducting them.- capture: A capture immediately deducts the authorized funds from the customer's card. A capture must always be linked to at least one authorization via the parenttransactionid.- auth_capture: A simultaneous combination of authorization and capture, used when there is no need to perform these operations separately.- refund: A refund transaction returns funds to the customer's payment method, typically reversing a previously completed capture.- void: A void transaction cancels a prior authorization, effectively discarding the reserved funds before they are captured.- incremental_auth: A transaction that increases the authorized amount on an existing authorization. This applies only to authorizations that have not yet been captured.- reversal: A reversal cancels a completed transaction and re-credits the customer's payment method. This typically occurs shortly after the transaction but before the funds have fully settled. |
| timestamp | Double | Critical & Required | Critical & Required | Critical & Required | The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted. |
| amount | Double | Critical & Required | Critical & Required | Critical & Required | The transaction amount in the unit specified by the currencyunit field and in the currency specified by the currency field. |
| currency | String | Critical & Required | Critical & Required | Critical & Required | The 3-digit ISO code for the currency used in the transaction. |
| currencyunit | String | Critical & Required | Critical & Required | Critical & Required | This field defines the unit of currency used in the 'amount' field. Accepts only major (e.g., 12.30) or minor (e.g., 1230) unit values. This choice should align with the unit used in the 'amount' field. |
| channel | String | Critical & Required | Critical & Required | Critical & Required | Indicates the specific type of channel used for a transaction. Accepted values with their description: - ecom: Ecommerce transaction, this is a card-not-present transaction done over the internet.- pos: Point of Sale transaction, also known as card-present.- moto: A mail or telephone order is a card-not-present transaction where the cardholder gives permission to process the transaction by providing order and payment details by mail (not email), fax, or telephone.- atm: Automated Teller Machine transaction, where a card is used at an ATM for activities such as cash withdrawals and deposits. |
| merchant | String | Critical & Required | Critical & Required | Critical & Required | The unique identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any unique identifier is accepted. |
| mcccode | String | Critical & Required | Critical & Required | Critical & Required | A Merchant Category Code (MCC) is a four-digit number listed for financial services. An MCC is used to classify a business by the types of goods or services it provides. Only ISO 18245 mcc codes are accepted. |
| cardbin | String | Critical & Required | Critical & Required | Critical & Required | The Bank Identification Number (BIN), also known as the Issuer Identification Number (IIN), is the first six or eight digits of the card number. |
| lastfourdigits | String | Critical & Required | Critical & Required | Critical & Required | The last four digits of the card number. |
| cardexpirydate | String | Critical & Required | Critical & Required | Critical & Required | The expiry date of the card. Accepted format: MM/yy. |
| cardtoken | String | Critical & Required | Critical & Required | Critical & Required | The card token is the encryption that is used to identify the credit card. Any salted hash is accepted. |
| responsecode | String | Critical & Required | Critical & Required | Critical & Required | The response code is a numerical code that indicates the outcome of authorization checks of issuing banks. The code must be a 2 character ISO8583-1987 response. |
| success | String | Critical & Required | Critical & Required | Critical & Required | This indicates the overall result of the transaction. Accepted values are: - true: Transaction fully completed without any failures (both technical and non-technical).- false: Any part of the transaction failed or did not meet the necessary criteria, regardless of technical success.- none: The outcome of the transaction is uncertain or not yet known.Please use true only for fully successful transactions. Use false if there's any doubt or known issues, and none when outcome information is incomplete. |
| acceptorcountry | String | Important | Important | Important | Countrycode of country where the card acceptor is located. Only ISO 3166-1 numeric country codes are accepted. |
| acceptorip | String | Important | Important | Important | The acceptor IP address is the IP address of the card acceptor's terminal. For card-present transactions this terminal, which is used by the merchant to process payments, is typically located on the merchant's premises. |
| avsresult | String | Important | Important | Important | AVS (Address Verification System) result is the outcome of a check performed for Card-not-Present and MOTO transactions on the billing address provided by the shopper to see if the provided address matches the address on file with the card issuer. Accepted values are: - A: Addresses match/ZIP codes do not.- B: Street addresses match, but ZIP codes not verified due to incompatible formats.- C: Street address and postal/ZIP codes not verified due to incompatible formats.- D: Street addresses and postal/ZIP codes match (VISA).Customer name incorrect, ZIP codes match (AMEX / JCB). - E: Customer name incorrect, billing address and ZIP code match.- F: Street addresses and postal codes match (VISA). Customer name incorrect, billing address matches (AMEX / JCB).- G: Address information not verified for international transaction.- I: Address information not verified.- K: Customer name matches.- L: Customer name and ZIP code match.- M: Street addresses and postal/ZIP codes match.- N: No match.- O: Customer name and billing address match.- P: Postal/ZIP codes match. Acquirer sent both postal/ZIP code and street address, but street address not verified due to incompatible formats.- R: Retry: System unavailable or timed out. Issuer ordinarily performs address verification but was unavailable.- S: AVS not supported.- T: Nine-digit zip code matches, address does not match.- U: Information is unavailable.- W: For U.S. Addresses, nine-digit postal code matches, address does not. For address outside the U.S. postal code matches, address does not (MasterCard / Discover). Customer name, billing address, and postal code are all correct ( AMEX / JCB).- X: For U.S. addresses, nine-digit postal code and addresses matches. For addresses outside the U.S., postal code and address match.- Y: Street address and postal/ZIP match.- Z: Postal/ZIP match, street addresses do not match or street address not included in request.- none: Unknown. |
| avsused | String | Important | Important | Important | Indicates if AVS (Address Verification System) is enabled. AVS checks are performed for Card-not-Present and MOTO transactions on the billing address provided by the shopper to see if the provided address matches the address on file with the card issuer. This helps verify the identity of the shopper vs the actual cardholder. It is more likely that the shopper is the cardholder when the billing address details match. Before authentication it can already be known whether AVS is enabled, the result (avsresult) will only be known after authentication. Accepted values are: - true: AVS enabled.- false: AVS disabled.- none: Unknown. |
| cavvresult | String | Important | Important | Important | The Cardholder Authentication Verification Value (CAVV) is a value that allows VISA to validate the integrity of the Verified by Visa (VbV) transaction data for VISA 3Ds transactions. Accepted values are: - 0: CAVV authentication results invalid, no verification performed.- 1: CAVV failed verification (authentication), Issuer approves authorization.- 2: CAVV passed verification (authentication), Issuer approves authorization.- 3: CAVV passed verification (attempt), Issuer approves authorization.- 4: CAVV failed verification (attempt), Issuer approves authorization.- 5: Not Used - Reserved.- 6: CAVV not verified (VisaNet flag for Issuer not selected), Issuer approves authorization.- 7: CAVV failed verification (attempt), Issuer approves authorization.- 8: CAVV passed verification (attempt), Issuer approves authorization.- 9: CAVV failed verification (attempt), Issuer approves authorization.- A: CAVV passed verification (attempt), Issuer approves authorization.- B: CAVV passed verification (authentication).- C: CAVV failed verification (attempt).- D: CAVV failed verification (authentication).- none: Unknown. |
| cavvused | String | Important | Important | Important | Indicates if Cardholder Authentication Verification Value (CAVV) is enabled for the transaction. Before authentication it can already be known whether CAVV is enabled, the result (cavvresult) will only be known after authentication. Accepted values are: - true: CAVV enabled.- false: CAVV disabled.- none: Unknown. |
| channelsubtype | String | Important | Important | Important | Indicates the subtype of channel used for a transaction. This is a subfield of channel. Accepted values with their description: - paymentlink: The payment is done using a link that is shared by the merchant, also known as PayByLink transactions.- telephoneorder: MoTo transactions where the order and payment details are provided by telephone.- mailorder: MoTo transactions where the order and payment details are provided by mail (not email).- none: Unknown. |
| cvvresult | String | Important | Important | Important | Card Verification Value (CVV) result is the outcome of a check performed on the security code provided by the shopper to see if it matches the code on file with the card issuer. Accepted values: - M: CVV2 Match.- N: CVV2 No Match.- P: Not processed.- S: CVV2 should be on the card.- U: Issuer does not participate in CVV2 service, or participates but has not provided the encryption keys, or both.- X: No response from association.- none: Unknown. |
| cvvused | String | Important | Important | Important | Indicates if Card Verification Value (CVV) checks are done for the transaction. Card Verification Value (CVV) checs are performed on the security code provided by the shopper to see if it matches the code on file with the card issuer. Before authentication it can already be known whether CVV is enabled, the result (cvvresult) will only be known after authentication. Accepted values are: - true: CVV checks are done.- false: CVV checks are not done.- none: Unknown. |
| eci | String | Important | Important | Important | The Electronic Commerce Indicator (ECI) is the value indicating the outcome of 3D-Secure (3DS) authentication attempted on transactions where 3DS is enabled. Different card schemes use different values. Accepted values for Visa / American Express / JCB / Discover / Diners are: - 05: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.- 06: Either cardholder or card issuing bank is not 3D enrolled.- 07: Authentication is unsuccessful or not attempted.- none: Unknown.Accepted values for MasterCard are: - 02: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.- 01: Either cardholder or card issuing bank is not 3D enrolled.- 00: Authentication is unsuccessful or not attempted.- none: Unknown. |
| merchantcountry | String | Important | Important | Important | Countrycode of country where the merchant is registered. Only ISO 3166-1 numeric country codes are accepted. |
| merchantip | String | Important | Important | Important | The IP address of the merchant refers to the IP address where the merchant is registered. It is important to distinguish between the acceptor IP and the merchant IP. The acceptor IP is the location of the merchant's server where the payment is received. Therefore, a merchant can have multiple acceptor IPs, but only one merchant IP. |
| mid | String | Important | Important | Important | The unique identifier assigned to a merchant by their payment processor. It's important to note that the MID does not uniquely identify the merchant, but rather it identifies the merchant's account. This is because a merchant can have multiple MIDs, as they may have separate merchant accounts for different aspects of their business. |
| parenttransactionid | String | Important | Important | Important | The identifier that links separate events of one transaction. The parenttransactionid can link auths with captures, voids and refunds and it can link auth_captures with refunds and voids. Any unique identifier is accepted. For example: In order to link a capture with an authorization, you need to specify the transactionid of the corresponding auth or auth_capture as the parenttransactionid |
| posentrymode | String | Important | Important | Important | The Point of Sale (POS) entry mode is the code (3 digits) that identifies the method used to capture the PAN entry mode and the PIN entry capability. ISO 8583 (field 22) POS entry mode consists of 2 parts: 1. PAN (Primary Account Number) entry mode (the first 2 digits): - 00: Unknown.- 01: Key entered / Manual.- 02: Magnetic stripe.- 03: Bar code.- 05: ICC (integrated circuit card, that is, chip).- 07: Auto entry via contactless EMV.- 10: Merchant has Cardholder Credentials on File.- 80: Fallback from integrated circuit card (ICC) to magnetic stripe.- 81: Electronic commerce.- 91: Auto entry via contactless magnetic stripe.2. PIN entry capability (the third digit): - 0: Unknown- 1: Terminal can accept PINs.- 2: Terminal cannot accept PINs.- none: Completely unknown posentrymode. |
| recurring | String | Important | Important | Important | Indicates if the payment is recurring or not. Accepted values are: - true: Is recurring.- false: is not recurring.- none: Unknown. |
| threedsused | String | Important | Important | Important | Indicates if 3D-Secure (3DS) is enabled for the transaction. Before authentication it can already be known whether 3DS is enabled, the result (eci) will only be known after authentication. Accepted values are: - true: 3-D Secure has been used.- false: 3-D Secure has not been used.- none: Unknown. |
| transactioncountry | String | Important | Important | Important | The country code of the shopper's device from which the card-not-present transaction is made. Only ISO 3166-1 numeric country codes are accepted. |
| transactionip | String | Important | Important | Important | IP-address of the shopper's device with which the card-not-present transaction is made. |
| transactionintent | String | Important | Important | Important | The intent of the cardholder. Accepted values are: - purchase: the cardholder intends to make a purchase, such as buying goods or services.- card_verification: the cardholder intends to confirm the card's validity or register the card for future transactions.- withdrawal: the cardholder intends to withdraw funds, such as at an ATM or via a bank teller.- deposit: the cardholder intends to deposit funds into an account.- balance_inquiry: the cardholder intends to check their account balance at an ATM.- pin_verification: the cardholder intends to verify their PIN at an ATM without performing another transaction.- set_pin: the cardholder intends to set up or reset a PIN, often for first-time use or after a reset request.- none: Unknown |
| gatewaydeclinereason | String | n.a. | Important | Important | The gateway decline reason is a code provided by the payment gateway indicating the reason for a declined transaction. Declinecodes differ from gateway to gateway, therefore the reason of the decline is preferred. Any declinereason is accepted. E.g. Application Incomplete, Duplicate, Fraud, Risk Thresholds, Card Disabled. |
| shopperemail | String | Supplementary | Supplementary | Important | The email address of the shopper. |
| shoppername | String | Supplementary | Supplementary | Important | The name of the shopper. Any name is accepted. |
| shopperphonenumber | String | Supplementary | Supplementary | Important | The phone number of the shopper. |
| acceptorcity | String | Supplementary | Supplementary | Supplementary | City where the card acceptor is located. Any city name is accepted. |
| acceptorid | String | Supplementary | Supplementary | Supplementary | The name or unique identifier of the acceptor. Any name or unique identifier is accepted. |
| acceptorpostalcode | String | Supplementary | Supplementary | Supplementary | Postal code where the card acceptor is located. Any postal code is accepted. |
| acceptorstatecode | String | Supplementary | Supplementary | Supplementary | State where the card acceptor is located. Any state code is accepted. |
| acceptorstreetaddress | String | Supplementary | Supplementary | Supplementary | Street address where the card acceptor is located. Without acceptorip this field becomes important. Any street address is accepted. |
| acceptordeviceid | String | Supplementary | Supplementary | Supplementary | The unique identifier for the physical device on which the acceptor (terminal) is installed. Note that a single acceptor (terminal) can be associated with multiple acceptor devices. |
| acceptordevicegeocoordinates | String | Supplementary | Supplementary | Supplementary | Geographic coordinates of the acceptor's device. Only ISO 6709 format is accepted. Accepted format: {sign}{latitude}{sign}{longitude}/. |
| acquirer | String | Supplementary | Supplementary | Supplementary | The acquirer is a financial institution with whom the merchant has a bank account. |
| acquirercountry | String | Supplementary | Supplementary | Supplementary | Countrycode of country where the acquirer is registered. Only ISO 3166-1 numeric country codes are accepted. |
| authresult | String | Supplementary | Supplementary | Supplementary | Indicates if the transaction successfully passed all authentication and authorization checks. Accepted values are: - fail: failed authentication and authorization.- success: successful authentication and authorization.- none: Unknown. |
| bookingdate | Double | Supplementary | Supplementary | Supplementary | The date and time when a reservation or booking was made, applicable to services like hotels, flights, events, and car rentals. Only Unix Timestamps (UTC) are accepted. |
| bookingprocessingdate | Double | Supplementary | Supplementary | Supplementary | The date and time when a booking was processed or confirmed, which may differ from the booking date, applicable across various service sectors. Only Unix Timestamps (UTC) are accepted. |
| bookingreference | String | Supplementary | Supplementary | Supplementary | A unique code or number for identifying and tracking a booking in various service industries, from travel to event management. This code is generally a customer-facing identifier provided as a confirmation of a booking, used by the customer to reference, manage, or modify their reservation. |
| cardaccess | String | Supplementary | Supplementary | Supplementary | Information on how the card was accessed. Accepted values are: - pinaccess: Card is accessed by using a pincode.- signatureaccess: Card is accessed by using a signature.- hybrid: Card is accessed by using a pincode and a signature.- none: Unknown. |
| cardholder | String | Supplementary | Supplementary | Supplementary | The name or unique identifier of the cardholder. This is not the same as the cardtoken, as a cardholder can have multiple credit cards (cardtokens). Any name or unique identifier is accepted. |
| cardholderemail | String | Supplementary | Supplementary | Supplementary | The email address of the card holder. |
| cardholderphonenumber | String | Supplementary | Supplementary | Supplementary | The phone number of the card holder. |
| checkindate | Double | Supplementary | Supplementary | Supplementary | The date when a customer or guest is scheduled to start their service, like arriving at a hotel, boarding a flight, or picking up a rental car. Only Unix Timestamps (UTC) are accepted. |
| checkoutdate | Double | Supplementary | Supplementary | Supplementary | The date when the service concludes, such as the end of a hotel stay, return of a rental car, or completion of an event. Only Unix Timestamps (UTC) are accepted. |
| ddresult | String | Supplementary | Supplementary | Supplementary | The dynamic descriptor result returned by the processor is the text that represents businesses on bank account statements. Can be up to 22 characters long. |
| deviceid | String | Supplementary | Supplementary | Supplementary | The mobile device id or any other device id. Any id is accepted. |
| deviceos | String | Supplementary | Supplementary | Supplementary | The operating system (os) of the mobile device. Any os is accepted. |
| devicephonenumber | String | Supplementary | Supplementary | Supplementary | The phone number of the mobile device. Any phone number is accepted. |
| initialrecurring | String | Supplementary | Supplementary | Supplementary | Indicates if the transaction is the first of a series of recurring transactions. Accepted values are: - true: The transaction is the first of a series of recurring transactions.- false: The transaction is not the first of a series of recurring transactions.- none: Unknown. |
| merchantadvicecode | String | Supplementary | Supplementary | Supplementary | The merchant advice code is a code provided by the merchant's payment processor that indicates the reason for a declined transaction, and how it can be retried. |
| merchantname | String | Supplementary | Supplementary | Supplementary | The name of the merchant. Any name is accepted. |
| merchantcity | String | Supplementary | Supplementary | Supplementary | City where the merchant is registered. Without merchantip this field becomes important. Any city is accepted. |
| merchantpostalcode | String | Supplementary | Supplementary | Supplementary | Postal code where the merchant is registered. Without merchantip this field becomes important. Any postal code is accepted. |
| merchantstatecode | String | Supplementary | Supplementary | Supplementary | State where the merchant is registered. Without merchantip this field becomes important. Any state code is accepted. |
| merchantstreetaddress | String | Supplementary | Supplementary | Supplementary | Street address where the merchant is registered. Without merchantip this field becomes important. Any street address is accepted. |
| operationdate | Double | Supplementary | Supplementary | Supplementary | The scheduled date and time for a specific operation, such as a hotel stay, flight, event attendance, or car rental period. Only Unix Timestamps (UTC) are accepted. |
| operationid | String | Supplementary | Supplementary | Supplementary | The unique identifier used internally by service providers to manage and track a variety of operational activities, including hotel reservations, flights, events, and car rentals, across different service-oriented industries. |
| processor | String | Supplementary | Supplementary | Supplementary | A payment processor is a company (often a third party) appointed by a merchant to handle transactions from various channels such as credit cards and debit cards for merchant acquiring banks. |
| proxyused | String | Supplementary | Supplementary | Supplementary | Indicates whether a proxy server was used. |
| recurringparentid | String | Supplementary | Supplementary | Supplementary | The identifier that links back to the initial recurring transaction (the first of a series of recurring transactions). |
| submerchant | String | Supplementary | Supplementary | Supplementary | The name or unique identifier of the submerchant, which is a merchant that processes under a payment service provider or payment facilitator. These services use one merchant account to process the transactions of many sub-merchants, thereby eliminating the need for each sub-merchant to open and maintain a fully-fledged merchant account. Any name or unique identifier is accepted. |
| terminaltype | String | Supplementary | Supplementary | Supplementary | The type of unattended POS terminal, also known as Cardholder-Activated Terminal (CAT) types. Accepted values are: - cat1: Automated Dispensing Machine- cat2: Self Service Terminal- cat3: Limited Amount Terminal- cat4: InFlight Terminal- cat6: Electronic Commerce- cat7: Transponder- cat9: MPOS (mobile POS)- none: Unknown. |
| transactioncity | String | Supplementary | Supplementary | Supplementary | City of the shopper's device with which the card-not-present transaction is made |
| transactionpostalcode | String | Supplementary | Supplementary | Supplementary | Postal code of the shopper's device with which the card-not-present transaction is made. |
| transactionstatecode | String | Supplementary | Supplementary | Supplementary | State of the shopper's device with which the card-not-present transaction is made. |
| transactionstreetaddress | String | Supplementary | Supplementary | Supplementary | Street address of the shopper's device with which the card-not-present transaction is made. |
| ucafindicator | String | Supplementary | Supplementary | Supplementary | The Universal Cardholder Authentication (UCAF) indicator indicates to what extend the UCAF data collection is supported for MasterCard 3DS transactions. Accepted values are: - 0: UCAF data collection is not supported by the merchant.- 1: UCAF data collection is supported by the merchant, and UCAF data may be present and contain an attempted AAV.- 2: UCAF data collection is supported by the merchant and UCAF data must be present and contain a fully authenticated AAV.- none: Unknown. |
| kyclevel | String | n.a. | Supplementary | Important | The Know-Your-Customer level of the merchant. Any indication level is accepted. |
| limitprofile | String | n.a. | Supplementary | Important | The limit profile of a merchant is a set of limits imposed on the daily/weekly/monthly transaction amounts. A low limit profile number denotes low limits on all transactions. |
| merchantemail | String | n.a. | Supplementary | Important | The email address of the merchant. |
| merchantturnover | String | n.a. | Supplementary | Important | Expected monthly turnover (auths and authcaptures) to be processed through the merchant's account in euros. |
| merchanturl | String | n.a. | Supplementary | Important | URL of merchant web site or page where transaction took place. Any URL is accepted. |
| registrationdate | Double | n.a. | Supplementary | Important | The time UTC at which the merchant got registered. Only Unix Timestamps are accepted. |
| ubo | String | n.a. | Supplementary | Important | The full name of the Ultimate Beneficial Owner (UBO). The UBO is the individual that is registered as the owner of the merchant account. |
| ubocountry | String | n.a. | Supplementary | Important | Countrycode of country where the ubo is registered. Only ISO 3166-1 numeric country codes are accepted. |
| gateway | String | n.a. | Supplementary | Supplementary | A payment gateway is a merchant service that facilitates a payment transaction by the transfer of information between a payment portal (such as a website, mobile phone or interactive voice response service) and the front end processor or acquiring bank. |
| iso | String | n.a. | Supplementary | Supplementary | The full name of the Independent Sales Organisation (ISO) that accepts credit card payments for the merchant account that is in its portfolio. |
| isocountry | String | n.a. | Supplementary | Supplementary | The country of the ISO. |
| kyclevelnorm | Double | n.a. | Supplementary | Supplementary | A normalized know-your-customer level of the merchant between 0 and 1, where 0 is a totally unknown and untrusted merchant and 1 is a fully known and absolutely trusted merchant. |
| ocptenabled | String | n.a. | Supplementary | Supplementary | Indicates if ocpt is enabled for this merchant. When ocpt is enabled, payout back to the cardholder is supported. |
| payfac | String | n.a. | Supplementary | Supplementary | The full name of the Payment Facilitator that has the merchant account in its portfolio. |
| payfaccountry | String | n.a. | Supplementary | Supplementary | The country of the Payment Facilitator. |
| uboemail | String | n.a. | Supplementary | Supplementary | The email address of the ubo. |
| ubophonenumber | String | n.a. | Supplementary | Supplementary | The phone number of the ubo. |
| ubostreetaddress | String | n.a. | Supplementary | Supplementary | Street address where the ubo is registered. Without merchantip this field becomes important. Any street address is accepted. |
| bankaccountnumber | String | n.a. | n.a. | Supplementary | Bank Account Number. This refers to the International Bank Account Number (IBAN) or any equivalent national bank account number or ID. |
| digitalwalletoperator | String | n.a. | n.a. | Supplementary | Indicates the Digital Wallet Operator (DWO). A digital wallet refers to an electronic system that allows customers to pay for purchases without presenting a physical credit or debit card. Accepted values are: - staged: A staged digital wallet transaction is done with a wallet that uses multiple "stages" to complete the transaction (a "funding" stage and a "payment" stage) and doesn't necessarily pass along card information to the card brand or issuer.- pass_through: A pass-through digital wallet transaction is done with a wallet where card payment information is used directly in the transaction, and passed along to the issuer and card network.- none: Unknown. |
Dispute Events
View API Endpoint for Dispute Events
Toggle to view the batch schema for Dispute Events
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| transactionid | String | Critical & Required | Critical & Required | Supplementary | The unique identifier of the transaction event. Every transaction event, so auth, capture, auth_capture, etc., has its own unique ID. |
| timestamp | Double | Critical & Required | Critical & Required | Supplementary | The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted. |
| reporttype | String | Critical & Required | Critical & Required | Supplementary | The type of fraud report. Please note: 1st chargebacks and fraud notifications are the priority here, especially during integration! Accepted values are: - fraud notification: Fraud activity reported by the (cardholder's) bank. Examples are Visa's TC40 files and MasterCard's SAFE files.- 1st chargeback: First stage of the chargeback where the disputed amount is withdrawn from the merchant's account.- information supplied: Defense documents against the 1st chargeback are supplied.- chargeback reversal: The disputed amount is transferred back to the merchant's account.- pre-arbitration: A stage in a chargeback dispute where the issuer, unconvinced with the merchant's provided evidence, escalates the case for further review, serving as an intermediate step before potential full arbitration.- 2nd chargeback: 2nd and definite chargeback where the disputed amount is withdrawn from the merchant's account. |
| merchant | String | Critical & Required | Critical & Required | Supplementary | The unique identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any unique identifier is accepted. |
| chargebackreason | String | Critical & Required | Critical & Required | Supplementary | Reason for the chargeback. |
| fraudimportdate | Double | Important | Important | Supplementary | Timestamp when a dispute was opened. |
| chargebackid | String | Supplementary | Supplementary | Supplementary | External ID of this chargeback, unique for the customer. |
| fraudreason | String | Supplementary | Supplementary | Supplementary | Reason why the transaction was fraudulent. |
| amount | Double | Supplementary | Supplementary | Supplementary | The transaction amount in the unit specified by the currencyunit field and in the currency specified by the currency field. |
| currency | String | Supplementary | Supplementary | Supplementary | The 3-digit ISO code for the currency used in the transaction. |
| currencyunit | String | Supplementary | Supplementary | Supplementary | This field defines the unit of currency used in the 'amount' field. Accepts only major (e.g., 12.30) or minor (e.g., 1230) unit values. This choice should align with the unit used in the 'amount' field. |
| statusid | String | Supplementary | Supplementary | Supplementary | The Status ID for a dispute or chargeback event is a unique identifier indicating the current status of the process, such as pending, lost, or won. It tracks the event's progression from initiation to resolution. |
Account Bank Transfers
View API Endpoint for Account Bank Transfers
Toggle to view the batch schema for Account Bank Transfers
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| transactionid | String | n.a. | n.a. | Important | The unique identifier of the transaction event. Every transaction event, so auth, capture, auth_capture, etc., has its own unique ID. |
| timestamp | Double | n.a. | n.a. | Important | The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted. |
| transactiontype | String | n.a. | n.a. | Important | The type of transaction event. Accepted values are: - payout: A direct transfer of funds (OCT) to credit card holders.- withdrawal: The withdrawal of cash from a bank account.- deposit: The deposit of cash into a bank account.- bank_incoming_transfer: The incoming transfer of money into a bank account.- bank_outgoing_transfer: The outgoing transfer of money out of a bank account.- wallet_incoming_transfer: The incoming transfer of money into a wallet.- wallet_outgoing_transfer: The outgoing transfer of money out of a wallet. |
| amount | Double | n.a. | n.a. | Important | The transaction amount in the unit specified by the currencyunit field and in the currency specified by the currency field. |
| currency | String | n.a. | n.a. | Important | The 3-digit ISO code for the currency used in the transaction. |
| currencyunit | String | n.a. | n.a. | Important | This field defines the unit of currency used in the 'amount' field. Accepts only major (e.g., 12.30) or minor (e.g., 1230) unit values. This choice should align with the unit used in the 'amount' field. |
| merchant | String | n.a. | n.a. | Important | The unique identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any unique identifier is accepted. |
| bankaccountnumber | String | n.a. | n.a. | Supplementary | Bank Account Number. This refers to the International Bank Account Number (IBAN) or any equivalent national bank account number or ID. |
| walletid | String | n.a. | n.a. | Supplementary | External ID of the merchant wallet. |
Inter Account Transfers
View API Endpoint for Inter Account Transfers
Toggle to view the batch schema for Inter Account Transfers
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| sender_transactionid | String | n.a. | n.a. | Important | ID of the transaction for the sending wallet. |
| receiver_transactionid | String | n.a. | n.a. | Important | ID of the transaction for the receiving wallet. |
| timestamp | Double | n.a. | n.a. | Important | The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted. |
| sender_merchant | String | n.a. | n.a. | Important | The name or identifier of the merchant corresponding to the sender wallet. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted. |
| receiver_merchant | String | n.a. | n.a. | Important | The name or identifier of the merchant corresponding to the receiving wallet. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted. |
| amount | Double | n.a. | n.a. | Important | The transaction amount in the unit specified by the currencyunit field and in the currency specified by the currency field. |
| currency | String | n.a. | n.a. | Important | The 3-digit ISO code for the currency used in the transaction. |
| currencyunit | String | n.a. | n.a. | Important | This field defines the unit of currency used in the 'amount' field. Accepts only major (e.g., 12.30) or minor (e.g., 1230) unit values. This choice should align with the unit used in the 'amount' field. |
| sender_walletid | String | n.a. | n.a. | Supplementary | ID of the sending wallet. |
| receiver_walletid | String | n.a. | n.a. | Supplementary | ID of the receiving wallet. |
Merchant Evaluations
View API Endpoint for Merchant Evaluations
Toggle to view the batch schema for Merchant Evaluations
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| timestamp | Double | n.a. | n.a. | Important | The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted. |
| merchant | String | n.a. | n.a. | Important | The unique identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any unique identifier is accepted. |
| evaluation | String | n.a. | n.a. | Important | Outcome of the latest evaluation of the merchant. Valid values are: - legitimate- suspicious- fraudster |
| comment | String | n.a. | n.a. | Important | The comment field is a free-form text field that can be used to provide additional information about merchant evaluations. This is information that is not yet covered by the categories that are defined as values for the evaluation field. After having done an investigation on merchants, analysts often provide comments on why the merchant was closed down (or not). Example values are "suspected money launderer, large number of transactions from High Risk countries", or "blocked due to large number of refunds". |
Merchant Account Information
View API Endpoint for Merchant Account Information
Toggle to view the batch schema for Merchant Account Information
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| merchant | String | Supplementary | Supplementary | Supplementary | The unique identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any unique identifier is accepted. |
| mcccode | String | Supplementary | Supplementary | Supplementary | A Merchant Category Code (MCC) is a four-digit number listed for financial services. An MCC is used to classify a business by the types of goods or services it provides. Only ISO 18245 mcc codes are accepted. |
| acquirer | String | Supplementary | Supplementary | Supplementary | The acquirer is a financial institution with whom the merchant has a bank account. |
| acquirercountry | String | Supplementary | Supplementary | Supplementary | Countrycode of country where the acquirer is registered. Only ISO 3166-1 numeric country codes are accepted. |
| merchantname | String | Supplementary | Supplementary | Supplementary | The name of the merchant. Any name is accepted. |
| merchantcity | String | Supplementary | Supplementary | Supplementary | City where the merchant is registered. Without merchantip this field becomes important. Any city is accepted. |
| merchantcountry | String | Supplementary | Supplementary | Supplementary | Countrycode of country where the merchant is registered.Only ISO 3166-1 numeric country codes are accepted |
| merchantip | String | Supplementary | Supplementary | Supplementary | The IP address of the merchant refers to the IP address where the merchant is registered. It is important to distinguish between the acceptor IP and the merchant IP. The acceptor IP is the location of the merchant's server where the payment is received. Therefore, a merchant can have multiple acceptor IPs, but only one merchant IP. |
| merchantpostalcode | String | Supplementary | Supplementary | Supplementary | Postal code where the merchant is registered. Without merchantip this field becomes important. Any postal code is accepted. |
| merchantstatecode | String | Supplementary | Supplementary | Supplementary | State where the merchant is registered. Without merchantip this field becomes important. Any state code is accepted. |
| merchantstreetaddress | String | Supplementary | Supplementary | Supplementary | Street address where the merchant is registered. Without merchantip this field becomes important. Any street address is accepted. |
| merchantgeocoordinates | String | Supplementary | Supplementary | Supplementary | Geographic coordinates where the merchant is registered. Only ISO 6709 format is accepted. Accepted format: {sign}{latitude}{sign}{longitude}/. |
| mid | String | Supplementary | Supplementary | Supplementary | The unique identifier assigned to a merchant by their payment processor. It's important to note that the MID does not uniquely identify the merchant, but rather it identifies the merchant's account. This is because a merchant can have multiple MIDs, as they may have separate merchant accounts for different aspects of their business. |
| iso | String | n.a. | Supplementary | Supplementary | The full name of the Independent Sales Organisation (ISO) that accepts credit card payments for the merchant account that is in its portfolio. |
| isocountry | String | n.a. | Supplementary | Supplementary | The country of the ISO. |
| kyclevel | String | n.a. | Supplementary | Supplementary | The Know-Your-Customer level of the merchant. Any indication level is accepted. |
| kyclevelnorm | Double | n.a. | Supplementary | Supplementary | A normalized know-your-customer level of the merchant between 0 and 1, where 0 is a totally unknown and untrusted merchant and 1 is a fully known and absolutely trusted merchant. |
| limitprofile | String | n.a. | Supplementary | Supplementary | The limit profile of a merchant is a set of limits imposed on the daily/weekly/monthly transaction amounts. A low limit profile number denotes low limits on all transactions. |
| merchantemail | String | n.a. | Supplementary | Supplementary | The email address of the merchant. |
| merchantturnover | String | n.a. | Supplementary | Supplementary | Expected monthly turnover (auths and authcaptures) to be processed through the merchant's account in euros. |
| merchanturl | String | n.a. | Supplementary | Supplementary | URL of merchant web site or page where transaction took place. Any URL is accepted. |
| ocptenabled | String | n.a. | Supplementary | Supplementary | Indicates if ocpt is enabled for this merchant. When ocpt is enabled, payout back to the cardholder is supported. |
| payfac | String | n.a. | Supplementary | Supplementary | The full name of the Payment Facilitator that has the merchant account in its portfolio. |
| payfaccountry | String | n.a. | Supplementary | Supplementary | The country of the Payment Facilitator. |
| registrationdate | Double | n.a. | Supplementary | Supplementary | The time UTC at which the merchant got registered. Only Unix Timestamps are accepted. |
| ubo | String | n.a. | Supplementary | Supplementary | The full name of the Ultimate Beneficial Owner (UBO). The UBO is the individual that is registered as the owner of the merchant account. |
| ubocountry | String | n.a. | Supplementary | Supplementary | Countrycode of country where the ubo is registered. Only ISO 3166-1 numeric country codes are accepted. |
| uboemail | String | n.a. | Supplementary | Supplementary | The email address of the ubo. |
| ubophonenumber | String | n.a. | Supplementary | Supplementary | The phone number of the ubo. |
| ubostreetaddress | String | n.a. | Supplementary | Supplementary | Street address where the ubo is registered. Without merchantip this field becomes important. Any street address is accepted. |
| walletid | String | n.a. | n.a. | Supplementary | External ID of the merchant wallet. |
How to Transfer Historical Data to Fraudio?
Transfer historical data to Fraudio by uploading CSV files to our Amazon S3 storage. For alternative data transfer methods, please contact us.
Step 1: Get Fraudio Credentials
- Request credentials to authenticate with AWS CLI from Fraudio, including your
CUSTOMER_NAME, which is needed to view and upload files.
Step 2: Install AWS CLI
- Install the AWS CLI by following the official guide.
Step 3: Log into AWS
- Use the AWS CLI to configure your credentials. Run the command
aws configureand enter your key ID and secret when prompted.
Step 4: Upload Your Data
- Use the AWS CLI or your preferred S3 client to upload your CSV files to the designated S3 bucket provided by Fraudio.
Step 5: Confirm Upload Completion
- Verify that all files have been successfully uploaded by checking the S3 bucket. You can use the AWS Management Console or CLI commands to list the files in the bucket.
Step 6: Notify Fraudio
- Once the upload is complete, inform your Fraudio representative to initiate the data processing and integration.
Batch Integration
At Fraudio, we specialize in real-time transaction fraud monitoring through our API. This integration allows you to inform us of transactions as they occur, enabling prompt fraud identification, AI adaptation for future transactions, and bolstering our fraud detection capabilities.
While we strongly recommend the real-time API integration for its simplicity and effectiveness, we recognize that certain circumstances may necessitate alternative solutions. Factors such as resource constraints or technical infrastructure limitations could impede real-time integration.
To accommodate these situations, we offer an alternative method: batch transfer integration. This approach entails uploading files on a scheduled basis rather than transmitting data in real-time via the API.
With this method, you can upload new files at a regular interval, which will be automatically imported into our systems. This ensures that our platform can continue to provide timely and efficient fraud detection and prevention.
Comparison: API Integration vs. Batch Integration
| API Integration | Batch Integration | |
|---|---|---|
| Large amounts of data at once | no | yes |
| Programming effort | medium | low |
| Encrypted by default | yes | yes |
| Transaction fraud detection period | sub-seconds | days |
| Merchant fraud detection period | less than a day | days |
| Data quality reporting | Automatic | On Request |
| Protocol | HTTPS | S3 |
| Format | JSON | Zipped CSV |
| Authentication | API Token | Key ID + Secret |
| Maximal no. of scored transactions per day | no limit | 10.000.000 (soft limit) |