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.
NumberOfLineItems	Optional	Integer	The number of distinct line items in the delivery.
LineItem	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
LineItem		Array	An array of objects containing information relating to the line items of the delivery.
ProductCode	Optional	String	A merchant defined code for the line item product.
ProductDescription	Optional	String	A human readable description of the line item product.
UnitPrice	Optional	Currency	The consumer cost for the line item product,
Quantity	Optional	Integer	The quantity of the line item product in the transaction.

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": [
						{
							"NumberOfLineItems": {},
							"DeliveryInfo": {
								"DeliveryMethod": {},
								"FirstName": {},
								"LastName": {},
								"AddressLine1": {},
								"AddressLine2": {},
								"City": {},
								"PostalCode": {},
								"Region": {},
								"CountryCode": {},
								"Email": {},
								"Phone": {},
								"AccountID": {}
							},
							"LineItem": [
								{
									"ProductCode": {},
									"ProductDescription": {},
									"UnitPrice": {},
									"Quantity": {}
								}
							]
						}
					]
				},
				"TransactionDTM": {},
				"MerchantOrderID": {},
				"ThirdPartyData": {
					"DeviceFingerprint": {}
				}
			}
		}
	]
}

CSV

CSV format uses column names for each of the data elements. The data elements use the same definition as the JSON format.

When submitting the CSV file, use the following column names:

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/NumberOfLineItems
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/LineItem/ProductCode
ShoppingCart/Delivery/LineItem/ProductDescription
ShoppingCart/Delivery/LineItem/UnitPrice
ShoppingCart/Delivery/LineItem/Quantity
TransactionDTM
MerchantOrderID
ThirdPartyData/DeviceFingerprint