Risk Information XML

This page defines the elements of the Risk Information XML.

Include as much information as possible in the Risk Information XML to obtain the best results from Vesta’s services.

Use the Risk Information XML to send transaction details to Vesta. Vesta uses the details that you provide in the XML to make an accurate assessment of the risk associated with the transaction. You must send the Risk Information XML in the body of all requests to the ChargePaymentFraudRequest, ChargePaymentRequest, CheckPaymentRequest, CheckPaymentFraudRequest, and ValidateAccountNumber endpoints, regardless of the Vesta service that you use. Send the XML as a string value for the RiskInformation field as shown in the API documentation.

The Risk Information XML includes elements for sending details about many different types of services that your business may or may not offer. You should send the elements that are relevant to your business. The definitions below indicate the type of business that would typically use the element.

Click here to download a zip file containing specifications and examples of the Risk Information XML.

The zip file linked above contains the following three files:

  • StandardRiskInfo2.2.sample.web.xml - An example of a complete Risk Information XML file.
  • StandardRiskInfo2.2.xsd - The XML schema definitions for the Risk Information XML file.
  • RiskInformationXML.xlsx - An Excel spreadsheet that contains a filterable list of elements and their definitions.

RiskInformation Element

The RiskInformation element is the root element of the Risk Information XML file. The RiskInformation element is required and should include a version attribute as shown in the example below:

<RiskInformation version="2.2">

The RiskInformation element must include a Transaction element as its content.

Transaction Element

The Transaction element is the only child element of the RiskInformation element. The Transaction element is the parent element for all of the transaction information that Vesta will use to analyze the risk of the transaction. The table below defines the child elements of the Transaction element:

Element Name Description
Purchaser Contains elements relating to information about the purchaser placing the transaction.
Channel Contains elements relating to detailed information about the type of medium that the customer used for the transaction.
Promotion Contains elements relating to discounts applied to the entire order.
Billing Contains elements relating to the billing aspects for the transaction.
ShoppingCart Contains a group of Delivery elements for a transaction.
TimeStamp An element that defines the date and time of the order.
MerchantOrderID An element that specifies the merchant’s unique identifier for the order.
CustomMerchantData Contains elements relating to detailed information specific to the merchant.
Device Contains elements specific to the device.
Installment Contains elements specific to installment payments.

Each of these elements may contain zero, one, or several child elements, which are defined in the sections below.

Purchaser Element

The Purchaser element provides information about the purchaser placing the transaction. The contents of the Purchaser element include a single child element: Account.

Account Element

The Account element provides information about the purchaser’s account if an account exists with the merchant. The table below defines the contents of the Account element:

Element Name Data Type Required For Description
AccountID String User Account With Merchant The merchant-defined account identifier for the purchaser.
CreatedDTM Datetime User Account With Merchant The date and time the purchaser account was created by the merchant. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
DOB Date User Account With Merchant The date of birth of the purchaser. Use Standard ISO 8601 date format: YYYY-MM-DD.
isEmailVerified Boolean + NULL User Account With Merchant Indicates if the email address for the purchaser has been verified, such as sending a confirmation code to the email:
* FALSE - A verification was attempted and failed.
* TRUE - A verification was attempted and successful.
* NULL or empty - A verification was not attempted.
isPhoneVerified Boolean + NULL User Account With Merchant Indicates if the phone number for the purchaser’s account with the merchant has been verified, such as sending a confirmation code to the number:
* FALSE - A verification was attempted and failed.
* TRUE - A verification was attempted and successful.
* NULL or empty - A verification was not attempted.
Email String User Account With Merchant The email address attached to the purchaser’s account.
CompanyName String User Account With Merchant The name of the company on the purchaser’s account with the merchant.
FirstName String User Account With Merchant The first (given) name for the purchaser.
LastName String User Account With Merchant The last (surname) name for the purchaser.
AddressLine1 String User Account With Merchant The first line in the address for the purchaser.
AddressLine2 String User Account With Merchant The second line in the address for the purchaser.
UnitNumber String User Account With Merchant For non-U.S. addresses, the unit number in the address for the purchaser.
BuildingNumber String User Account With Merchant For non-U.S. addresses, the building number in the address for the purchaser.
StreetOrBlock String User Account With Merchant For non-U.S. addresses, the street or block in the address for the purchaser.
Neighborhood String User Account With Merchant For non-U.S. addresses, the neighborhood name in the address for the purchaser.
City String User Account With Merchant The city in the address for the purchaser’s account with the merchant.
Region String User Account With Merchant For U.S. addresses, the two-state character code in the address for the purchaser. For non-U.S. addresses, the name of the region.
PostalCode String User Account With Merchant The local postal (ZIP) code in the address for the purchaser.
CountryCode String User Account With Merchant The country in the address for the purchaser. Use two-character alpha ISO 3166-1 codes.
CurrentBalance Currency User Account With Merchant The current balance on the purchaser’s account with the merchant, if the account is used to store value.
PhoneNumber String User Account With Merchant The phone number attached to the purchaser’s account. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
SocialNetwork Parent Element User Account With Merchant The SocialNetwork element provides information about any social networks that have been linked to the purchaser account on the merchant’s system.
See the SocialNetwork Element section for details.
isAddressValidated Boolean + NULL User Account With Merchant Indicates if the merchant performed a validation of the purchaser’s physical address. Validations include checking the address format to ensure it conforms to local requirements or querying a third-party service for address deliverability, such as the United States Post Office:
* FALSE - A verification was attempted and failed.
* TRUE - A verification was attempted and successful.
* NULL or empty - A verification was not attempted.
Gambling Parent Element User Account With Merchant The Gambling element provides betting information for the purchaser account on the merchant’s system. See the Gambling Element section for details.

