Developer API Reference

Bankcard Transaction Data Elements

The following Bankcard data elements are required in all Bankcard transactions (Credit or PIN Debit), unless noted otherwise. These data elements are included with each Bankcard transaction in addition to Base Transaction data elements.

Note: While the Base Transaction data elements are required, your application cannot send a transaction containing only Base Transaction data elements. Bankcard-specific transaction data is required to successfully process any Bankcard transaction.

AVSData

Cardholder address data for Address Verification System (AVS). This element is Optional.

Note: Please reference the ServiceInformation.BankcardServices. AVSData object returned by GetServiceInformation to determine which fields below must be set.
Required Parameter Description Data Type
Conditional* CardholderName Cardholder name embossed on the front of the card. *Required if specified in AVSData.CardholderName(ServiceInformation). String
Conditional* City City. *Required if specified in AVSData.City(ServiceInformation). String
Conditional* Country Country. *Required if specified in AVSData.Country(ServiceInformation). Maps to the TypeISOCountryCodeA3 enumeration. Enum
Conditional* Email Cardholder email address. *Please reference AVS/Email service configuration for level of service provider support. String
Conditional* Phone Cardholder phone number. *Required if specified in AVSData.Phone(ServiceInformation). String
Conditional* PostalCode Postal code. *Required if specified in AVSData.PostalCode(ServiceInformation). String
Conditional* StateProvince State or Province. *Required if specified in AVSData.StateProvince(ServiceInformation).

AVSResult

Specifies the result of an Address Verification System (AVS) lookup by the service provider. This element is Optional.

Required Parameter Description Data Type
Optional ActualResult Specifies the actual result of AVS from the service provider. String
X AddressResult Specifies the result of AVS as it pertains to address matching. Enum
X CardholderNameResult Specifies the result of AVS as it pertains to cardholder name matching. Enum
X CityResult Specifies the result of AVS as it pertains to city matching. Enum
X CountryResult Specifies the result of AVS as it pertains to country matching. Enum
X PhoneResult Specifies the result of AVS as it pertains to phone matching. Enum
X PostalCodeResult Specifies the result of AVS as it pertains to postal code matching. Enum
X StateResult Specifies the result of AVS as it pertains to state matching. Required. Enum

BankcardApplicationConfigurationData

Overrides application data for the specific transaction. This element is Optional.

Required Parameter Description Data Type
Optional ApplicationAttended Indicates the application is attended or unattended, if different from the value set in ServiceInformation. Boolean
Optional ApplicationLocation Location of the application relative to the merchant, if different from the value set in ServiceInformation. Enum
Optional HardwareType Type of device running the application, if different from the value set in ServiceInformation. Enum
Optional PINCapability Indicates support for cardholder Personal Identification Number (PIN), if different from the value set in ServiceInformation. Enum
Optional ReadCapability Capability of the device to read cardholder data, if different from the value set in ServiceInformation. Enum

ApplicationConfigurationData

The Following Are Required For EMV Transactions.

Required Parameter Description Data Type
Optional ApplicationAttended Indicates whether the application is attended or unattended, if different from the value set in ServiceInformation. Boolean
Optional ApplicationLocation Location of the application relative to the merchant, if different from the value set in ServiceInformation. Enum
Optional HardwareType Type of device running the application, if different from the value set in ServiceInformation. Enum
Optional PINCapability Indicates support for cardholder Personal Identification Number (PIN), if different from the value set in ServiceInformation. Enum
Optional ReadCapability Capability of the device to read cardholder data, if different from the value set in ServiceInformation. Enum
Required for EMV EMVTerminalData A code that describes the condition under which the transaction takes place at the Point-Of-Service. string
Required for EMV CardDataOutputCapability The card data output capability of the terminal. Enum
Required for EMV CardRetentionCapability A code that describes the condition under which the transaction takes place at the Point-Of-Service. Enum
Required for EMV CardholderAuthenticationCapability The cardholder authentication capability of the terminal. Enum
Required for EMV PINMaxCharacters The PIN capture capability of the terminal. Enum
Required for EMV TerminalOperator The terminal operator. 0 – Customer operated 1 – Card acceptor operated 2 – Administrative Enum
Required for EMV TerminalOutputCapability The terminal output capability of the terminal. Enum

