Developer API Reference

Base Transaction Data Elements

The following Base Transaction data elements are required in all transactions (unless noted), regardless of transaction class.

Note: While the Base Transaction data elements are required, the application cannot send a transaction containing only Base Transaction data elements. Service class specific transaction data is required to successfully process any Bankcard, Electronic Checking and/or Stored Value transaction. Please refer to Bankcard Transaction Data Elements for all Bankcard specific data elements.

Activation

Contains information for activating an account. This is a required element.

Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addendum. Object

Addendum

The Addendum object is used to pass optional service specific information. This object is not required unless specifically directed to do so by your EVO Snap* Support team.

Required Parameter Description Data Type
Optional Unmanaged Unmanaged addenda. Object

AddressInfo

Contains address information for either the merchant or customer. This element is Optional.

Required Parameter Description Data Type
X City City. String
X CountryCode Country Code – Maps to the TypeISOCountryCodeA3 enumeration. Enum
X PostalCode Postal or ZIP Code. String
Optional StateProvince State or Province. String
X Street1 Street Address Line 1. String
X Street2 Street Address Line 2. String

Adjust

Contains information for adjusting the amount of a transaction. This element is Required.

IMPORTANT! The Adjust object provides differenceData support for the BCP Service Class. Please refer to the Adjust operation for more information.
Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addenda. Object
X Amount Positive or negative amount to modify the original authorization amount. Decimal
Optional TipAmount Positive amount added to the total as a tip. Decimal
X TransactionId Transaction ID of the authorization to adjust. String

AlternativeMerchantData

Specifies alternative merchant data appearing on accountholder statements. Subject to Issuer discretion. This is an Optional element when supported by service.

Required Parameter Description Data Type
Optional Address Specifies alternate merchant address information – Maps to AddressInfo. Object
Conditional* CustomerServiceInternet Specifies an alternate customer service web URL or Email address. *Required for eCommerce transactions. String
Conditional* CustomerServicePhone Specifies an alternate customer service phone number. *Required for MOTO transactions. String
Optional Description Specifies a description of the product or service purchased recognizable by the accountholder. String
Optional MerchantId Specifies an alternate merchant location ID or vendor code. String
X Name Specifies an alternate merchant name or DBA name. String
Optional SIC Specifies the Standard Industry Code or Merchant Category Code used to identify an alternate merchant industry classification. String

BillPayServiceData

Specifies the bill payment service name and address for PINless Debit bill payments. This element is required if different from merchant name and address.

Required Parameter Description Data Type
X CompanyAddress Address of the bill payment service – Maps to AddressInfo. Object
X CompanyName Name of the bill payment service. String

Capture

Contains information for capturing a transaction for settlement. This element is Required.

IMPORTANT! The BankcardCapture object provides differenceData support across all service classes. Changes to the Amount/TipAmount must be specified in BankcardCapture.

Please refer to each Capture operation for more information.

Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addendum. Object
X TransactionId Transaction ID to capture in the authorization. String

CustomerInfo

Contains information about the customer. This element is required by some service providers. If this value is set on the transaction and not required by the service provider, the data is not present on the transaction.

Required Parameter Description Data Type
Optional Address Parameterized address – Maps to AddressInfo. Object
Optional BusinessName Company name. String
Optional Email Email address. String
Optional Fax Primary fax number. String
Optional Name Parameterized full name – Maps to NameInfo. Object
Optional Phone Primary telephone number. String

DriversLicense

Contains customer driver’s license information. This element is optional.

Required Parameter Description Data Type
X Number Driver’s license number. String
X State State or Province where customer drivers license was issued – Maps to the TypeStateProvince enumeration. Enum
Optional Track1 Track 1 data from the driver’s license magnetic stripe – Should not include the sentinels and LRC. String
Optional Track2 Track 2 data from the driver’s license magnetic stripe – Should not include the sentinels and LRC. String

Manage

Contains information for updating an account. This element is Required.

IMPORTANT! The following class provides differenceData support across all service classes.
Please refer to the ManageAccountById operation for more information.
Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addendum. Object
X TransactionId Transaction Identifier corresponding to the transaction to update. String

NameInfo

Contains customer name information. This element is required by some service providers. If the value is set on the transaction but not required by the service provider, the data is not present on the transaction.

Required Parameter Description Data Type
X First First name. String
X Last Last name. String
Optional Middle Middle name or initial. String
Optional Suffix Suffix. String
Optional Title Title. String

PayeeData

Specifies the payee information for PINless Debit bill payments. This element is required if the transaction is PINless Debit.