SocialNetwork Element

The SocialNetwork element provides information about any social networks that have been linked to the purchaser account on the merchant’s system. The table below defines the contents of the SocialNetwork element:

Element Name Data Type Required For Description
Email String User Account With Merchant The email address on the social network of reference.
AccountID String User Account With Merchant The account identifier on the social network of reference.
Platform String User Account With Merchant The name of the social network of reference: Facebook, GooglePlus, Twitter, Instagram, YouTube, Qzone, Weibo, Reddit, Pinterest, LinkedIn, or Other.
Contact your Integration Specialist for other social networks that may be used.

Gambling Element

The Gambling element provides betting information for the purchaser account on the merchant’s system. The table below defines the contents of the Gambling element:

Element Name Data Type Required For Description
MaxBetAmount Currency Gambling The maximum amount used for betting.
MinBetAmount Currency Gambling The minimum amount used for betting.
AverageBetAmount Currency Gambling The average bet amount.
TotalNumberOfBets Integer Gambling The total number of bets placed.
TotalNumberOfWins Integer Gambling The total number of wins from betting.
FirstBetDate Date Gambling The date the first bet was placed. Use Standard ISO 8601 date format: YYYY-MM-DD.
LastBetDate Date Gambling The date the last bet was placed. Use Standard ISO 8601 date format: YYYY-MM-DD.
TotalWinAmount Currency Gambling The total amount won from betting.
TotalLossAmount Currency Gambling The total amount lost from betting.

Channel Element

The Channel element provides detailed information about the type of medium that the customer used for the transaction. The table below defines the contents of the Channel element:

Element Name Data Type Required For Description
ANI String IVR/CSR Channel The IVR/CSR ANI for the transaction. This field is required for any transaction that is phoned in. Use a zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
IPAddress String WEB/Device Channel The IP address of the device placing the transaction (for a channel that uses devices). Format: IPv4 or IPv6.
MerchantChannelCode String All The merchant-defined channel code (used for reporting).
MerchantChannelDescription String All A description of the merchant-defined channel code. Limited to 50 characters.
MerchantSubChannelCode String All The merchant-defined sub-channel code (used for reporting).
VestaChannelCode String All A platform-defined channel code. Use one of the following values: WEB, IVR, MOBILE, MRC, CSR, or OTHER. Consult your Integration Specialist for assistance in determining the value to be used.

Promotion Element

The Promotion element defines discounts that are applied to the entire order. Discounts for individual line items are set in the LineItem element, which is a child element of the ShoppingCart element.

The table below defines the contents of the Promotion element:

Element Name Data Type Required For Description
Discount Currency All The amount of the discount.
Description String All A description of the discount. Limited to 50 characters.
Code String All The code that represents the discount.

Billing Element

The Billing element contains billing aspects for the transaction. This information is tied directly to the billing process and may be different than the account information.

The table below defines the contents of the Billing element:

Element Name Data Type Required For Description
PaymentDeviceToken String All The payment token from the payment processor used by the merchant account.
BillingPhoneNumber String All The phone number for billing provided in the order flow. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
Email String All The email address for billing provided in the order flow.
PaymentDetails Element Parent Element All The PaymentDetails element provides additional details about the card number. See the PaymentDetails Element section for details.
GovernmentID Element Parent Element All The GovernmentID element provides information about the identification method used to verify the purchaser during the transaction. See the GovernmentID Element section for details.

PaymentDetails Element

The PaymentDetails element provides additional details about the card number. The table below defines the contents of the PaymentDetails element:

Element Name Data Type Required For Description
isPDOF Boolean + NULL All Indicates if the payment method details are stored by the merchant, such as storing a credit card as a permanent token in a digital wallet:
* FALSE - The payment method details are NOT stored by the merchant; however, it is an option.
* TRUE - The payment method details are stored, and the merchant does NOT have to re-enter it the next time a purchase is made.
* NULL or empty - The merchant does not offer the storing of payment method details as a feature.
CardStoredDTM Datetime All The date and time a stored card was created. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.

GovernmentID Element

The GovernmentID element provides information about the identification method used to verify the purchaser during the transaction. The table below defines the contents of the GovernmentID element:

Element Name Data Type Required For Description
CollectedType String All Indicates how the government ID was obtained: ManualEntry, ImageCapture, or Import.
IDType String All The type of government ID collected: PassportNumber, SSN, StateID, IFE, INE, or TaxIdentificationNumber.
IDNumber String All The unique number on the government ID.

ShoppingCart Element

The ShoppingCart element contains a group of Delivery elements, which specify the details of an order or invoice. The ShoppingCart element requires a DeliveryCount attribute that specifies the number of Delivery child elements, as shown in the example below:

<ShoppingCart DeliveryCount="1">

The sections below define the Delivery element and its child elements: DeliveryInfo, LineItem, BillPay, and Wallet.

Delivery Element

The Delivery element contains a group of elements with detailed information for a shopping cart item that will be shipped to a single physical or virtual location. The Delivery element requires an LineItemCount attribute that defines the number of line items in the delivery, as shown in the example below:

<Delivery LineItemCount="1">

The contents of the Delivery element include the following child elements, which are defined in the sections below: DeliveryInfo, LineItem, BillPay, and Wallet.

DeliveryInfo Element

The DeliveryInfo element contains detailed shipping information for the item being delivered. The table below defines the contents of the DeliveryInfo element:

Element Name Data Type Required For Description
DeliveryMethod String All The way the delivery will take place. Use one of the following values: Print, WillCall, Delay, Email, PhysicalShipping, Reload, DigitalDownload, MoneyTransfer, BillPay, Subscription, TelcoTopup, WalletReload, WalletAdd, SMS, or Other. Contact your Integration Specialist for assistance in determining the value to use.
ShippingCarrier String Physical Goods, Physical Shipping The name of the shipping carrier, if it applies: UPS, FedEx, USPS, DHL, CanadaPost, Purolator, OnTrac, or Estafeta. Contact your Integration Specialist for assistance in determining the value to use.
TargetShipDate Date Physical Shipping The estimated shipping date for physical shipping goods or the planned delivery date for delayed digital fulfillment. Use Standard ISO 8601 date format: YYYY-MM-DD.
ShippingClass String Physical Shipping The class of shipping: Overnight, Priority, FirstClass, ParcelPost, or Express. Contact your Integration Specialist for assistance in determining the value to use.
ShippingCost Currency Physical Shipping The cost of shipping the delivery.
PickupLocation String In Store Pickup The pickup location, if there will be a pickup at a known location, such as a store. In the case of a store pickup, this would be a store identifier, either an address or a store number.
PickupDeliveryTime Datetime In Store Pickup The estimated or requested date and time of the pickup. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
Company String All The name of the company the delivery is intended for.
FirstName String All The first (given) name for the recipient of the delivery.
LastName String All The last (surname) name for the recipient of the delivery.
AddressLine1 String Physical Shipping The first line in the address for the delivery.
AddressLine2 String Physical Shipping The second line in the address for the delivery.
UnitNumber String Physical Shipping For non-U.S. addresses, the unit number in the address for the delivery.
BuildingNumber String Physical Shipping For non-U.S. addresses, the building number in the address for the delivery.
StreetOrBlock String Physical Shipping For non-U.S. addresses, the street or block in the address for the delivery.
Neighborhood String Physical Shipping For non-U.S. addresses, the neighborhood name in the address for the delivery.
City String Physical Shipping The city in the address for the delivery.
Region String Physical Shipping For U.S. addresses, the two-state character code in the address for the delivery. For non-U.S. addresses, the name of the region.
PostalCode String Physical Shipping The local postal (ZIP) code in the address for the delivery.
CountryCode String Physical Shipping The country in the address for the delivery. Use two-character alpha ISO 3166-1 codes.
PhoneNumber String All, Telco The phone number for the delivery recipient. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
Email String All, Email Delivery The email address for the delivery recipient.
SubscriberKey String Telco The subscriber key for the delivery recipient. Used for merchants that have a sub-account that stores the value of the transaction.
AccountID String Telco The account identifier for the delivery recipient. Used when the delivery goes to an account either with the merchant or a third party.
isAddressValidated Boolean + NULL Physical Shipping Indicates if the merchant performed a validation of the purchaser’s physical address. Validations include checking the address format to ensure it conforms to local requirements or querying a third-party service for address deliverability, such as the United States Post Office. Use one of the following values:
* FALSE - A validation was attempted and failed.
* TRUE - A validation was attempted and successful.
* NULL or empty - A validation was not attempted.
isEmailValidated Boolean + NULL All, Email Delivery Indicates if the merchant performs a validation of the email address associated with delivery. Validations include checking the address format to ensure it conforms to email standards or querying the domain (such as Google) to check if the email address is deliverable. Use one of the following values:
* FALSE - A validation was attempted and failed.
* TRUE - A validation was attempted and successful.
* NULL or empty - A validation was not attempted.

