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.
Visit the Downloads page to download examples and specifications for the Risk Information XML file.
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. |
| Merchant | Contains elements specific to the merchant. |
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. |
| 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 |
|---|---|---|---|
| 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). |
| 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. |
| CardStoredDateTime | 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. |
| PaymentName | The name of the payment instrument. | ||
| PaymentType | The category of the payment. |
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). |
| 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. |
| 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. |
| 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 |
|---|---|---|---|
| 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. |
| 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. |
Merchant Element
| Element Name | Data Type | Required For | Description |
|---|---|---|---|
| MerchantID | String | Merchant | A unique alphanumeric identifier for the merchant on the parent system. |
| MCCCode | Integer | Merchant | Industry standard codes for the merchant. |
| MerchantName | String | Merchant | The merchant’s name. |
| MerchantCountryCode | String | Merchant | The country code for the location of the merchant. Use two-character alpha ISO 3166-1 codes. |