Required Parameter Description Data Type
X AccountNumber Customer account number assigned by the payment recipient company. String
X CompanyName Name of the payment recipient company. String
X Phone Phone number of the payment recipient company. String

PersonalInfo

Contains sensitive customer personal information. This element is Optional.

Required Parameter Description Data Type
Optional Company Company name. String
Optional DateOfBirth The customer date of birth. DateTime
Optional DriversLicense The customer driver’s license information. Object
Optional EmployeeIdNumber Employee identification number used as an alternate form of identification. String
Optional Gender The customer gender. String
Optional GovernmentIdNumber Government issued identification number used as an alternate form of identification. String
Optional MilitaryIdNumber Military issued identification number used as an alternate form of identification. String
Optional SocialSecurityNumber The customer social security number. String
Optional TaxId The customer federal tax identification number. String

PINlessDebitData

Collection of transaction details related to PINless Debit cards. This element is optional when processing a recurring or installment MOTO or Ecommerce transaction with a PIN Debit card without entering a PIN.

Required Parameter Description Data Type
Conditional* BillPayServiceData Specifies the bill payment service name and address for PINless Debit bill payment. *Required if different from merchant name and address. Object
X PayeeData Specifies the payee information for PINless Debit bill payment. Object

Response

Contains detailed transaction response data always returned to the client application. This element is expected.

Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addendum. Object
X CaptureState Indicates the state of the transaction as it relates to capture. Enum
X IsAcknowledged Indicates the transaction has been acknowledged by the client application. Boolean
X OriginatorTransactionId Transaction identifier assigned by CWS prior to sending the transaction to the service provider. Useful in identifying the transaction for contacting the service offline. Always be returned to the client application. String
Optional Reference Specifies user or customer reference data echoed from the request. String
Expected ServiceTransactionDateTime The local date and time for the transaction as calculated by the service. The amount of detail varies between services. Object
Expected ServiceTransactionId Transaction identifier assigned by the service provider. Useful in identifying the transaction when contacting the service provider offline. String
X Status Identifies if the transaction was a success or failure. Enum
X StatusCode Status code returned from the service. Required in the PTLS Schema for all CWS transactions. String
Optional StatusMessage Verbose message describing the status of the transaction. String
Expected TransactionId Transaction ID used for subsequent CWS transactions. String
X TransactionState Indicates the current state of a transaction. Enum

Bankcard Processing (BCP) Responses

For Bankcard transactions, the data elements contained in Response include values for both BankcardTransactionResponseas and BankcardTransactionResponsePro. For Bankcard Capture transactions, the data elements contained in Response are returned in BankcardCaptureResponse.

Note: If the application does not support Level 2 and/or Level 3 transaction data, only the values included as part of BankcardTransactionResponse need to be referenced.

Electronic Checking (ECK) Responses

For Electronic Checking transactions, the data elements contained in Response are returned in ElectronicCheckingTransactionResponse. For Electronic Checking Capture transactions, the data elements contained in Response are returned in ElectronicCheckingCaptureResponse.

Stored Value Account (SVA) Responses

For Stored Value Account transactions, the data elements contained in Response are returned in StoredValueTransactionResponse. For Stored Value Account Capture transactions, the data elements contained in Response are returned in StoredValueCaptureResponse.

Return

Contains information required when funds for a captured transaction need to be returned to the cardholder account. This element is Required.

IMPORTANT! The BankcardReturn object provides differenceData support for the BCP service class. Changes to the Amount must be specified in BankcardReturn.

Please refer to the ReturnById operation for more information.

Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addenda. Object
Optional TransactionDateTime The local date and time for a transaction as calculated by the merchant and printed on the customer receipt. This field should contain a timezone offset representing the timezone in which the transaction is taking place. Format: YYYY-MM-DDTHH:MM:SS±offset. Optional, but highly recommended. String
X TransactionId Transaction Id of the authorization to return. String

ServiceTransactionDataTime

The local date and time for a transaction as calculated by the service provider. If present in the response, thee data element and value must be provided when settling a subsequent authorization completion. This element is Optional.

Required Parameter Description Data Type
Optional Date Date. String
Optional Time Time. String
Optional TimeZone Timezone. String

SummaryData

Summary information for credit and debit totals. This element is Required.