LineItem Element

The LineItem element contains detailed product, promotion, and seller information for the item. The table below defines the contents of the LineItem element:

Element Name Data Type Required For Description
ProductCode String All The merchant-maintained product code for the product/service.
ProductDescription String All The merchant-defined product description. Description length not to exceed 120 characters including spaces and special characters.
Quantity Integer All The line item quantity.
UnitPrice Currency All The unit price for the line item.
DiverseCart Element Parent Element All The DiverseCart element provides important details about the contents of the shopping cart. This element is used by the merchants who have diverse product or service offerings. See the DiverseCart Element section for more information. Consult your Integration Specialist for details.
Promotion Element Parent Element All The Promotion element provides information about the discounts applied to the line item only – not the whole transaction. See the Promotion Element section for details.
GiftCards Element Parent Element Gift Cards The GiftCards element provides details specific to merchants who sell gift cards. See the GiftCards Element section for details.
TravelRoute Element Parent Element Travel Ticket The TravelRoute element provides details specific to merchants who sell tickets for travel on airplanes. See the TravelRoute Element section for details.
Seller Element Parent Element Marketplace The Seller element provides details for merchants sell items that are hosted by third parties or that use third-party individuals or organizations to fulfill orders, such as eBay. See the Seller Element section for details.
CrossBorderFulfillment Element Parent Element Cross Border Fulfillment The CrossBorderFulfillment element provides details necessary for when fulfillment occurs across a border and defines the currency transitions that are part of that transaction. See the CrossBorderFulfillment Element section for details.
Insurance Element Parent Element Insurance The Insurance element provides information about insurance policies. See the Insurance Element section for details.
Event Element Parent Element Event Ticket The Event element provides information for event ticketing. See the Event Element section for details.
DiverseCart Element

The DiverseCart element provides important details about the contents of the shopping cart. This element is used by merchants who have diverse product or service offerings. The table below defines the contents of the DiverseCart element:

Element Name Data Type Required For Description
SKU String All The merchant-maintained SKU, if applicable.
ProductType String All The product type for the line item. Consult your Integration Specialist for details.
Category String All The product category for the line item. Consult your Integration Specialist for details.
SubCategory String All The sub-category for the line item. Consult your Integration Specialist for details.
Brand String All The brand name of the product, such as Calvin Klein.
Promotion Element

The Promotion element provides information about the discounts applied to the line item only – not the whole transaction. The table below defines the contents of the Promotion element:

Element Name Data Type Required For Description
Discount Currency All The amount of the discount for a specific line item.
Code String All The code that represents the discount for a specific line item.
Description String All A short description of the discount for a specific line item.
GiftCards Element

The GiftCards element provides details specific to gift card merchants who sell gift cards. The table below defines the contents of the GiftCards element:

Element Name Data Type Required For Description
From String Gift Cards The value of the “From” field that identifies the person giving the gift card.
Text String Gift Cards Contents of the message in the gift card. Limited to 120 characters (includes spaces and special characters).
To String Gift Cards The value from the “To” field that identifies the person receiving the gift card.
TravelRoute Element

The TravelRoute element provides details specific to travel ticket merchants. The table below defines the contents of the TravelRoute element:

Element Name Data Type Required For Description
Carrier String Travel Ticket The name of the travel carrier: American Airlines, Greyhound, Southwest, or ABO.
DepartureDTM String Travel Ticket The date and time of the trip’s departure. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
ArrivalDTM String Travel Ticket The date and time of the trip’s arrival. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
Destination String Travel Ticket The airport where the travel route ended. Use industry standard abbreviations for standard locations, such as the airport code of LAX for Los Angeles International Airport. Contact your Integration Specialist for assistance in determining the value to use.
FareClass String Travel Ticket The fare class for the ticket(s).
Origin String Travel Ticket The airport where the travel route started. Use industry standard abbreviations for standard locations, such as the airport code of LAX for Los Angeles International Airport. Contact your Integration Specialist for assistance in determining the value to use.
Traveler Element Parent Element Travel Ticket The Traveler element provides the first and last names of the person who is using the ticket to travel. The number of traveler elements should match the quantity specified by the lineItem element. See the Traveler Element section for details.
Traveler Element

The Traveler element provides the first and last name of the person associated with the ticket. The table below defines the contents of the Traveler element:

Name Data Type Required For Description
FirstName String Travel Ticket The first (given) name for the traveler.
LastName String Travel Ticket The last (surname) name for the traveler.
Seller Element

The Seller element provides details for merchants who sell items that are hosted by third parties or who use third-parties to fulfill orders, such as eBay. The table below defines the contents of the Seller element:

Element Name Data Type Required For Description
NumberPriorSales Integer Marketplace The number of competed sales by the seller prior to this transaction.
ItemCreatedDate Date Marketplace The date the line item was created for sale on the merchant’s marketplace. Use Standard ISO 8601 date format: YYYY-MM-DD.
Account Element Parent Element Marketplace The Account element provides information about the seller’s account hosted by the merchant. See the Account Element section for details.
Account Element

The Account element provides information about the seller’s account hosted by the merchant. The table below defines the contents of the Account element:

Element Name Data Type Required For Description
AccountID String Marketplace The merchant account identifier of the seller.
CreatedDTM Datetime Marketplace The date and time the seller account was created by the merchant. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
DOB Date Marketplace The date of birth of the seller. Use Standard ISO 8601 date format: YYYY-MM-DD.
isEmailVerified Boolean + NULL Marketplace Indicates if the email address for the seller has been verified, such as sending a confirmation code to the email:
* FALSE - A verification was attempted and failed.
* TRUE - A verification was attempted and successful.
* NULL or empty - A verification was not attempted.
Email String Marketplace The email address attached to the seller’s account.
CompanyName String Marketplace The name of the company on the seller’s account with the merchant.
FirstName String Marketplace The first (given) name for the seller.
LastName String Marketplace The last (surname) name for the seller.
AddressLine1 String Marketplace The first line in the address for the seller.
AddressLine2 String Marketplace The second line in the address for the seller.
UnitNumber String Marketplace For non-U.S. addresses, the unit number in the address for the seller.
BuildingNumber String Marketplace For non-U.S. addresses, the building number in the address for the seller.
StreetOrBlock String Marketplace For non-U.S. addresses, the street or block in the address for the seller.
Neighborhood String Marketplace For non-U.S. addresses, the neighborhood name in the address for the seller.
City String Marketplace The city in the address for the seller.
Region String Marketplace For U.S. addresses, the two-state character code in the address for the seller. For non-U.S. addresses, the name of the region.
PostalCode String Marketplace The local postal (ZIP) code in the address for the seller.
CountryCode String Marketplace The country in the address for the seller. Use two-character alpha ISO 3166-1 codes.
isAddressValidated Boolean + NULL Marketplace Indicates if the merchant performed a validation of the seller’s physical address. Validations include checking the address format to ensure it conforms to local requirements or querying a third-party service for address deliverability, such as the United States Post Office:
* FALSE - A validation was attempted and failed.
* TRUE - A validation was attempted and successful.
* NULL or empty - A validation was not attempted.
CurrentBalance Currency Marketplace The current balance on the seller’s account with the merchant, if the account is storing funds.
PhoneNumber String Marketplace The phone number attached to the seller’s account. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
isPhoneVerified Boolean + NULL Marketplace Indicates if the phone number for the seller has been verified, such as sending a confirmation code to the number:
* FALSE - A verification was attempted and failed.
* TRUE - A verification was attempted and successful.
* NULL or empty - A verification was not attempted.
SocialNetwork Element Parent Element Marketplace The SocialNetwork element provides information about any social networks that have been linked to the seller’s account on the merchant’s system. See the SocialNetwork Element section for details.
SocialNetwork Element