BankcardCapture

Contains information for capturing Bankcard transactions (Credit and PIN Debit). This element is Required. BankcardCapture provides differenceData support for the following Transaction Processing operations:

  • Capture(BCP, SVA)
  • CaptureAll(BCP, ECK)
  • CaptureAllAsync(BCP only)
Required Parameter Description Data Type
Conditional* Amount Amount to capture if different from the authorized amount. *Required when capturing a different amount than what was authorized. Decimal
Conditional* ChargeType Indicates the type of charge. In most retail environments this value is set to ‘RetailOther’, but if other enumerations are applicable they should be used. *Required for Retail transactions. Enum
Conditional* ShipDate Date of goods shipment. *Required for MOTO transactions. DateTime
Optional TipAmount Tip amount, if not specified at the time of authorization. Decimal
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. ‘NotSet’ or ‘Override’

BankcardCaptureResponse

Response to capturing one or more Bankcard transactions (Credit and PIN Debit). The element is Expected.

Note:BankcardCaptureResponse inherits the data elements in Response.

BankcardCaptureResponse is returned by the following Transaction Processing operation signatures:

  • Capture
  • CaptureAll
  • CaptureAllAsync
Required Parameter Description Data Type
Optional BatchId Batch identifier. String
Expected IndustryType The industry type of the transaction(s). Enum
Optional PrepaidCard Specifies whether or not the card is a prepaid card. The identification of prepaid cards is at the discretion of the payment brand or issuer. Enum
Conditional* TransactionSummaryData Summary of transaction data. *Expected for CaptureAll. Object

BankcardReturn

Contains information for returning Bankcard transactions (Credit and PIN Debit). Maps to BankcardTenderData.Object This element is Required. BankcardReturn provides differenceData support for the following Transaction Processing operations:

  • ReturnById
Required Parameter Description Data Type
Conditional* Amount Specifies the amount to return. *Required when performing a partial return. Decimal
Optional FeeAmount Specifies the fee amount associated with an authorization, such as convenience fees. Decimal
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. ‘NotSet’ or ‘Override’

BankcardTenderData

Contains information about the Bankcard transaction tender data. This element is Required.

Required Parameter Description Data Type
Conditional* CardData *Required if any one of the following must be provided:

  • CardData
  • PaymentAccountDataToken – PTLS Mapping: CardDataToken
  • SecurePaymentAccountData – PTLS Mapping: SecureCardData
Object
Optional CardSecurityData Security data for card transactions, such as AVS and CVV. Object
Conditional* EcommerceSecurityData Ecommerce security elements. *Optional for Ecommerce transactions, otherwise not present. Object

BankcardTransaction

Contains information about the Bankcard transaction (Credit and PIN Debit). This element is Required.

Note:BankcardTransaction inherits the data elements in Transaction.

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

  • AuthorizeAndCapture
  • Authorize
  • ReturnUnlinked
  • QueryAccount
  • Verify
  • ManageAccount
Required Parameter Description Data Type
Optional ApplicationConfigurationData Details about the way this application instance is configured, if different from the values set in ServiceInformation. – Maps to BankcardApplicationConfigurationData. Object
X BankcardTenderData Contains transaction information such as card data, routing information, and additional data specific to the tender being processed. Object
X BankcardTransactionData Contains transaction detail information. Object

BankcardTransactionData

Contains information about the Bankcard transaction data. This element is Required.

