Developer API Reference
Base Transaction Data Elements
The following Base Transaction data elements are required in all transactions (unless noted), regardless of transaction class.
Contains information for activating an account. This is a required element.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Optional | Addendum | Managed and unmanaged addendum. | Object |
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 |
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 |
Contains information for adjusting the amount of a transaction. This element is Required.
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 |
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 |
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 |
Contains information for capturing a transaction for settlement. This element is Required.
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 |
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 address. | String | |
| Optional | Fax | Primary fax number. | String |
| Optional | Name | Parameterized full name - Maps to NameInfo. | Object |
| Optional | Phone | Primary telephone number. | String |
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 |
Contains information for updating an account. This element is Required.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Optional | Addendum | Managed and unmanaged addendum. | Object |
| X | TransactionId | Transaction Identifier corresponding to the transaction to update. | String |
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 |
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 |
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 |
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 |
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.
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.
Contains information required when funds for a captured transaction need to be returned to the cardholder account. This element is Required.
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 |
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 |
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 |
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 |
Contains all information required to send a transaction to a service provider. This element is Required.
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 |
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 |
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' |
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 |
Base class object containing information about the tender used for a specific transaction. This element is Required.
| 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 see here . | 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 |
Contains information for undoing (voiding) a transaction. This element is Required.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Optional | Addendum | Managed and unmanaged addenda | Object |
| X | TransactionId | Transaction Id of the authorization to void. | String |
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 |