The SocialNetwork element provides information about any social networks that have been linked to the seller’s account on the merchant’s system. The table below defines the contents of the SocialNetwork element:

Element Name Data Type Required For Description
Email String Marketplace The email address on the social network of reference.
AccountID String Marketplace The account identifier on the social network of reference.
Platform String Marketplace The name of the social network of reference. Contact your Integration Specialist for additional social networks that may be used: Facebook, GooglePlus, Twitter, Instagram, YouTube, Qzone, Weibo, Reddit, Pinterest, LinkedIn, or Other.
CrossBorderFulfillment Element

The CrossBorderFulfillment element provides details that are important when fulfillment occurs across a border, such as the currency conversions that are required. The table below defines the contents of the CrossBorderFulfillment element:

Element Name Data Type Required For Description
ExchangeRate Float Cross Border Fulfillment, Money Transmission The exchange rate at transaction time between the sending and receiving currencies.
ReceiveAmount Currency Cross Border Fulfillment, Money Transmission The amount received from the transfer.
ReceiveCurrency String Cross Border Fulfillment, Money Transmission The type of currency received. Use ISO 4217 alpha codes format.
SendAmount Currency Cross Border Fulfillment, Money Transmission The amount sent in the transfer.
SendCurrency String Cross Border Fulfillment, Money Transmission The type of currency sent. Use ISO 4217 alpha codes format.
Payout Element Parent Element Cross Border Fulfillment, Money Transmission The Payout element provides information about where the cross-border fulfillment occurs, either through money transmission or some type of stored value, such as a Telco top-up. See the Payout Element section for details.
Payout Element

The Payout element provides information about where the cross-border fulfillment occurs, either through money transmission or some type of stored value, such as a Telco top-up. The table below defines the contents of the Payout element:

Element Name Data Type Required For Description
City String Cross Border Fulfillment, Money Transmission The city in the address for the payout.
CountryCode String Cross Border Fulfillment, Money Transmission The country in the address where the payout occurs. Use two-character alpha ISO 3166-1 codes.
PostalCode String Cross Border Fulfillment, Money Transmission The local postal (ZIP) code in the address where the payout occurs.
Region String Cross Border Fulfillment, Money Transmission For U.S. addresses, the two-state character code where the payout occurs. For non-U.S. addresses, the name of the region.
Network String Cross Border Fulfillment, Money Transmission The payout network used for the money transmission.
Insurance Element

The Insurance element provides information about the insurance policy that is being sold or paid for. The table below defines the contents of the Insurance element:

Element Name Data Type Required For Description
Type String Insurance The type of insurance policy: Home or Auto.
PolicyNumber String Insurance The identification number for the insurance policy.
PolicyHolderFirstName String Insurance The first (given) name for the insurance policy holder.
PolicyHolderLastName String Insurance The last (surname) name for the insurance policy holder.
PolicyHolderAddress String Insurance The address for the insurance policy holder.
Carrier String Insurance The name of the insurance carrier.
InvoiceID String Insurance The identification number of the invoice for the insurance policy.
Term String Insurance The term length for the insurance policy.
Premium Decimal Insurance The amount the policy holder pays for the insurance policy.
Event Element

The Event element provides information for merchants who sell tickets to events such as concert or sports events. The table below defines the contents of the Event element:

Element Name Data Type Required For Description
Location String Event Ticket The location (address) for the event.
EventType String Event Ticket The event type: Recurring, OneTime, or MultiDay. Consult your Integration Specialist for details.
EventCategory String Event Ticket The event category: MusicPerformance, Festival, Theatre, ArtExhibit. Consult your Integration Specialist for details.
EventDescription String Event Ticket A description of the event. Limited to 120 characters (includes spaces and special characters).
StartDate Date Event Ticket The start date for the specific event purchased. Use Standard ISO 8601 date format: YYYY-MM-DD.
NumberOfOccurences String Event Ticket The number of times that the event will happen.
CreatedDate Date Event Ticket The date the event was created in the merchant’s system. Use Standard ISO 8601 date format: YYYY-MM-DD.

