Merchant Risk Profile

During onboarding, Vesta generates a risk profile specific to your business which will help us identify fraudulent transactions. To generate the profile, you must send us details about your business in a JSON or CSV file as specified on this page.

It is important to provide as much information as possible. The more information you send us, the better our predictions will be. When preparing your merchant risk profile data file, keep the following guidelines in mind:

  • Redundant Data - If the data appears to be repetitious or redundant, provide the data in every field. For example, if the customer address and recipient address are the same, include the address in both fields.
  • Data Period - We request 180 days of transactional data for analysis. The number of transaction days can vary based on the total transaction volumes that you process in a given timeframe.
  • Data Availability - Your systems may not store all of the data that we request. However, we request that you include as much information as possible to improve the accuracy of your risk assessments.

Data File Specifications

We accept data files in JSON or CSV formats. JSON is our preferred format.

Name your data file as describe below:

<MerchantName>_HistoricalData_<DateTime>.JSON

Use the example below for reference:

MyCompany_HistoricalData_20200315.JSON

If you send a CSV file, the file must conform to the RFC 4180 standard and use UTF-8 encoding.

Field Definitions

The sections below define the fields to include in the data file. The data element definitions are the same for both JSON and CSV files.

RiskInformation Data Elements and Associated Details

Data Element Data Priority Format Definition
RiskInformation   Array An array of objects.
HistoricTransaction Required Object An object containing information about a past transaction.

HistoricTransaction Data Elements and Associated Details

Data Element Data Priority Format Definition
HistoricTransaction   Object An object containing information about a past transaction.
Billing Required Object An object containing billing data.
Purchaser Required Object Objects containing information about the purchaser.
Channel Required Object Objects containing information about the channel used.
ShoppingCart Required Object Objects containing information about the shopping cart, delivery, and line item contents.
TransactionDTM Required Datetime The date and time of the transactions in standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
MerchantOrderID Required String The order/transaction identification used by the merchant to track the order.
ThirdPartyData Required Object An object containing information about the third-party data that is part of the transaction.

Billing Data Elements and Associated Details

Data Element Data Priority Format Definition
Billing   Object An object containing billing data.
FirstName Desired String The cardholder’s first name.
LastName Desired String The cardholder’s last name.
AddressLine1 Required String The cardholder’s address, line 1.
AddressLine2 Optional String The cardholder’s address, line 2.
City Required String The cardholder’s city.
PostalCode Required String The cardholder’s ZIP or postal code.
Region Required String The cardholder’s region name. For U.S. addresses, use the two-character state code.
CountryCode Required String The cardholder’s two-character country code. Use the ISO-3166 official country codes.
Email Required String The cardholder’s email address.
Phone Desired String The cardholder’s phone number. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
PurchaseAmount Required Numeric The total amount of the transaction in the processed currency.
CurrencyCode Desired String The transaction currency. Use ISO 4217 alpha codes format.
CardFirst6 Required String The first six digits of the credit/debit card number processed
CardLast4 Required String The last four digits of the credit/debit card number processed
CardNumberToken Required String A token value or ID that represents the card number in a 1:1 way in the merchant system.
CVVResponseCode Desired String The card verification value response code from the payment processor.
AVSResponseCode Desired String The address verification service response code from the payment processor.
AuthResponseCode Optional String The authorization response code from the payment processor.
FirstCardOrderDTM Desired Datetime The date and time the card was first used to place an order with the merchant in standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
CardOnFile Optional Boolean A flag to indicate if the card was stored prior to the transaction in question. Possible values are TRUE or FALSE. TRUE indicates that the consumer did not enter card information for this transaction and instead used stored card information.
Outcome Required String The final decision/outcome of the order. Possible values are CompleteBank, DenyMerchant, DenyRefundPayment, or ExceptionOther.
HasChargeback Required Boolean A flag to indicate if the transaction had a chargeback.
ChargebackReasonCode Desired String If a chargeback occurred, the reason code associated with the chargeback as provided by the payment processor.
ConsumerReportedFraud Desired Boolean A flag to indicate if the consumer reported fraud. This occurs when a consumer calls the merchant to inquire about a transaction and it is determined that the transaction was fraudulent. Possible values are TRUE or FALSE.