Required Parameter Description Data Type
Optional AccountType Indicates the bank account type. Enum
Conditional* AlternativeMerchantData Alternative merchant data to appear on accountholder statements. Subject to Issuer discretion. *Optional if BankcardService.AlternativeMerchantData is true. Object
Conditional* ApprovalCode Approval code for this authorization. *Required if prior authorization approval was obtained. String
Optional BatchAssignment Specific batch number assignment, when allowed. String
Optional BatchId Override for the default BatchId. Only used if BatchAssignment is supported. String
Optional CashBackAmount Specifies a cash back amount for PIN Debit transactions. Decimal
X CustomerPresent Presence of cardholder relative to the transaction point of service. Enum
Conditional* EmployeeId Clerk/cashier identifier. *Required for Retail, Restaurant, and MOTO industry types. String
X EntryMode Indicates how the cardholder data was retrieved. When authorizing with stored card data, either locally or with PaymentAccountDataToken, indicates that the card data was manually collected (keyed or one of its variants). Enum
Optional FeeAmount Specifies a fee amount associated with the authorization, such as convenience fees. Decimal
Optional GoodsType Type of goods purchased. Enum
IndustryType OBSOLETE
MerchantProfile must include IndustryType and cannot be overridden at the transaction level.
Enum
Optional InternetTransactionData Gets or sets the internet transaction data value. Object
Optional InvoiceNumber Informational field used to track invoice/receipt number. String
Optional IsPartialShipment Indicates whether or not the transaction represents a partial shipment. Boolean
Optional IsQuasiCash If ‘true’, specifies that this transaction represents a sale of items that are directly convertible to cash, such as casino gaming chips, money orders, deposits, wire transfer money orders, Travelers Cheques, and foreign currency. Boolean
Optional LaneId Identifies the cashier location at which the transaction occurred. String
X OrderNumber Order number as assigned by the merchant. String
Conditional* PartialApprovalCapable Indicates whether the merchant is capable of processing a partial approval for this transaction. *Required if ServiceInformation.Tenders.PartialApprovalSupportType = ‘Enabled’. Otherwise, not present. – Maps to the PartialApprovalSupportType enumeration. Enum
Optional ScoreThreshold Specifies the Magensa MagnePrint® score threshold used in accepting or declining certain transactions. String
X SignatureCaptured Specifies whether the cardholder provided a signature for the transaction. Boolean
Optional TerminalId Gets or sets the internet transaction data value. String
Optional TipAmount Tip amount, if known at the time of authorization. Decimal
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. ‘NotSet’ or ‘Override’

BankcardTransactionResponse

Response to the Bankcard transaction (Credit and PIN Debit). This element is Expected.

Note:BankcardTransactionResponse inherits the data elements in Response.

The data elements listed below are returned in BankcardTransactionResponsePro regardless of whether “Pro” data (Level2, Level3) is supported. BankcardTransactionResponse is returned by the following Transaction Processing operation signatures:

  • Acknowledge
  • AuthorizeAndCapture
  • Authorize
  • ReturnById
  • ReturnUnlinked
  • Adjust
  • Undo
  • QueryAccount
  • Verify
  • ManageAccount
Required Parameter Description Data Type
Expected Amount Specifies the authorization amount of the transaction. This is the actual amount authorized and used when settling a subsequent authorization completion instead of the request amount. Decimal
Expected ApprovalCode A value returned when a transaction is approved. This value should be printed on the receipt, and also recorded for every off-line transaction, such as a voice authorization. String
Optional AVSResult Collection of AVS response data. Object
Optional BatchId Batch Identifier. String
Optional CardLevel Code returned by the card association that indicates the type of card used by the customer.. String
Optional* CardType Type of card used in the transaction. *Optional for Credit transactions. – Maps to the TypeCardType enumeration. Enum
Optional CashBackAmount The approved cash back amount. Decimal
Optional CVResult Response code returned by the card issuer indicating the result of Card Verification (CVV2/CVC2/CID). Enum
Optional DowngradeCode Downgrade reason. String
Optional FeeAmount Fee amount charged for the transaction. Decimal
Optional FinalBalance The account balance after the transaction. Decimal
Expected MaskedPAN The cardholder’s PAN in masked format.
Note: MaskedPAN is stored with each transaction record and returned in the response to TMS query requests. Although the first 6 digits of MaskedPAN may be returned in the response (for example, 9876-54**-****-****-1234), they are only to be used by the software company and EVO Snap* for troubleshooting purposes. As a best practice, software companies should only present the last 4 digits of MaskedPAN to the merchant and their customers, whether displaying this information on-screen or printing the information on a receipt or invoice.
String
Optional OrderId The order id generated by CWS. This value is often used by service providers for transaction correlation. String
Conditional* PaymentAccountDataToken Token specified by a tokenization (offsite payment account data storage) service provider, used to retrieve securely stored payment account data. *Required if any one of the following must be provided: String
Optional PrepaidCard Specifies whether or not the card is a prepaid card. The identification of prepaid cards is at the discretion of the payment brand or issuer. Enum
Optional Resubmit Specifies whether resubmission is supported for PIN Debit transactions. Enum
Optional RetrievalReferenceNumber Retrieval reference number generated by the processor used for settlement and reversals. If present in the response, this same data element and value must be provided during settlement of any subsequent authorization linked to this transaction. String
Optional SettlementDate Settlement date. DateTime