BillPay Element

The BillPay element contains detailed payment information for the service provider and recipient. The table below defines the contents of the BillPay element:

Element Name Data Type Required For Description
ServiceProvider Element Parent Element Bill Pay The ServiceProvider element provides information about the company receiving payment for a service. See the ServiceProvider Element section for details.
ServiceRecipient Element Parent Element Bill Pay The ServiceRecipient element provides information about the recipient of the serive. See the ServiceRecipient Element section for details.
ServiceProvider Element

The ServiceProvider element provides information about the company receiving payment for a servie. The table below defines the contents of the ServiceProvider element:

Element Name Data Type Required For Description
BillType String Bill Pay The type of service billed by the service provider company: Utility_Water, Utility_Electricity, Utility_Gas, Utility_Waste, Utility_Sewage, Communication_Internet, Communication_TV, Communication_MobilePhone, Communication_HomePhone, Communication_Entertainment, Housing_Rent, Housing_Mortgage, Tickets_TollRoads, Tickets_Bus, Tickets_Rental, Government, or Other.
CompanyName String Bill Pay The name of the service provider company.
AddressLine1 String Bill Pay The first line in the address for the service provider company.
AddressLine2 String Bill Pay The second line in the address for the service provider company.
UnitNumber String Bill Pay For non-U.S. addresses, the unit number in the address for the service provider company.
BuildingNumber String Bill Pay For non-U.S. addresses, the building number in the address for the service provider company.
StreetOrBlock String Bill Pay For non-U.S. addresses, the street or block in the address for the service provider company.
Neighborhood String Bill Pay For non-U.S. addresses, the neighborhood name in the address for the service provider company.
City String Bill Pay The city in the address for the service provider company.
Region String Bill Pay For U.S. addresses, the two-state character code in the address for the service provider company. For non-U.S. addresses, the name of the region.
PostalCode String Bill Pay The local postal (ZIP) code in the address for the service provider company.
CountryCode String Bill Pay The country in the address for the service provider company. Use two-character alpha ISO 3166-1 codes.
PhoneNumber String Bill Pay The phone number for the service provider company. Use zero-padded, 15-digit string without spaces or non-digit characters and include the country code (modified E.163 format).
InvoiceID String Bill Pay The identification number of the invoice issued by the service provider company.
ServiceRecipient Element

The ServiceRecipient element provides information about the recipient of the service. The table below defines the contents of the ServiceRecipient element:

Element Name Data Type Required For Description
FirstName String Bill Pay The first (given) name for the recipient of the service.
LastName String Bill Pay The last (surname) name for the recipient of the service.
AddressLine1 String Bill Pay The first line in the address for the recipient of the service.
AddressLine2 String Bill Pay The second line in the address for the recipient of the service.
UnitNumber String Bill Pay For non-U.S. addresses, the unit number in the address for the recipient of the service.
BuildingNumber String Bill Pay For non-U.S. addresses, the building number in the address for the recipient of the service.
StreetOrBlock String Bill Pay For non-U.S. addresses, the street or block in the address for the recipient of the service.
Neighborhood String Bill Pay For non-U.S. addresses, the neighborhood name in the address for the recipient of the service.
City String Bill Pay The city in the address for the recipient of the service.
Region String Bill Pay For U.S. addresses, the two-state character code in the address for the recipient of the service. For non-U.S. addresses, the name of the region.
PostalCode String Bill Pay The local postal (ZIP) code in the address for the recipient of the service.
CountryCode String Bill Pay The country in the address for the recipient of the service. Use two-character alpha ISO 3166-1 codes.
Account Element Parent Element Bill Pay The Account element provides information about the service recipient’s account paying the bill to the service provider company. See the Account Element section for details.
Account Element

The Account element provides information about the service recipient’s account paying the bill to the service provider company. The table below defines the contents of the Account element:

Element Name Data Type Required For Description
OutstandingBalance Currency Bill Pay The outstanding balance amount in the service recipient’s account.
IsInGoodStanding Boolean + NULL Bill Pay Indicates if the service recipient’s account is in good standing.
* FALSE - The account is not in good standing.
* TRUE - The account is in good standing.
* NULL or empty value - Nothing is returned.
LastPaidDate Date Bill Pay The date the last bill was paid by the service recipient. Use Standard ISO 8601 date format: YYYY-MM-DD.
AgeDays Integer Bill Pay The length of time the service recipient’s account has existed.