Purchaser Data Elements and Associated Details

Data Element Data Priority Format Definition
PurchaseAmount   Object An object containing information about the purchaser.
Account Required Object An object containing information about the purchaser account with the merchant.

Account Data Elements and Associated Details

Data Element Data Priority Format Definition
Account   Object An object containing information about the purchaser account with the merchant.
AccountID Required String The account identifier used by the merchant.
CreatedDTM Optional Datetime The date and time the account was created in standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
Email Optional String The account owner’s email address.
IsEmailVerified Optional Boolean A flag to indicate if the email was verified, such as sending a code to the email that must be entered to complete account setup as part of the account creation process. Possible values are TRUE or FALSE.
Phone Optional String The account owner’s phone number. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
IsPhoneVerified Optional Boolean A flag to indicate if the phone number was verified, such as sending an SMS code that must be entered to complete account setup as part of the account creation process. Possible values are TRUE or FALSE.

Channel Data Elements and Associated Details

Data Element Data Priority Format Definition
Channel   Array An array of objects.
IPAddress Required String The IP address of the device used to place the order.
ANI Optional String The caller’s phone number used to place the order. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
MerchantChannelCode Desired String The merchant defined code for the channel the order is placed in.

ShoppingCart Data Elements and Associated Details

Data Element Data Priority Format Definition
ShoppingCart   Object An object containing the items being purchased.
NumberOfDeliveries Desired Integer The total number of distinct deliveries being made as part of the transaction. A delivery is defined by a unique set of delivery information, such as name, shipping address, email, etc.
Delivery Required Array An array of objects related to the distinct deliveries.

Delivery Data Elements and Associated Details

Data Element Data Priority Format Definition
Delivery   Array An array of objects related to the distinct deliveries.
DeliveryInfo Required Object An object containing information relating to the delivery of the related line items.
LineItems Required Object An object containing information relating to the line items of the delivery.

DeliveryInfo Data Elements and Associated Details

Data Element Data Priority Format Definition
DeliveryInfo   Object An object containing information relating to the line items of the delivery.
DeliveryMethod Desired String The method in which the consumer received the good, such as Digital, InStore, Shipped, InApp, etc.
FirstName Optional String The recipient’s first name.
LastName Optional String The recipient’s last name.
AddressLine1 Required String The recipient’s address, line 1.
AddressLine2 Optional String The recipient’s address, line 2.
City Required String The recipient’s city.
PostalCode Required String The recipient’s ZIP or postal code.
Region Required String The recipient’s region name. For U.S. addresses, use the two-character state code.
CountryCode Required String The recipient’s two-character country code. Use the ISO-3166 official country codes.
Email Required String The recipient’s email address.
Phone Optional String The recipient’s phone number. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
AccountID Optional String The account identifier of the recipient.

LineItems Data Elements and Associated Details

Data Element Data Priority Format Definition
LineItems   Object An object containing information relating to the line items of the delivery.
NumberOfLineItems Optional Integer The number of distinct line items in the delivery.

ThirdPartyData Data Elements and Associated Details

Data Element Data Priority Format Definition
ThirdPartyData   Array An array of objects.
DeviceFingerprint Desired Object A merchant-defined object containing information relating to the device fingerprinting associated with the transaction.

File Structure

The sections below provide information about the structure of the JSON or CSV file that you create.

JSON

The example below shows the structure of the JSON file:

