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
-
Adherence to API Data Schemas: Ensure that the historical data adheres to the data schemas of the API Endpoints that are used. For a detailed description of the batch data schemas, please refer to the Batch Data Schemas section.
-
Consistency with Data Quality of Live Data: 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.
-
Consistency of Data Volume: Ensure that there are no gaps in the data by verifying that transactions are present for each day to maintain completeness. It is recommended to send at least 24 months of historical data.
-
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 Financial Events Screening endpoint. This ensures continuity and accuracy in our fraud scoring models, providing effective fraud protection.
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 event type that is sent to the API, we would like to receive the corresponding historical data in batch. Therefore it is important to align with the data that is sent to the API.
For historical batches, we recommend following the schema of the Financial Events Enrichment endpoint. It is not necessary to split events by transactions that require scoring versus enrichment. Include post-auth information for complete context (for example authorization response fields on 0110 events).
If you prefer, you may also send transaction events separately as on the live API. That typically involves more effort and is generally not necessary for batch processing. In that case, follow Financial Events Screening and Financial Events Enrichment (including authorization response events for post-auth fields).
Event types you may include in the same Enrichment-shaped batch:
- Financial events (purchases, captures, refunds, and similar) via Financial Events Enrichment
- Dispute events (
dispute, for example chargebacks and TC40/SAFE) via dispute - Bank transfers (
bank_transfer) via bank_transfer - Entity updates (merchants, cards, wallets, and other entity types) via entities-only with an empty
eventsarray
Toggle to view the Financial Events Enrichment schema used for batch
| Field | Data Type | Payment Fraud (Issuer) | Payment Fraud (Acquirer / Processor) | Merchant Fraud / AML | Description |
|---|---|---|---|---|---|
| events[].type | String | Required | Required | Required | Event type to enrich. Examples: card_network_transaction, refund, void, capture, reversal, chargeback, dispute, wallet_withdrawal, wallet_deposit, payout, bank_transfer, wallet_transfer. |
| events[].id | String | Required | Required | Required | Unique identifier of the event. |
| events[].timestamp | Double | Required | Required | Required | UTC time of the event as a Unix timestamp (seconds; may be fractional). |
| events[].parent_event_id | String | Optional | Optional | Optional | Direct parent transaction/event ID for chained events. |
| events[].lifecycle_rrn | String | Optional | Optional | Optional | Lifecycle identifier shared across chained transactions (RRN). |
| events[].details.mti | String | Optional | Optional | Optional | ISO 8583 MTI when applicable. |
| events[].details.transaction_type | String | Optional | Optional | Optional | ISO 8583 DE003 transaction type when applicable. |
| events[].details.currency | String | Optional | Optional | Optional | 3-digit ISO currency code. |
| events[].details.currency_unit | String | Optional | Optional | Optional | major or minor. |
| events[].details.amount | Double | Optional | Optional | Optional | Amount in the currency and unit provided. |
| events[].details.response_code | String | Optional | Optional | Optional | Authorization or financial response code from the issuer/network (for example ISO 8583 DE039). Typical on 0110 / post-auth events. |
| events[].details.eci | String | Optional | Optional | Optional | Electronic Commerce Indicator from 3-D Secure or equivalent authentication. |
| events[].details.avs_result | String | Optional | Optional | Optional | Address Verification System (AVS) result code. |
| events[].details.cvv_result | String | Optional | Optional | Optional | Card verification value (CVV/CVC) check result. |
| events[].details.cavv_result | String | Optional | Optional | Optional | Cardholder Authentication Verification Value (CAVV) or equivalent authentication result. |
| events[].details.sister_transaction_id | String | Optional | Optional | Optional | ID of the counterpart record for the same transfer, used when a single transfer is represented by two records (e.g. one per side). When migrating from v1/transactions/inter-account-transfers, map receiver_transactionid here. |
| events[].details.pos_entry_mode | String | Optional | Optional | Optional | ISO POS entry mode when applicable. |
| events[].details.pos_condition_code | String | Optional | Optional | Optional | ISO POS condition code when applicable. |
| events[].details.mcc | String | Optional | Optional | Optional | Merchant category code as processed on this event/transaction. Distinct from registered MCCs on a merchant_account or sub_merchant entity. |
| events[].sender.refs.card | String | Optional | Optional | Optional | Reference to a card entity when applicable. |
| events[].sender.refs.wallet | String | Optional | Optional | Optional | Reference to a wallet entity when the wallet is the sender (e.g., wallet withdrawal, payout events). |
| events[].sender.refs.merchant_business | String | Optional | Optional | Optional | 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[].sender.refs.bank_account | String | n.a. | n.a. | Optional | Reference to a bank_account entity when the bank account is the sender (e.g., wallet deposit events). |
| events[].receiver.refs.wallet | String | Optional | Optional | Optional | Reference to a wallet entity when the wallet is the receiver (e.g., wallet deposit events). |
| events[].receiver.refs.merchant_business | String | Optional | Optional | Optional | Reference to a merchant_business entity when the merchant is the receiving party. Should be included alongside wallet reference for wallet deposit events. |
| events[].receiver.refs.bank_account | String | n.a. | n.a. | Optional | Reference to a bank_account entity when the bank account is the receiver (e.g., wallet withdrawal events). |
| events[].receiver.refs.acceptor | String | Optional | Optional | Optional | Reference to an acceptor entity when applicable. |
| events[].refs.gateway | String | Optional | Optional | Optional | Reference to the payment gateway (intermediary). |
| events[].refs.acquirer | String | Optional | Optional | Optional | Reference to the acquirer (intermediary). |
| entities[] | Array | Optional | Optional | Optional | Top-level array of entity objects. Entities are correlated to events through refs, not by nesting. |
| entities[].type | String | Optional | Optional | Optional | Entity type, e.g. merchant_business, merchant_account, sub_merchant, card, wallet, acquirer, payfac, etc. |
| entities[].id | String | Optional | Optional | Optional | Stable entity identifier. |
| entities[].name | String | Optional | Optional | Optional | Entity name when available. |
| entities[].country_code | String | Optional | Optional | Optional | Entity country code when available. |
| entities[].limitprofile | String | Optional | Optional | Optional | Merchant limit profile (can be partial update; null to clear). |
| entities[].mccs | Array | Optional | Optional | Optional | Registered / assigned MCC list on a merchant_account or sub_merchant entity. Do not send on merchant_business; use event.details.mcc for the as-processed code on a transaction. |
| entities[].mid | String | Optional | Optional | Optional | Processor- or acquirer-assigned Merchant ID on a merchant_account entity. |
| entities[].terminal_type | String | Optional | Optional | Optional | Cardholder-Activated Terminal (CAT) type on an acceptor entity (e.g. cat1, cat2, cat6, cat9). |
| entities[].type=bank_account | String | n.a. | n.a. | Optional | A bank account entity. Used as sender or receiver in wallet withdrawal and deposit events. The entity id is a stable identifier for the account. |
| entities[].iban | String | n.a. | n.a. | Optional | IBAN (or equivalent national account number) for bank_account entities. |
| entities[].refs.merchant_business | String | n.a. | n.a. | Optional | Reference from another entity to a merchant_business (e.g. wallet or bank account belonging to the merchant). |
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) |