Wallet Element

The Wallet element contains detailed information about a digital wallet. That table below defines the contents of the Wallet element:

Element Name Data Type Required For Description
WalletID String Wallet The unique identifier for the wallet.
WalletCreatedDTM Date Wallet The date and time the wallet was created. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
FirstCashAddDTM Date Wallet The date and time the first cash amount was added to the wallet. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
LastCashAddDTM Date Wallet The date and time the last cash amount was added to the wallet. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
NumberOfCashAdds Integer Wallet The number of times cash was added to the wallet.
TotalCashAmountAdded Currency Wallet The total amount of cash added to the wallet.
MaximumCashAmountAdded Currency Wallet The maximum amount of cash added to the wallet.
FirstCashAddLocation String Wallet The location the first cash amount was added.
LastCashAddLocation String Wallet The location the last cash amount was added.
NumberOfCardAdds Integer Wallet The number of times cards were added to the wallet.
TotalAmountAddedByCard Currency Wallet The total amount added by card to the wallet.
AmountLastAdded Currency Wallet The amount last added to the wallet.
LastAddDTM Date Wallet The most recent date and time an amount was last added to the wallet. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
CurrentBalanceAmount Currency Wallet The current balance amount of the wallet.
MaximumBalanceAmount Currency Wallet The maximum balance amount the wallet has had at any time.
NumberOfPayments Integer Wallet The number of payments made.
FirstPaymentDTM Date Wallet The date and time the first payment was made. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
FirstPaymentAmount Currency Wallet The amount of the first payment.
LastPaymentDTM Date Wallet The date and time of the last payment. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
LastPaymentAmount Currency Wallet The amount of the last payment.
FirstACHAddDTM Date Wallet The date and time the first amount was added to the wallet using an ACH transaction. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
LastACHAddDTM Date Wallet The date and time the last amount was added to the wallet using an ACH transaction. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.
NumberOfACHAdds Integer Wallet The number of times an amount was added to the wallet using an ACH transaction.
TotalACHAmountAdded Currency Wallet The total amount added by an ACH transactionto the wallet.
MaximumACHAmountAdded Currency Wallet The maximum amount added to the wallet using an ACH transaction.
FirstACHAddLocation String Wallet The location where the first amount was added using an ACH transaction. If online, the location is Web.
LastACHAddLocation String Wallet The location where the last amount was added using an ACH transaction. If online, the location is Web.

TimeStamp Element

The TimeStamp element contains the date and time of the order. The table below defines the contents of the TimeStamp element:

Element Name Data Type Required For Description
TimeStamp Datetime All The date and time the order was created in the merchant’s time zone. Use Standard ISO 8601 date and time format (including time zone offset): YYYY-MM-DDThh:mm:ssTZD.

MerchantOrderID Element

The MerchantOrderID element contains the merchant’s unique identifier for the order. The table below defines the contents of the MerchantOrderID element:

Element Name Data Type Required For Description
MerchantOrderID String All The internal merchant unique order identifier.

CustomMerchantData Element

The CustomMerchantData element contains detailed information specific to a merchant. Your Integration Specialist provides custom documentation outlining the additional XML required for this element if any unique information is required.

Device Element

Element Name Data Type Required For Description
Type String Device Purchaser’s device type, e.g., Phone, Tablet, etc.
IMEI String Device Device IMEI number
HardwareTouchSupport String Device Identifies whether the hardware supports touch features.
MaxTouchPoints String Device The maximum number of touch points supported by the device.
CPUArchitecture String Device The architecture of the device’s CPU.
LanguageSet String Device The language in use on the device.
OperatingSystem String Device The device’s operating system.
ScreenResolution String Device The screen resolution of the device.
TimezoneOffset Datetime Device The time zone set on the device.
UserAgent String Device The browser and version in use on the device.

Installment Element

Element Name Data Type Required For Description
TotalInstallmentAmount Currency Installment The total amount of the installment plan.
TotalPaybackAmount Currency Installment The total amount to be paid back.
NumberPayments Integer Installment The total number of installment payments.
PaymentIntervalWords String Installment The time between installment payments.
PaymentNumber Integer Installment The number of installment payments.
CustomMerchantData String Installment Information specific to the merchant.