Required Parameter Description Data Type
X CashBackTotals Totals for cash back transactions – Maps to SummaryTotals.>/td> Object
X CreditReturnTotals Totals for returned credit transactions – Maps to SummaryTotals. Object
X CreditTotals Totals for credit transactions – Maps to SummaryTotals. Object
X DebitReturnTotals Totals for returned debit transactions – Maps to SummaryTotals. Object
X DebitTotals Totals for debit transactions – Maps to SummaryTotals. Object
X NetTotals Net totals for the batch – Maps to SummaryTotals. Object
X VoidTotals Totals for voided transactions – Maps to SummaryTotals. Object

SummaryTotals

Contains net amount and total item count. This element is Required.

Required Parameter Description Data Type
Optional Count Total item count. Integer
Optional NetAmount Net amount. Decimal

Transaction

Contains all information required to send a transaction to a service provider. This element is Required.

Note: For Bankcard transactions, BankcardTransactionas must be included.

The following Transaction Processing operation signatures accept Transaction as a parameter:

  • AuthorizeAndCapture
  • Authorize
  • ReturnUnlinked
  • QueryAccount
  • Verify
  • ManageAccount
Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addendum. Object
Optional CustomerData Details about the customee – Maps to TransactionCustomerData. Object
Optional ReportingData Additional data to be printed on reports – Maps to TransactionReportingData. Object
X TenderData Details about the tender used for the transaction – Maps to TransactionTenderData. Object
X TransactionData Details about the transaction. Object

TransactionCustomerData

Contains information about the customer. This element is required by some service providers. If this value is set on the transaction and not required by the service provider, the data is not present on the transaction.

Required Parameter Description Data Type
Optional BillingData Customer billing data – Maps to CustomerInfo. Object
Optional CustomerId Reference number used by the merchant to identify the customer. String
Optional CustomerTaxId Customer’s federal or VAT identification number. String
Optional ShippingData Customer shipping data – Maps to CustomerInfo. Object

TransactionData

Base class object containing information for a specific transaction. This element is Required.

Required Parameter Description Data Type
X Amount Authorization amount of the transaction. Decimal
Optional CampaignId Specifies the identifier associated with a campaign-enabled Commerce Playlist, such as Multi-Party Payments (MPP). String
X CurrencyCode Transaction currency code as defined by the International Standards Organization (ISO). – Maps to the TypeISOCurrencyCodeA3 enumeration. Enum
Optional Reference Specifies user or customer reference data used for tracking or reporting purposes echoed back in the response. String
Conditional* TransactionDateTime The local date and time of the transaction as calculated by the merchant and printed on the customer receipt. This field should contain a timezone offset representing the timezone in which the transaction is taking place. Format: YYYY-MM-DDTHH:MM:SS±offset. *Required by some service providers. String
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. Either ‘NotSet’ or ‘Override’

TransactionReportingData

Contains additional transaction data to be printed on reports. This element is conditional, allowed by some service providers. If this value is set on the transaction and not allowed by the service provider, the data is not present on the transaction.

Required Parameter Description Data Type
Optional Comment Comment about the transaction. String
Optional Description Transaction description. String
Optional Reference Merchant or customer reference field used for tracking or reporting purposes. String

TransactionTenderData

Base class object containing information about the tender used for a specific transaction. This element is Required.

Note: For Bankcard transactions, BankcardTenderData must be included.
Required Parameter Description Data Type
Conditional* EncryptionKeyId Specifies the identifier for the encryption key used for card data encryption, such as the key serial number for DUK/PT encryption. *Required if SecurePaymentAccountData is used. String
Optional PaymentAccountDataToken
PTLS Mapping:CardDataToken
Token specified by offsite cardholder data storage service providers to retrieve stored payment account data. May be used in place of detailed tender data.
Note: For more information about support for PaymentAccountDataToken, please refer to FIND THISDKJSLT.
String
Conditional* SecurePaymentAccountData PTLS Mapping:SecureCardDataData collected from a magnetic stripe and protected by an encrypting card reader. Track 2 data must be provided. *A minimum of one of the following CardData, PaymentAccountDataToken or SecurePaymentAccountData must be provided. String
Optional SwipeStatus Specifies the status of the card swipe as returned by the card reader. String

Undo

Contains information for undoing (voiding) a transaction. This element is Required.

IMPORTANT! The following class provides differenceData support across all service classes. Please refer to the Undo operation for more information.
Required Parameter Description Data Type
Optional Addendum Managed and unmanaged addenda Object
X TransactionId Transaction Id of the authorization to void. String

Unmanaged

Can be used to pass service-specific information such as username/password or session token credentials. This element is Optional.

Required Parameter Description Data Type
X Any One or more XML strings. String