BankcardUndo

Contains information for undoing (voiding) Bankcard transactions (Credit and PIN Debit). This element is Required. The following Transaction Processing operation signatures accept BankcardUndo as a parameter:

  • Undo
Required Parameter Description Data Type
ForceVoid Indicates that the authorized transaction should be removed from the batch regardless of whether the Undo is approved or declined. Otherwise, authorized transactions will only be removed from the batch if the void is approved. Boolean
Conditional* PINDebitReason Specifies the reason for the undo. *Required for PIN Debit transactions. – Maps to the PINDebitUndoReason enumeration. Enum
Conditional* TenderData Details about the card tender. *Required if BankcardService.Tenders.PINDebitUndoTenderDataRequired is true.Maps to BankcardTenderData. Object
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. ‘NotSet’ or ‘Override’

CardDate

Contains information about the payment card. Conditional, required for Authorize and AuthorizeAndCapture transactions. May be required for undoing PIN Debit transactions.

Required Parameter Description Data Type
Optional CardholderName Cardholder name embossed on the front of the card. Recommended for MOTO and Ecommerce industry types. String
X CardType Type of card used in the transaction. – Maps to the TypeCardType enumeration. Enum
Conditional* Expire The 4-digit expiration date embossed on the front of a card. *Required for authorization, not required for settlement. String
X PAN Cardholder Primary Account Number embossed on the front of the card. String
Conditional* Track1Data The actual data read from the magnetic stripe on a card. Application should strip Start and End Sentinels, LRC, and Track separators. *Required if at least one track data is required for authorizations unless card not present or keyed entry. String
Conditional* Track2Data The actual data read from the magnetic stripe on a card. Application should strip Start and End Sentinels, LRC, and Track separators. *Required if at least one track data is required for authorizations unless card not present or keyed entry. String

EMVData

Contains EMV data for the payment card.

