Historical Data
Why Forter asks for your historical data
To ensure the highest level of accuracy for our decisioning model, Forter customizes our model to fit the specific risk profile of each of our customers. We achieve this by training the model with your past order and account data, including actual fraud outcomes, in order to provide you with better accuracy from Day 1.
To provide the best results, we require comprehensive historical data including many of the data points that are required for a live integration. The timeframe for the requested data will depend on your traffic volume and the solutions you are leveraging. This helps us to understand both new and established buyer patterns.
If for any reason you're unable to provide us with data covering the specified timeframe, you should notify your dedicated Implementation Manager who will provide guidance on a suitable path forward.
Download a template
Below, you will find details on what historical data is relevant to share with Forter, including a CSV example that may serve as a template. Each header column in the template maps to a parameter in our API, so you can use the API Reference for formatting requirements and enum options for each field. A few fields that are specific to historical data are defined below.
Upload file securely
Forter processes your historical order data offline using batch files in a CSV format. To ensure secure transmission of this data, please format your extracted data in the CSV format provided and upload to a dedicated AWS S3 folder that we have created for your account.
You can find instructions on how to set up your credentials and access the folder here.
Forter requires 12 months of order data to account for spikes in traffic, promotional and seasonality effects. Order history should include traffic from payment methods even if they are excluded from decisioning, as well as any order attempts that resulted in payment authorization failure, were declined for fraud, or otherwise canceled. The required data points include buyer information, cart items, payment methods, promotions used, as well as billing and shipping details, using the same fields as the Order API.
The model also needs to know the fulfillment status of each order, as well as any declined transactions and related chargebacks or fraud notifications. While fulfillment status would normally be provided in a subsequent call to the Order Status API in your live integration, please include it along with your order history under historicalData.status. Enum options are: COMPLETED, CANCELED_BY_MERCHANT, CANCELED_BY_CUSTOMER.
In the case of transactions that were declined for suspicion of fraud, mark the order as historicalData.status = CANCELED_BY_MERCHANT and historicalData.fraud = DECLINED_FOR_FRAUD.
In the case of transactions that were processed but a chargeback or fraud notification was later received, mark the order as historicalData.status = COMPLETED and use one of the following enums for historicalData.fraud:
- FRAUD_CHARGEBACK - dispute submitted by the customer with a reason code of fraud, or a retrieval request otherwise known as a “soft chargeback”
- SERVICE_CHARGEBACK - dispute submitted by the customer for item not received or for not meeting the quality standard expected
- PRE_CHARGEBACK_ALERT - notification of an incoming dispute from a third party
- FRAUD_REFUND - complaint of fraud by the customer without a formal dispute
If your fraud data is not available in the same system as your order history, you may upload this information separately. Please refer to the instructions below for Dispute history.
Build your template
For Order history, the specific columns to send to Forter vary based on your particular integration. To create a customized template, you can use the CSV base template below and add the relevant columns for your relevant vertical and any payment methods.
accountOwner.accountId,accountOwner.created,accountOwner.email,accountOwner.firstName,accountOwner.lastName,cartItems[0].basicItemData.name,cartItems[0].basicItemData.quantity,cartItems[0].basicItemData.category,cartItems[0].basicItemData.price.amountLocalCurrency,cartItems[0].basicItemData.price.amountUSD,cartItems[0].basicItemData.price.currency,checkoutTime,connectionInformation.customerIP,historicalData.fraud,historicalData.orderStatus,orderId,orderType,payment[0].billingDetails.address.address1,payment[0].billingDetails.address.address2,payment[0].billingDetails.address.city,payment[0].billingDetails.address.country,payment[0].billingDetails.address.region,payment[0].billingDetails.address.zip,payment[0].billingDetails.personalDetails.email,payment[0].billingDetails.phone[0].phone,payment[0].billingDetails.personalDetails.fullName,payment[0].billingDetails.personalDetails.firstName,payment[0].billingDetails.personalDetails.lastName,payment[0].creditCard.bin,payment[0].creditCard.expirationMonth,payment[0].creditCard.expirationYear,payment[0].creditCard.lastFourDigits,payment[0].creditCard.nameOnCard,payment[0].creditCard.verificationResults.eciValue,payment[0].creditCard.verificationResults.processorResponseCode,payment[0].creditCard.verificationResults.processorResponseText,primaryDeliveryDetails.deliveryMethod,primaryDeliveryDetails.deliveryType,primaryRecipient.personalDetails.email,primaryRecipient.phone[0].phone,totalAmount.amountLocalCurrency,totalAmount.amountUSD,totalAmount.currency
e520-ba9a-367-60b,1415273168,[email protected],John,Smith,White GenericBrand handbag,1,Apparel and accessories,105.55,99.95,CAD,1699916780,10.0.0.127,SERVICE_CHARGEBACK,COMPLETED,4306795,WEB,235 Montgomery st.,Ste. 1110,San Francisco,US,CA,2157-08-23,[email protected],15557654321,John Smith,John,Smith,42424242,3,2018,4242,John R. H. Smith,5,D23,Stolen card,USPS - Ground Mail,PHYSICAL,[email protected],15557654321,105.55,99.95,CADAdd relevant columns for cart item details, based on the type of goods you sell.
primaryRecipient.address.address1,primaryRecipient.address.address2,primaryRecipient.address.city,primaryRecipient.address.zip,primaryRecipient.address.country,primaryRecipient.address.region
235 Montgomery st.,Ste. 1110,San Francisco,94104,US,CAInclude relevant payment methods for your integration. Credit card is already included in the base CSV.
payment[0].applePay.bin,payment[0].applePay.expirationMonth,payment[0].applePay.expirationYear,payment[0].applePay.lastFourDigits,payment[0].applePay.nameOnCard
,3,2018,4242,John R. H. SmithAlternatively, you can download the comprehensive template file and remove the irrelevant columns.
Orders with multiple cart items
For orders that have multiple cart items or multiple payment methods, which are represented in arrays, please follow one of the patterns below.
orderId,cartItems[0].basicItemData.name,cartItems[0].basicItemData.quantity,cartItems[0].basicItemData.category,cartItems[0].basicItemData.price.amountUSD,cartItems[1].basicItemData.name,cartItems[1].basicItemData.quantity,cartItems[1].basicItemData.category,cartItems[1].basicItemData.price.amountUSD,cartItems[2].basicItemData.name,cartItems[2].basicItemData.quantity,cartItems[2].basicItemData.category,cartItems[2].basicItemData.price.amountUSD,totalAmount.amountUSD
4306795,White GenericBrand handbag,1,Apparel and accessories,99.95,Brown GenericBrand wallet,1,Apparel and accessories,39.95,Green GenericBrand duffel,1,Apparel and accessories,69.95,209.85Forter requires 12 months of historical dispute data covering all of the order data provided. Most claims are issued within 90 days from the time of transaction. As a result, dispute history is not expected to match the order history time frame perfectly.
If you were able to include dispute data in the historicalData.fraud field in your Order history, you may skip this step. If not, please share this data in an additional CSV that includes the orderID from your Order history file along with the reason string that was provided by the processor or claim source.
orderId,reason
4306795,Fraudulent Transaction: Card Not Present EnvironmentForter requires 6 to 12 months of historical account signup data.
Signup history should contain the information provided by the customer as part of the registration process as well as data captured in the background such as account ID, timestamp, and connection information. The required data points use mostly the same fields as the Signup API.
Given that the accounts could have been closed or suspended in that timeframe, Forter also requests that you provide us with the current status of the account, though in your live integration this will be shared via Account Status API. The enum options for accountData.status are: ACTIVE, SUSPENDED, CLOSED, GUEST, PENDING.
accountId,eventTime,signupStatus,connectionInformation.customerIP,connectionInformation.userAgent,connectionInformation.merchantDeviceIdentifier,accountData.personalDetails.firstName,accountData.personalDetails.lastName,accountData.personalDetails.email,accountData.type,accountData.status
e520-ba9a-367-60b,1415287568000,SUCCESS,10.0.0.127,"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",HGJ7512345H3,John,Smith,[email protected],BUSINESS,ACTIVEForter requires 6 months of historical account login data.
Login history should contain all the information collected during login, such as the inputs entered by the customer, as well as data captured in the background such as timestamp, connection information, and the existing account details. The required data points use mostly the same fields as the Login API.
Your dataset should include login attempts that resulted in failure, so that our models can learn from these as well. The enum options for loginStatus are: SUCCESS, FAILED, BLOCKED_BY_MERCHANT, ACCOUNT_DOES_NOT_EXIST.
Given that the accounts could have been closed or suspended since the login event, Forter also requests that you provide us with the current status of the account, though in your live integration this will be shared via Account Status API. The enum options for accountData.status are: ACTIVE, SUSPENDED, CLOSED, GUEST, PENDING.
accountId,eventTime,connectionInformation.customerIP,connectionInformation.userAgent,connectionInformation.merchantDeviceIdentifier,loginMethodType,loginStatus,userInput.inputType,userInput.email,userInput.phone,accountData.personalDetails.firstName,accountData.personalDetails.lastName,accountData.personalDetails.email,accountData.created,accountData.type,accountData.status
e520-ba9a-367-60b,1471171293,10.0.0.127,"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",HGJ7512345H3,PASSWORD,SUCCESS,EMAIL,[email protected],15557654321,John,Smith,[email protected],1415287568000,BUSINESS,CLOSEDForter requires 6 months of historical compensation request data.
Compensation request history should contain the status and total compensation amount granted for the order, as well as details on each item included in the request. Note that the fields match the data structure in the Order Status API, though you may be utilizing the Compensation Request API in your live integration.
For orders that have multiple cart items, please follow one of the patterns below.
orderId,eventTime,updatedStatus,compensationStatus.totalGrantedAmount.amountUSD,compensationStatus.totalGrantedAmount.amountLocalCurrency,compensationStatus.totalGrantedAmount.currency,compensationStatus.itemStatus[0].basicItemData.quantity,compensationStatus.itemStatus[0].basicItemData.price.amountUSD,compensationStatus.itemStatus[0].basicItemData.price.amountLocalCurrency,compensationStatus.itemStatus[0].basicItemData.price.currency,compensationStatus.itemStatus[0].basicItemData.productId,compensationStatus.itemStatus[0].basicItemData.name,compensationStatus.itemStatus[0].basicItemData.type,compensationStatus.itemStatus[0].statusData.updatedStatus,compensationStatus.itemStatus[0].statusData.compensationTypeGranted,compensationStatus.itemStatus[0].statusData.reasonCategory,compensationStatus.itemStatus[1].basicItemData.quantity,compensationStatus.itemStatus[1].basicItemData.price.amountUSD,compensationStatus.itemStatus[1].basicItemData.price.amountLocalCurrency,compensationStatus.itemStatus[1].basicItemData.price.currency,compensationStatus.itemStatus[1].basicItemData.productId,compensationStatus.itemStatus[1].basicItemData.name,compensationStatus.itemStatus[1].basicItemData.type,compensationStatus.itemStatus[1].statusData.updatedStatus,compensationStatus.itemStatus[1].statusData.compensationTypeGranted,compensationStatus.itemStatus[1].statusData.reasonCategory
2356fdse0rr489,1415287568000,SENT,120.45,134.15,CAD,1,99.95,105.55,CAD,Ag54352R7768kkO,White GenericBrand handbag,TANGIBLE,ACCEPTED_BY_MERCHANT,REFUND,WRONG_ITEM,1,99.95,105.55,CAD,Ab54352R7768kkO,Black Socks,TANGIBLE,ACCEPTED_BY_MERCHANT,REFUND,WRONG_ITEM