{
	"RiskInformation": [
		{
			"HistoricTransaction": {
				"Billing": {
					"FirstName": {},
					"LastName": {},
					"AddressLine1": {},
					"AddressLine2": {},
					"City": {},
					"PostalCode": {},
					"Region": {},
					"CountryCode": {},
					"Email": {},
					"Phone": {},
					"PurchaseAmount": {},
					"CurrencyCode": {},
					"CardFirst6": {},
					"CardLast4": {},
					"CardNumberToken": {},
					"CVVResponseCode": {},
					"AVSResponseCode": {},
					"AuthResponseCode": {},
					"FirstCardOrderDTM": {},
					"CardOnFile": {},
					"Outcome": {},
					"HasChargeback": {},
					"ChargebackReasonCode": {},
					"ConsumerReportedFraud": {}
				},
				"Purchaser": {
					"Account": {
						"AccountID": {},
						"CreatedDTM": {},
						"Email": {},
						"IsEmailVerified": {},
						"Phone": {},
						"IsPhoneVerified": {}
					}
				},
				"Channel": {
					"IPAddress": {},
					"ANI ": {},
					"MerchantChannelCode": {}
				},
				"ShoppingCart": {
					"NumberOfDeliveries": {},
					"Delivery": [
						{
							"DeliveryInfo": {
								"DeliveryMethod": {},
								"FirstName": {},
								"LastName": {},
								"AddressLine1": {},
								"AddressLine2": {},
								"City": {},
								"PostalCode": {},
								"Region": {},
								"CountryCode": {},
								"Email": {},
								"Phone": {},
								"AccountID": {}
							},
							"LineItems": {
								"NumberOfLineItems": {}
							}
						}
					]
				},
				"TransactionDTM": {},
				"MerchantOrderID": {},
				"ThirdPartyData": {
					"DeviceFingerprint": {}
				}
			}
		}
	]
}

CSV

Use the column headings in the order listed below for your CSV file:

  • Billing/FirstName
  • Billing/LastName
  • Billing/AddressLine1
  • Billing/AddressLine2
  • Billing/City
  • Billing/PostalCode
  • Billing/Region
  • Billing/CountryCode
  • Billing/Email
  • Billing/Phone
  • Billing/PurchaseAmount
  • Billing/CurrencyCode
  • Billing/CardFirst6
  • Billing/CardLast4
  • Billing/CardNumberToken
  • Billing/CVVResponseCode
  • Billing/AVSResponseCode
  • Billing/AuthResponseCode
  • Billing/FirstCardOrderDTM
  • Billing/CardOnFile
  • Billing/Outcome
  • Billing/HasChargeback
  • Billing/ChargebackReasonCode
  • Billing/ConsumerReportedFraud
  • Purchaser/Account/AccountID
  • Purchaser/Account/CreatedDTM
  • Purchaser/Account/Email
  • Purchaser/Account/IsEmailVerified
  • Purchaser/Account/Phone
  • Purchaser/Account/IsPhoneVerified
  • Channel/IPAddress
  • Channel/ANI
  • Channel/MerchantChannelCode
  • ShoppingCart/NumberOfDeliveries
  • ShoppingCart/Delivery/DeliveryInfo/DeliveryMethod
  • ShoppingCart/Delivery/DeliveryInfo/FirstName
  • ShoppingCart/Delivery/DeliveryInfo/LastName
  • ShoppingCart/Delivery/DeliveryInfo/AddressLine1
  • ShoppingCart/Delivery/DeliveryInfo/AddressLine2
  • ShoppingCart/Delivery/DeliveryInfo/City
  • ShoppingCart/Delivery/DeliveryInfo/PostalCode
  • ShoppingCart/Delivery/DeliveryInfo/Region
  • ShoppingCart/Delivery/DeliveryInfo/CountryCode
  • ShoppingCart/Delivery/DeliveryInfo/Email
  • ShoppingCart/Delivery/DeliveryInfo/Phone
  • ShoppingCart/Delivery/DeliveryInfo/AccountID
  • ShoppingCart/Delivery/LineItems/NumberOfLineItems
  • TransactionDTM
  • MerchantOrderID
  • ThirdPartyData/DeviceFingerprint