Required Parameter Description Data Type
ApplicationId Identifies the application on the ICC as described in ISO/IEC 7816-5. Tag 9F06 (AID) String
ApplicationVersionNumber Version number assigned by the payment system for the application.Tag 9F09 string
* AuthorizationAmount The amount of the transaction. *Must be present in a 0100, 0120, 0200, or 0220 message for an ICC chip transaction. Tag 9F02 String
* ApplicationInterchangeProfile Indicates the capabilities of the ICC to support specific functions in the application. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 82 String
* ApplicationTransactionCount Counter maintained by the application in the ICC. (Incrementing the ATC is managed by the ICC). *Must be present in a 0100, 0120, 0200 or 0600 message for an ICC chip transaction. Otherwise, optional. Tag 9F36 (ATC) String
ApplicationUsageControl Indicates the issuer’s specified restrictions on the geographic usage and services allowed for the application. Tag 9F07 String
AuthorizationResponseCode Code returned by the issuer or generated by the terminal if it did not receive an online response from the issuer. Tag 8A String
CardAuthenticationReliabilityIndex May be set and sent by the acquirer when the acquirer or issuer is inactive for card authentication. String
CardAuthenticationResultsCode An issuer-supplied code indicating card authentication results. String
ChipConditionCode Indicates the status of the chip attempt at the terminal. This provides diagnostic and fraud detection data about magnetic stripe read operations at ICC terminals. 0 – Magnetic stripe read, service code does not begin with 2 or 6 (not chip card) OR Chip read, service code begins with 2 or 6 (chip card). 1 – Magnetic stripe read, service code begins with 2 or 6 (chip card), not preceded by chip read failure. 2 – Magnetic stripe read, service code begins with 2 or 6 (chip card), preceded by chip read failure (ICC fallback to magnetic stripe). String
* Cryptogram The cryptogram generated by the ICC. Consists of one of the following: Authorization Request Cryptogram (ARQC) for an authorization request, Application Authentication Cryptogram (AAC) for a declined transaction, or Transaction Certificate (TC) for an approved transaction. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 9F26 String
CryptogramInfromationData Indicates the type of cryptogram returned by the ICC (ARQC, AAC or TC) and the actions to be performed by the terminal. Will be present if available from the terminal, and must be set if available. May be used in validating the cryptogram. Tag 9F27 String
CVMList Identifies the cardholder verification methods (CVMs) supported by the application. Tag 8E String
CVMResults Cardholder verification method (CVM) results indicating the results of the last CVM performed. Tag 9F34 String
InterfaceDeviceSerialNumber A unique and permanent serial number assigned to the interface device (IFD) by the terminal manufacturer. Tag 9F1E (IFD) String
* CashBackAmount Secondary amount associated with the transaction, representing a cashback amount. In a cashback transaction, *must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise optional. Tag 9F03 String
IssuerActionDefault Card parameters that instruct the terminal about actions to take under various conditions. – Default ( ans10 , conditional ) Specifies the issuer’s conditions that cause a transaction to be rejected if it might have been approved online, but the terminal is unable to process the transaction online. Tag 9F0D If the IssuerActionCode field is set, only one of the fields should be set. String
IssuerActionDenial – Denial ( ans10 , conditional ) Specifies the issuer’s conditions that cause the denial of a transaction without attempt to go online. Tag 9F0E If the IssuerActionCode field is set, only one of the fields should be set. String
IssuerActionOnline – Online ( ans10 , conditional ) Specifies the issuer’s conditions that cause a transaction to be transmitted online. Tag 9F0F If the IssuerActionCode field is set, only one of the fields should be set. String
IssuerApplicationData Proprietary application data for transmission from the ICC to the issuer. May contain the following subfields: Scheme Discretionary Data, Issuer Discretionary Data, Derivation Key Index, Cryptogram Version Number, Card Verification Results, DAC. The layout of this field is specific to the issuer. Will be present if available from the terminal, and must be set if available. May be used in validating the cryptogram. Tag 9F10 String
IssuerScriptResults Indicates the result of the terminal script processing.
May be returned by the ICC to indicate the results of a script processed in a previous transaction. Typically sent in an 0120, 0220, 0420 advice message.
String
* LocalTransactionDate The local date (in YYMMDD format) on which the transaction was authorized. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 9A String
TerminalCapability Indicates the card data input, CVM, and security capabilities of the terminal. Tag 9F33 String
* TerminalCountryCode Indicates the country of the terminal, represented according to ISO 3166. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 9F1A String
TerminalType Indicates the environment of the terminal, its communications capability, and its operational control. Tag 9F35 String
* TerminalVerifyResult Status of the different functions as seen from the terminal. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 95 String
TransactionCategoryCode Defines the type of transaction for which authorization is being requested. Used in risk management. String
* CurrencyCode Indicates the currency code of the transaction according to ISO 4217. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 5F2A String
SequenceNumber Counter maintained by the terminal and incremented by one for each transaction. Tag 9F41 String
* TransactionType Indicates the type of the transaction, represented by the first two digits of the ISO 8583:1997 Processing Code. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 9C String
* UnpredictableNumber Value to provide uniqueness to the generation of the cryptogram. *Must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. Tag 9F37 String

CardSecurityData

Contains security information for the payment card. This element is required for PIN Debit transactions.

Required Parameter Description Data Type
Optional AVSData Cardholder address data for Address Verification System (AVS). Object
Conditional* CVData The Card Verification (CV) data applies to Visa (CVV), MasterCard (CVC), AMEX (CID), and Discover (CID), and is contained on the signature line of the physical credit card. *Required in authorizations if CVDataInd = ‘Provided’, not used in settlement. String
Optional CVDataProvided Indicates whether or not CV data provided. Recommended for card not present authorizations, not used in settlement. Enum
Optional IdentificationInformation Specifies identifying information about the tender, such as a magnetic stripe fingerprint. String
Conditional* KeySerialNumber Key serial number for DUK/PT PIN encryption. *Required for PIN Debit transactions. String
Conditional* PIN Encrypted PIN. *Required for PIN Debit transactions. String

EcommerceSecurityData

Ecommerce security elements. This element is Conditional, optional for Ecommerce transactions, otherwise not present.

Required Parameter Description Data Type
Conditional* TokenData Contains actual data for token. VPAS or UCAF value must be in its original base64 encoded form. *Required for Electronic Commerce transactions using VPAS, UCAF, or SET w/certificate. String
Conditional* TokenIndicator Specifies VPAS, UCAF, or SET certificate S/N. *Required for Electronic Commerce transactions using VPAS, UCAF, or SET w/certificate. Enum
Optional XID Transaction identifier in its original, base64 encoded form for Electronic Commerce transactions w/VPAS. String

IIASData

Inventory Information Approval System (IIAS) data including amounts for Flexible Spending Account (FSA) eligible items.

Required Parameter Description Data Type
Optional ClinicOtherAmount Specifies the portion of HealthCareAmt related to clinic or other qualified expenses. Decimal
Optional DentalAmount Specifies the portion of HealthCareAmt related to dental expenses. Decimal
Conditional* HealthcareAmount Specifies the total amount of eligible healthcare items associated with the authorization. *Required for IIAS transactions. Decimal
Conditional* IIASDesignation Specifies merchants IIAS status. *Required for IIAS transactions. Enum
Optional PrescriptionAmount Specifies the portion of HealthCareAmt related to prescription expenses. Decimal
Optional VisionAmount Specifies the portion of HealthCareAmt related to vision or optical expenses. Decimal

InternetTransactionData

Contains information about the internet connection. 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
Conditional* IpAddress The IP Address of the client application. *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. String
Conditional* SessionId The Session Id of the application. *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. String

ItemizedTax

Contains itemized tax information. This element is Optional.

Required Parameter Description Data Type
X Amount Amount of tax applied. Decimal
Optional Rate Rate of tax applied. Decimal
X Type Type of tax applied. – Maps to the TypeTaxType enumeration. Enum

ItemizedTaxes

Collection of itemized tax information. This element is Optional.

Required Parameter Description Data Type
X ItemizedTax Aggregate of tax information. Object

Level2Data

Aggregate of elements specific to Level 2/Purchase Card transactions. This element is Optional.

Required Parameter Description Data Type
X BaseAmount Base amount of the transaction, not including freight, handling, and tax amounts. Decimal
Optional CommodityCode Commodity code for the entire purchase. String
Optional CompanyName Name of company making purchase. String
Optional CustomerCode Code provided by cardholder to appear on invoice. String
Optional Description Description of the purchase. String
Optional DestinationCountryCode Destination country code of the goods being shipped. – Maps to the TypeISOCountryCodeA3 enumeration. Enum
Optional DestinationPostal Destination postal code. String
Optional DiscountAmount Discount amount. Decimal
Optional DutyAmount Duty amount. Decimal
Optional FreightAmount Freight amount. Decimal
Optional MiscHandlingAmount Miscellaneous handling charges. Decimal
Optional OrderDate Date the order was placed. DateTime
X OrderNumber Order number. String
Optional RequesterName Name of the person making the request. String
Optional ShipFromPostalCode The zip/postal code of the location from which the goods are shipped. String
Optional ShipmentId Number of the shipment. String
Optional Tax Aggregate of tax information. Object
Optional TaxExempt Tax exemption indicator and number. Object

LineItemDetail

Aggregate containing a collection of line item data. Allowed by some service providers. This element is Optional.

Required Parameter Description Data Type
X Amount Line item total cost. Use DiscountIncluded and TaxIncluded to specify whether this amount is inclusive of DiscountAmount and Tax. Decimal
Optional CommodityCode Line item commodity code. String
Optional Description Line item description. String
Optional DiscountAmount Discount amount for this line item. Decimal
Conditional* DiscountIncluded Indicates whether amount is inclusive of discount. *Required if DiscountAmount is specified. Boolean
Optional ProductCode Line item product code. String
X Quantity Quantity of item. Decimal
X SequenceNumber Sequence number generated by CWS. Long
Optional Tax Tax details for this line item. Object
X TaxIncluded Indicates whether amount is inclusive of tax. Boolean
Optional UnitOfMeasure Units used to measure quantity. – Maps to the TypeUnitOfMeasure enumeration. Enum
X UnitPrice Price per unit of line item. Decimal
Optional UPC Line item UPC code. String

ManagedBilling

Configuration to setup and perform an automated recurring payment on behalf of the merchant. This element is optional if ManagedBilling(ServiceInformation) = ‘true’, otherwise not present.

Note: Managed Billing is not currently supported.
Required Parameter Description Data Type
Optional DownPayment Amount the cardholder is initially paying towards the purchase. Decimal
X Installments Installment data. – Maps to ManagedBillingInstallments. Object
X Interval Unit used in calculating the period. Enum
X Period Number of intervals between each payment. Integer
X StartDate Date when the recurring payments should be initiated. DateTime

ManagedBillingInstallments

Installment data. This element is Required.

Note: Managed Billing is not currently supported.
Required Parameter Description Data Type
X Amount Amount the cardholder should be billed in each installment. Decimal
X Count Number of times the cardholder should be billed. Integer

Tax

Aggregate of tax information. This element is Optional.

Required Parameter Description Data Type
X Amount Total amount of tax applied. Decimal
Optional InvoiceNumber Tax invoice number. String
Optional ItemizedTaxes Collection of itemized tax information. Object
Optional Rate Total tax rate. Decimal

TaxExempt

Tax exemption indicator and number. This element is Optional.

Required Parameter Description Data Type
X IsTaxExempt Indicates tax exempt status of the transaction. Enum
Conditional* TaxExemptNumber Indicates the tax exempt number for the transaction. *Required if IsTaxExempt = ‘Exempt’ or ‘NotExemptTaxInfoProvided’. String

Totals

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

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

TransactionSummaryData

Summary information (item count and total amount) when transactions are captured. This element is Required.

Required Parameter Description Data Type
Optional CashBackTotals The sum of all PIN Debit transaction cash back amounts included in the batch. – Maps to Totals. Object
Expected NetTotals Total count and net amount of transactions for the entire batch independent of transaction class. – Maps to Totals. Object
Optional PINDebitReturnTotals Total count and amount of PIN Debit returns. – Maps to Totals. Object
Optional PINDebitSaleTotals Total count and amount of PIN Debit sales. – Maps to Totals. Object
Optional ReturnTotals Total count and amount of returns for the entire batch independent of transaction class. – Maps to Totals. Object
Optional SaleTotals Total count and amount of sales for the entire batch independent of transaction class. – Maps to Totals. Object
Optional VoidTotals Total count and amount of voids for the entire batch independent of transaction class. – Maps to Totals. Object

Bankcard Transaction Pro Data Elements

Applications supporting Level 2 and/or Level 3 data may be required to provide the following data elements in addition to the Base Transaction and Bankcard Transaction data elements.

IMPORTANT! In addition to the Transaction and BankcardTransaction objects, you must also create a BankcardTransactionPro object to support Level 2 and/or Level 3 data elements.

Levels of “Pro” Data

There are three levels of “pro” transaction data supported by Commerce Web Services:

  • Level 2 Data – Contains “Pro” Bankcard transaction data specified in BankcardTransactionDataPro in the Level2Data object.
  • Level 3 Data – Contains “Pro” Bankcard transaction data specified in BankcardTransactionDataPro in the LineItemDetail object.
  • Managed Billing Data – Contains “Pro” Bankcard transaction data specified in BankcardTransactionDataPro in the ManagedBilling object to supporting recurring (installment) payments.Not currently supported.

BankcardCapturePro

Contains information for capturing Bankcard Pro transactions. This element is Required.

Note: Please refer to BankcardTransactionDataPro for detailed information about the Level2Data and LineItemDetails objects below.
Required Parameter Description Data Type
Conditional* Level2Data Aggregate of elements specific to Level 2/Purchase Card transactions. *Required when LineItemDetails are provided, otherwise optional if Service Information indicates PurchaseCardLevel(ServiceInformation) = ‘Level2’ or higher and this data was not passed in the authorization. Object
Conditional* LineItemDetails Collection of transaction line item details. *Optional if service information indicates PurchaseCardLevel(ServiceInformation) = ‘Level3’.Maps to LineItemDetail. Object
Conditional* MultiplePartialCapture If present (true), indicates that this is a partial capture of the authorized funds. Additional captures are made against the same authorization. If omitted (false) then this is the last amount to be captured from the authorization. Any additional authorized funds are released. *Required if MultiplePartialCapture (ServiceInformation) is ‘true’. Boolean
Optional ShippingData Customer shipping details. – Maps to CustomerInfo. Object
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. ‘NotSet’ or ‘Override’

BankcardCaptureResponsePro

Response to capturing Bankcard Pro transactions. This element is Expected.

IMPORTANT! When sending in a BankcardCapture object, BankcardCaptureResponsePro inherits the data elements in BankcardCaptureResponse.

BankcardInterchangeData

Details about a transaction that may lower interchange rates for the transaction. This element is Optional.

Required Parameter Description Data Type
Conditional* BillPayment Indicates that the transaction is one in a set of recurring or installment transactions. *Required for recurring or installment transactions. Enum
Conditional* CurrentInstallmentNumber Number of installment represented by this transaction. *Required for installment transactions. Integer
Conditional* ExistingDebt Indicates recurring or installment transaction is on existing debt. *Required if BillPayment is set. Enum
Optional RequestACI Authorization Characteristics Indicator. Identifies the request as potentially qualifying for the Visa CPS or MasterCard Merit programs. Enum
Optional RequestAdvice Indicates whether to include advice on declined recurring payment transactions. Enum
Optional RequestCommercialCard Request commercial card status for the transaction. Enum
Conditional* TotalNumberOfInstallments Number of installments in the series. *Required for installment transactions. Integer

BankcardReturnPro

Contains information for capturing Bankcard Pro transactions. This element is Required.

Note: Please refer to BankcardTransactionDataPro for detailed information about the LineItemDetails objects below.
Required Parameter Description Data Type
Conditional* LineItemDetails Collection of transaction line item details. *Optional if service information indicates PurchaseCardLevel(ServiceInformation) = ‘Level3’.Maps to LineItemDetail. List
TransactionCode Specifies if a transaction should override the Evo duplicate charge check. ‘NotSet’ or ‘Override’

BankcardTransactionDataPro

Contains information about the Bankcard Pro transaction data. This element is Required to support Level 2 and/or Level 3 transaction data.

Note: Managed Billing is not currently supported.
Required Parameter Description Data Type
IIASData Inventory Information Approval System (IIAS) data including amounts for Flexible Spending Account (FSA) eligible items. Object
Conditional* Level2Data Aggregate of elements specific to Level 2/Purchase Card transactions. *Required when LineItemDetails are provided, otherwise optional if Service Information indicates PurchaseCardLevel (ServiceInformation) = ‘Level2’ or ‘Level3’. Object
Conditional* LineItemDetails Collection of transaction line item details. *Optional if Service Information indicates PurchaseCardLevel(ServiceInformation) = ‘Level3’.Maps to LineItemDetail. Object
Conditional* ManagedBilling Not currently supported.Configuration to setup and perform an automated recurring payment on the behalf of the merchant. *Optional if ManagedBilling(ServiceInformation) = ‘true’, otherwise not present. Object
Conditional* PINlessDebitData Collection of transaction details related to PINless Debit cards. *Optional when processing a recurring or installment MOTO or Ecommerce transaction with a PIN Debit card without entering a PIN. Object

BankcardTransactionPro

Contains information required to support recurring, installment, and deferred billing payments. This element is Required.

Required Parameter Description Data Type
Optional InterchangeData Details about a transaction that may lower interchange rates for the transaction. – Maps to BankcardInterchangeData. Object

BankcardTransactionResponsePro

Response to Bankcard Pro transactions. This element is Expected.

Note: BankcardTransactionResponsePro inherits the data elements in Response and BankcardTransactionResponse.

For all Bankcard transactions, BankcardTransactionResponsePro is returned even if ‘Pro’ data (Level2, Level3) is not supported.

Required Parameter Description Data Type
Optional AdviceResponse Specifies the reason for issuer decline of recurring payment transactions. Enum
Optional CommercialCardResponse Indicates the status of the card with respect to its ability to utilize purchase card data. When the card is a Business, Corporate, or Purchase card, providing purchase card data can result in improved interchange rates. Enum
Optional ReturnedACI Provides information concerning the status of a transaction’s CPS qualification. String