Bankcard Transaction Data Elements

Developer API Reference

Print Friendly, PDF & Email

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.

 

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
Optional Address Cardholder's address String
Optional CardholderName Cardholder name embossed on the front of the card. String
Optional City City String
Optional Country Country Enum - the desired country's country code.
Optional Email Cardholder email address. String
Optional Phone Cardholder phone number. String
Conditional - required if specified in AVSData.PostalCode(ServiceInformation) or if any other AVSData field is filled out. PostalCode Postal code String
Optional StateProvince State or Province String

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

 
Expected Parameter Description Data Type
Expected ActualResult Specifies the actual result of AVS from the service provider. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected AddressResult Specifies the result of AVS as it pertains to address matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected CardholderNameResult Specifies the result of AVS as it pertains to cardholder name matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected CityResult Specifies the result of AVS as it pertains to city matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected CountryResult Specifies the result of AVS as it pertains to country matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected PhoneResult Specifies the result of AVS as it pertains to phone matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected PostalCodeResult Specifies the result of AVS as it pertains to postal code matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association
Expected StateResult Specifies the result of AVS as it pertains to state matching. Enum - Match, No_Match, Not_Verified, No_Response_From_Card_Association

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 - NotSet = 0, Unknown = 1, OnPremises = 2, OffPremises = 3, HomeInternet = 4
Optional HardwareType Type of device running the application, if different from the value set in ServiceInformation. Enum - NotSet = 0, Unknown = 1, PC = 2, DialTerminal = 3, ElectronicCashRegister = 4, InStoreController = 5, Mainframe = 6, ThirdPartyDeveloper = 7, POSPort = 8, POSPartner = 9, TicketMachine = 10, ATM = 11, ScripDevice = 12, Telephone = 13, InitiatedCAT = 14, VirtualTerminal = 15, MobileBanking = 16, AdminTerminal = 17, HomeTerminal = 18, FuelMachine = 19, PersonalBanking = 20, PublicUtility = 21, Vending = 22, SelfService = 23, VoiceResponseUnit = 24, InteractiveTV = 25, PDA = 26, TerminalDevice = 27, Level1CAT = 28, Level2CAT = 29, Level3CAT = 30, MPOS = 31
Optional PINCapability Indicates support for cardholder Personal Identification Number (PIN), if different from the value set in ServiceInformation. Enum - NotSet = 0, Unknown = 1, PINSupported = 2, PINNotSupported = 3, PINVerifiedByDevice = 4, PINPadInoperative = 5
Optional ReadCapability Capability of the device to read cardholder data, if different from the value set in ServiceInformation. Enum - NotSet = 0, HasMSR = 1, NoMSR = 2, KeyOnly = 3, Chip = 4, ContactlessChip = 5, ContactlessMSR = 6, ECR = 7, VSCCapable = 8, RFIDCapable = 9, EmvICC = 10, MSREMVICC = 11, Unknown = 12, OCRReader = 13, BarCodeReader = 14, NotSpecified = 15, ARUIVR = 16, NoTerminal = 17, NFCCapable = 18, MSRKeyICC = 19, MSRKey = 20, KeyOnlySecure = 21, KeyOnlyNonSecure = 22

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 - NotSet = 0, Unknown = 1, OnPremises = 2, OffPremises = 3, HomeInternet = 4
Optional HardwareType Type of device running the application, if different from the value set in ServiceInformation. Enum - NotSet = 0, Unknown = 1, PC = 2, DialTerminal = 3, ElectronicCashRegister = 4, InStoreController = 5, Mainframe = 6, ThirdPartyDeveloper = 7, POSPort = 8, POSPartner = 9, TicketMachine = 10, ATM = 11, ScripDevice = 12, Telephone = 13, InitiatedCAT = 14, VirtualTerminal = 15, MobileBanking = 16, AdminTerminal = 17, HomeTerminal = 18, FuelMachine = 19, PersonalBanking = 20, PublicUtility = 21, Vending = 22, SelfService = 23, VoiceResponseUnit = 24, InteractiveTV = 25, PDA = 26, TerminalDevice = 27, Level1CAT = 28, Level2CAT = 29, Level3CAT = 30, MPOS = 31
Optional PINCapability Indicates support for cardholder Personal Identification Number (PIN), if different from the value set in ServiceInformation. Enum - NotSet = 0, Unknown = 1, PINSupported = 2, PINNotSupported = 3, PINVerifiedByDevice = 4, PINPadInoperative = 5
Optional ReadCapability Capability of the device to read cardholder data, if different from the value set in ServiceInformation. Enum - NotSet = 0, HasMSR = 1, NoMSR = 2, KeyOnly = 3, Chip = 4, ContactlessChip = 5, ContactlessMSR = 6, ECR = 7, VSCCapable = 8, RFIDCapable = 9, EmvICC = 10, MSREMVICC = 11, Unknown = 12, OCRReader = 13, BarCodeReader = 14, NotSpecified = 15, ARUIVR = 16, NoTerminal = 17, NFCCapable = 18, MSRKeyICC = 19, MSRKey = 20, KeyOnlySecure = 21, KeyOnlyNonSecure = 22
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 - NotSet = 0, None = 1, MSWrite = 2, ICC = 3
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 - NotSet = 0, NoEAuth = 1, PIN = 2, ESigAnalysis = 3, Biometrics = 4, Biographic = 5, EAuthInop = 6
Required for EMV PINMaxCharacters The PIN capture capability of the terminal. Enum - NotSet = 0, None = 1, P04 = 2, P05 = 3, P06 = 4, P07 = 5, P08 = 6, P09 = 7, P10 = 8, P11 = 9, P12 = 10
Required for EMV TerminalOperator The terminal operator. Enum - 0 = Customer operated, 1 = Card acceptor operated, 2 = Administrative
Required for EMV TerminalOutputCapability The terminal output capability of the terminal. Enum - NotSet = 0, None = 1, Print = 2, Display = 3, PrintDisplay = 4

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 - required when capturing a different amount than what was authorized. Amount Amount to capture if different from the authorized amount. Decimal
Conditional - required for Retail transactions. 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. Enum - NotSet = 0, Lodging = 1, Restaurant = 2, GiftShop = 3, HealthSpa = 4, BeautyShop = 5, ConventionFee = 6, TennisProShop = 7, GolfProShop = 8, RetailOther = 9
Conditional - required for MOTO transactions. ShipDate Date of goods shipment. DateTime
Optional TipAmount Tip amount, if not specified at the time of authorization. Decimal
Optional TransactionCode Specifies if a transaction should override the EVO duplicate charge check. Enum - NotSet, Override

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
 
Expected Parameter Description Data Type
Optional BatchId Batch identifier. String
Expected IndustryType The industry type of the transaction(s). Enum - NotSet = 0, MOTO = 1, Ecommerce = 2, Restaurant = 3, Retail = 4
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 - NotSet = 0, Yes = 1, No = 2
Conditional - expected for CaptureAll. TransactionSummaryData Summary of transaction data. Object

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

  • ReturnById
 
Required Parameter Description Data Type
Conditional - required when performing a partial return. Amount Specifies the amount to return. Decimal
Optional FeeAmount Specifies the fee amount associated with an authorization, such as convenience fees. Decimal
Conditional - required by ReturnById for PIN Debit transactions. TenderData Details about the card tender. Data Type
Optional TransactionCode Specifies if a transaction should override the EVO duplicate charge check. Enum - NotSet, Override

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

 
Required Parameter Description Data Type
Conditional - required if any one of the following must be provided:
  • CardData
  • PaymentAccountDataToken
  • SecurePaymentAccountData
CardData Card Data Object
Optional CardSecurityData Security data for card transactions, such as AVS and CVV. Object
Conditional - optional for eCommerce transactions, otherwise not present. EcommerceSecurityData eCommerce security elements. Object

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. Object
Required BankcardTenderData Contains transaction information such as card data, routing information, and additional data specific to the tender being processed. Object
Required BankcardTransactionData Contains transaction detail information. Object

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

 
Required Parameter Description Data Type
Optional AccountType Indicates the bank account type. Enum - NotSet = 0, SavingsAccount = 1, CheckingAccount = 2
Conditional - optional if BankcardService.AlternativeMerchantData is true. AlternativeMerchantData Alternative merchant data to appear on accountholder statements. Subject to Issuer discretion. Object
Conditional - required if prior authorization approval was obtained. ApprovalCode Approval code for this authorization. String
Optional BatchAssignment Specific batch number assignment, when allowed. String
Optional - only used if BatchAssignment is supported. BatchId Override for the default BatchId. String
Optional CashBackAmount Specifies a cash back amount for PIN Debit transactions. Decimal
Required CustomerPresent Presence of cardholder relative to the transaction point of service. Enum - NotSet = 0, Present = 1, Suspicious = 2, BillPayment = 3, Transponder = 4, MOTO = 5, VisaOpenNetworkTransaction = 6, VisaCardPresentStripeUnreadable = 7, MailFax = 8, Ecommerce = 9, TelARU = 10, MOTOCC = 11, VoiceResponse = 12
Conditional - required for Retail, Restaurant, and MOTO industry types. EmployeeId Clerk/cashier identifier. String
Required 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 - NotSet = 0, Keyed = 1, KeyedBadMagRead = 2, TrackDataFromMSR = 3, ChipReliable = 4, ChipUnreliable = 5, ContactlessMChipOrSmartCard = 6, ContactlessStripe = 7, TerminalNotUsed = 8, BarCode = 9, OCRReader = 10, VSCCapable = 11, ChipTrackDataFromRFID = 12, MSRTrackDataFromRFID = 13, NFCCapable = 14, Track2DataFromMSR = 15
Optional FeeAmount Specifies a fee amount associated with the authorization, such as convenience fees. Decimal
Optional GoodsType Type of goods purchased. Enum - NotSet = 0, DigitalGoods = 1, PhysicalGoods = 2
Required IndustryType OBSOLETE MerchantProfile must include IndustryType and cannot be overridden at the transaction level. Enum - NotSet = 0, MOTO = 1, Ecommerce = 2, Restaurant = 3, Retail = 4,
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
Required OrderNumber Order number as assigned by the merchant. String
Conditional - required if ServiceInformation.Tenders.PartialApprovalSupportType = 'Enabled'. Otherwise, not present. PartialApprovalCapable Indicates whether the merchant is capable of processing a partial approval for this transaction. Enum - NotSet = 0, Capable = 1, NotCapable = 2,
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
Optional TransactionCode Specifies if a transaction should override the EVO duplicate charge check. Enum - NotSet, Override

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
 
Expected 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 - optional for Credit transactions. CardType Type of card used in the transaction. 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 - NotSet = 0, Match = 1, NoMatch = 2, NotProcessed = 3, NoCodePresent = 4, ShouldHaveBeenPresent = 5, IssuerNotCertified = 6, Invalid = 7, NoResponse = 8, NotApplicable = 9
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. It is required for software companies to 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. 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 - NotSet = 0, Yes = 1, No = 2
Optional Resubmit Specifies whether resubmission is supported for PIN Debit transactions. Enum - NotSet = 0, Unspecified = 1, Permitted = 2, NotPermitted = 3
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

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
Conditional 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 - required for PIN Debit transactions. PINDebitReason Specifies the reason for the undo. Enum
Conditional - required if BankcardService.Tenders.PINDebitUndoTenderDataRequired is true. TenderData Details about the card tender. Object
Conditional TransactionCode Specifies if a transaction should override the EVO duplicate charge check. Enum - NotSet, Override

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
Required CardType Type of card used in the transaction. Enum
Conditional* Expire The 4-digit expiration date embossed on the front of a card. *Required for authorization, not required for settlement. String - Format: MM-YY
Required PAN Cardholder Primary Account Number embossed on the front of the card. String
Conditional - required if at least one track data is required for authorizations, unless card not present or keyed entry. Track1Data The actual data read from the magnetic stripe on a card. Application should strip Start and End Sentinels, LRC, and Track separators. String
Conditional - required if at least one track data is required for authorizations, unless card not present or keyed entry. Track2Data The actual data read from the magnetic stripe on a card. Application should strip Start and End Sentinels, LRC, and Track separators. String

Transactions submitted with card data that has been stored by a tokenization process not leveraging Snap* Platform Tokens must include the CardOnFileInfo fields. These indicators let the card issuer know whether this is the First or a Repeat transaction using the stored card data, whether the transaction was Merchant or Cardholder initiated, and provide the transaction ID from the original transaction that resulted in the card data being stored.

Required Parameter Description Data Type
Required PurchasedTokenization Merchants using the Snap Tokenization service must have the PurchasedTokenization flag set to “true”. The Snap service will set the CardOnFile and OriginalTransactionId fields on behalf of the merchant. Merchants must still set the InitiatedBy field. Boolean
Required CardOnFile Denotes whether this is the First or a Repeat transaction using the stored card data. If set to “First”, no other fields are required. If set to “Repeat”, InitiatedBy and OriginalTransactionId should be set in order to reduce transaction declines. Enum - First Repeat
Conditional - if no TransmissionNumber is present in the “First” transaction response, the OriginalTransactionId field may be left blank. OriginalTransactionId The OriginalTransactionId will be returned in responses in the TransmissionNumber field. The value from the “First” transaction must be used for all “Repeat” transactions. If no TransmissionNumber is present in the “First” transaction response, the OriginalTransactionId field may be left blank. String
Required InitiatedBy The InitiatedBy field can be set to one of two values: “Merchant” or “Cardholder”. “Merchant” would be used any time the transaction is run on behalf of the merchant, like an automated billing system. “Cardholder” is used any time the stored credentials are used on behalf of the cardholder, such as when purchasing a new item using the card on file. Enum - Merchant, Cardholder

Contains EMV data for the payment card.

 
Required Parameter Description Data Type
Required ApplicationId Identifies the application on the ICC as described in ISO/IEC 7816-5. Tag 9F06 (AID) String
Required ApplicationVersionNumber Version number assigned by the payment system for the application.Tag 9F09 String
Required 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
Required 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
Required 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
Required ApplicationUsageControl Indicates the issuer's specified restrictions on the geographic usage and services allowed for the application. Tag 9F07 String
Required 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
Required CardAuthenticationReliabilityIndex May be set and sent by the acquirer when the acquirer or issuer is inactive for card authentication. String
Required CardAuthenticationResultsCode An issuer-supplied code indicating card authentication results. String
Required 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
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. 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. Tag 9F26 String
Conditional - will be present if available from the terminal, and must be set if available. CryptogramInfromationData Indicates the type of cryptogram returned by the ICC (ARQC, AAC or TC) and the actions to be performed by the terminal. May be used in validating the cryptogram. Tag 9F27 String
Required CVMList Identifies the cardholder verification methods (CVMs) supported by the application. Tag 8E String
Required CVMResults Cardholder verification method (CVM) results indicating the results of the last CVM performed. Tag 9F34 String
Required InterfaceDeviceSerialNumber A unique and permanent serial number assigned to the interface device (IFD) by the terminal manufacturer. Tag 9F1E (IFD) String
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise optional. CashBackAmount Secondary amount associated with the transaction, representing a cashback amount. Tag 9F03 String
Required 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
Required 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
Required 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
Conditional - will be present if available from the terminal, and must be set if available. 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. May be used in validating the cryptogram. Tag 9F10 String
Required 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
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. LocalTransactionDate The local date on which the transaction was authorized. Tag 9A String - YYMMDD format
Required TerminalCapability Indicates the card data input, CVM, and security capabilities of the terminal. Tag 9F33 String
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. TerminalCountryCode Indicates the country of the terminal, represented according to ISO 3166. Tag 9F1A String
Required TerminalType Indicates the environment of the terminal, its communications capability, and its operational control. Tag 9F35 String
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. TerminalVerifyResult Status of the different functions as seen from the terminal. Tag 95 String
Required TransactionCategoryCode Defines the type of transaction for which authorization is being requested. Used in risk management. String
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. CurrencyCode Indicates the currency code of the transaction according to ISO 4217. Tag 5F2A String
Required SequenceNumber Counter maintained by the terminal and incremented by one for each transaction. Tag 9F41 String
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. TransactionType Indicates the type of the transaction, represented by the first two digits of the ISO 8583:1997 Processing Code. Tag 9C String
Conditional - must be present in a 0100, 0120, 0200 or 0220 message for an ICC chip transaction. Otherwise, optional. UnpredictableNumber Value to provide uniqueness to the generation of the cryptogram. Tag 9F37 String

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 - required in authorizations if CVDataInd = 'Provided', not used in settlement. 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. String - 3 or 4 digit number format
Optional CVDataProvided Indicates whether or not CV data provided. Recommended for card not present authorizations, not used in settlement. Enum - NotSet = 0, DeliberatelyBypass = 1, Provided = 2,
Optional IdentificationInformation Specifies identifying information about the tender, such as a magnetic stripe fingerprint. String
Conditional - required for PIN Debit transactions. KeySerialNumber Key serial number for DUK/PT PIN encryption. String
Conditional - required for PIN Debit transactions. PIN Encrypted PIN. String

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

 
Required Parameter Description Data Type
Conditional - required for Electronic Commerce transactions using VPAS, UCAF, or SET w/certificate. TokenData Contains actual data for token. VPAS or UCAF value must be in its original base64 encoded form. String
Conditional - required for Electronic Commerce transactions using VPAS, UCAF, or SET w/certificate. TokenIndicator Specifies VPAS, UCAF, or SET certificate S/N. Enum - NotSet = 0, VPAS = 1, UCAFWithData = 2, UCAFWithoutData = 3, AttemptedCardUnsupported = 4, AttemptedServiceUnavailable = 5, MasterPass = 6, ApplePay = 7, AndroidPay = 8, SamsungPay = 9, DiscoverProtectBuy = 10, AmexSafeKey = 11, JCBJSecure = 12, UPISecurePlus = 13
Optional XID Transaction identifier in its original, base64 encoded form for Electronic Commerce transactions w/VPAS. String

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 - required for IIAS transactions. HealthcareAmount Specifies the total amount of eligible healthcare items associated with the authorization. Decimal
Conditional - required for IIAS transactions. IIASDesignation Specifies merchants IIAS status. Enum - NotSet = 0, IIASVerified = 1, IIASExempt = 2
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

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 - required by some service providers. IpAddress The IP Address of the client application. 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 - required by some service providers. SessionId The Session Id of the application. If this value is set on the transaction and not required by the service provider, the data is not present on the transaction. String

Contains itemized tax information. This element is Optional.

 
Required Parameter Description Data Type
Required Amount Amount of tax applied. Decimal - up to four decimal places
Optional Rate Rate of tax applied. Decimal - 4 to 6 decimal places permitted
Required Type Type of tax applied. Enum - NotSet = 0, CityTax = 1, CountyTax = 2, CountyParishTax = 3, EnergyTax = 4, FederalTax = 5, EnvironmentalTax = 6, GoodsServicesTax = 7, HarmonizedTax = 8, LuxuryTax = 9, LocalSalesTax = 10, MunicipalTax = 11, OccupancyTax = 12, OtherTax = 13, QuebecSalesTax = 14, RoomTax = 15, StateLocalSalesTax = 16, StateProvincialGoodsTax = 17, StateSalesTax = 18, StateProvincialTax = 19, Unknown = 20, VAT = 21

Collection of itemized tax information. This element is Optional.

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

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

 
Required Parameter Description Data Type
Required 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. 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
Required 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

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

 
Required Parameter Description Data Type
Required 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 - required if DiscountAmount is specified. DiscountIncluded Indicates whether amount is inclusive of discount. Boolean
Optional ProductCode Line item product code. String
Required Quantity Quantity of item. Decimal
Required SequenceNumber Sequence number generated by CWS. String
Optional Tax Tax details for this line item. Object
Required TaxIncluded Indicates whether amount is inclusive of tax. Boolean
Optional UnitOfMeasure Units used to measure quantity. Enum - NotSet = 0, Acre = 1, AmpereHour = 2, Ampere = 3, Year = 4, TroyOunceOrApothecariesOunce = 5, Are = 6, AlcoholicStrengthByMass = 7, AlcoholicStrengthByVolume = 8, StandardAtmosphere = 9, TechnicalAtmosphere = 10, Bar = 11, BoardFoot = 12, BrakeHorsePower = 13, BillionEURTrillionUS = 14, DryBarrelUS = 15, BarrelUSPetroleumEtc = 16, Becquerel = 17, BritishThermalUnit = 18, BushelUS = 19, BushelUK = 20, CarryingCapacityInMetricTon = 21, Candela = 22, DegreeCelsius = 23, Hundred = 24, Centigram = 25, CoulombPerKilogram = 26, HundredLeave = 27, Centilitre = 28, Centiliter = 29, SquareCentimetre = 30, SquareCentimeter = 31, CubicCentimetre = 32, CubicCentimeter = 33, Centimetre = 34, Centimeter = 35, HundredPack = 36, CentalUK = 37, Coulomb = 38, MetricCarat = 39, Curie = 40, HundredPoundsCWTHundredWeightUS = 41, HundredWeightUK = 42, Decare = 43, TenDay = 44, Day = 45, Decade = 46, Decilitre = 47, Deciliter = 48, SquareDecimetre = 49, SquareDecimeter = 50, CubicDecimetre = 51, CubicDecimeter = 52, Decimetre = 53, Decimeter = 54, DozenPiece = 55, DozenPair = 56, DisplacementTonnage = 57, DramUS = 58, DramUK = 59, DozenRoll = 60, DrachmUK = 61, DecitonneCentnerMetric100KgQuintalMetric100Kg = 62, Pennyweight = 63, Dozen = 64, DozenPack = 65, DegreeFahrenheit = 66, Farad = 67, Foot = 68, SquareFoot = 69, CubicFoot = 70, Gigabecquerel = 71, GramOfFissileIsotope = 72, GreatGross = 73, GillUS = 74, GillUK = 75, DryGallonUS = 76, GallonUK = 77, GallonUS = 78, Gram = 79, Grain = 80, Gross = 81, GrossRegisterTon = 82, GigawattHour = 83, Hectare = 84, Hectobar = 85, HundredBox = 86, Hectogram = 87, HundredInternationalUnit = 88, Hectolitre = 89, Hectoliter = 90, MillionCubicMetre = 91, MillionCubicMeter = 92, Hectometre = 93, Hectometer = 94, HectolitreOfPureAlcohol = 95, HectoliterOfPureAlcohol = 96, Hertz = 97, Hour = 98, Inch = 99, SquareInch = 100, CubicInch = 101, Joule = 102, Kilobar = 103, Kelvin = 104, Kilogram = 105, KilogramPerSecond = 106, Kilohertz = 107, Kilojoule = 108, KilometrePerHour = 109, KilometerPerHour = 110, SquareKilometre = 111, SquareKilometer = 112, KilogramPerCubicMetre = 113, KilogramPerCubicMeter = 114, Kilometre = 115, Kilometer = 116, KilogramOfNitrogen = 117, KilogramNamedSubstance = 118, Knot = 119, Kilopascal = 120, KilogramOfPotassiumHydroxideCausticPotash = 121, KilogramOfPotassiumOxide = 122, KilogramOfPhosphorusPentoxidePhosphoricAnhydride = 123, KilogramOfSubstance90PercentDry = 124, KilogramOfSodiumHydroxideCausticSoda = 125, Kilotonne = 126, KilogramOfUranium = 127, KilovoltAmpere = 128, Kilovar = 129, Kilovolt = 130, KilowattHour = 131, Kilowatt = 132, Pound = 133, TroyPoundUS = 134, Leaf = 135, LitreOfPureAlcohol = 136, LiterOfPureAlcohol = 137, TonUKorLongTonUS = 138, Litre = 139, Liter = 140, Lumen = 141, Lux = 142, MegaLitre = 143, MegaLiter = 144, Megametre = 145, Megameter = 146, Megawatt = 147, ThousandStandardBrickEquivalent = 148, ThousandBoardFeet = 149, Millibar = 150, Millicurie = 151, Milligram = 152, Megahertz = 153, SquareMile = 154, Thousand = 155, Minute = 156, Million = 157, MillionInternationalUnit = 158, MilliardBillionUS = 159, Millilitre = 160, Milliliter = 161, SquareMillimetre = 162, SquareMillimeter = 163, CubicMillimetre = 164, CubicMillimeter = 165, Millimetre = 166, Millimeter = 167, Month = 168, Megapascal = 169, CubicMetrePerHour = 170, CubicMeterPerHour = 171, CubicMetrePerSecond = 172, CubicMeterPerSecond = 173, MetrePerSecondSquared = 174, MeterPerSecondSquared = 175, SquareMetre = 176, SquareMeter = 177, CubicMetre = 178, CubicMeter = 179, Metre = 180, Meter = 181, MetrePerSecond = 182, MeterPerSecond = 183, MegavoltAmpere = 184, MegawattHour1000KWH = 185, NumberOfArticles = 186, NumberOfBobbins = 187, NumberOfCells = 188, Newton = 189, NumberOfInternationalUnits = 190, NauticalMile = 191, NumberOfPacks = 192, NumberOfParcels = 193, NumberOfPairs = 194, NumberOfParts = 195, NumberOfRolls = 196, NetRegisterTon = 197, Ohm = 198, Ounce = 199, FluidOunceUS = 200, FluidOunceUK = 201, Pascal = 202, Piece = 203, ProofGallon = 204, DryPintUS = 205, PintUK = 206, LiquidPintUS = 207, QuarterOfAYear = 208, DryQuartUS = 209, QuartUK = 210, LiquidQuartUS = 211, QuarterUK = 212, RevolutionsPerMinute = 213, RevolutionsPerSecond = 214, HalfYear6Months = 215, Score = 216, Scruple = 217, Second = 218, Set = 219, ShippingTon = 220, Siemens = 221, MileStatuteMile = 222, ShortStandard7200Matches = 223, StoneUK = 224, TonUSOrShortTonUKUS = 225, KiloampereHourThousandAmpereHour = 226, TonneMetricTon = 227, TenPair = 228, ThousandCubicMetrePerDay = 229, ThousandCubicMeterPerDay = 230, TrillionEUR = 231, TonneOfSubstance90PercentDry = 232, TonOfSteamPerHour = 233, Volt = 234, Cord = 235, Weber = 236, Week = 237, WattHour = 238, Standard = 239, Watt = 240, SquareYard = 241, CubicYard = 242, Yard = 243, Bag = 244, Bale = 245, Box = 246, Bottle = 247, Can = 248, Case = 249, Carton = 250, Cylinder = 251, Diameter = 252, Hectokilogram = 253
Required UnitPrice Price per unit of line item. Decimal
Optional UPC Line item UPC code. String

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
Required Installments Installment data. Object
Required Interval Unit used in calculating the period. Enum - NotSet = 0, Day = 1, Week = 2, Month = 3, Year = 4
Required Period Number of intervals between each payment. Integer
Required StartDate Date when the recurring payments should be initiated. DateTime

Installment data. This element is Required.

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

Aggregate of tax information. This element is Optional.

 
Required Parameter Description Data Type
Required 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

Tax exemption indicator and number. This element is Optional.

 
Required Parameter Description Data Type
Required IsTaxExempt Indicates tax exempt status of the transaction. Enum - Exempt NotExemptTaxInfoProvided
Conditional - required if IsTaxExempt = 'Exempt' or 'NotExemptTaxInfoProvided'. TaxExemptNumber Indicates the tax exempt number for the transaction. String

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

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. Object
Expected NetTotals Total count and net amount of transactions for the entire batch independent of transaction class. Object
Optional PINDebitReturnTotals Total count and amount of PIN Debit returns. Object
Optional PINDebitSaleTotals Total count and amount of PIN Debit sales. Object
Optional ReturnTotals Total count and amount of returns for the entire batch independent of transaction class. Object
Optional SaleTotals Total count and amount of sales for the entire batch independent of transaction class. Object
Optional VoidTotals Total count and amount of voids for the entire batch independent of transaction class. 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.

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 - 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. Level2Data Aggregate of elements specific to Level 2/Purchase Card transactions. Object
Conditional - optional if service information indicates PurchaseCardLevel(ServiceInformation) = 'Level3'. LineItemDetails Collection of transaction line item details. Object
Conditional - required if MultiplePartialCapture (ServiceInformation) is 'true'. 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. Boolean
Optional ShippingData Customer shipping details. Object
Conditional TransactionCode Specifies if a transaction should override the EVO duplicate charge check. Enum - NotSet, Override

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

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

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

 
Required Parameter Description Data Type
Conditional - required for recurring or installment transactions. BillPayment Indicates that the transaction is one in a set of recurring or installment transactions. Enum - NotSet = 0, DeferredBilling = 1, SinglePayment = 2, Installment = 3, Recurring = 4
Conditional - required for installment transactions. CurrentInstallmentNumber Number of installment represented by this transaction. Integer
Conditional - required if BillPayment is set. ExistingDebt Indicates recurring or installment transaction is on existing debt. Enum - NotSet = 0, NotExistingDebt = 1, IsExistingDebt = 2
Optional RequestACI Authorization Characteristics Indicator. Identifies the request as potentially qualifying for the Visa CPS or MasterCard Merit programs. Enum - NotSet = 0, NotCPSMeritCapable = 1, IsCPSMeritCapable = 2, CPSMeritCapableIncAuth = 3, PremierCustomer = 4, RecurringInstallment = 5
Optional RequestAdvice Indicates whether to include advice on declined recurring payment transactions. Enum - NotSet = 0, NotCapable = 1, Capable = 2
Optional RequestCommercialCard Request commercial card status for the transaction. Enum - NotSet = 0, Disable = 1, Enable = 2
Conditional - required for installment transactions. TotalNumberOfInstallments Number of installments in the series. Integer

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 - optional if service information indicates PurchaseCardLevel(ServiceInformation) = 'Level3'. LineItemDetails Collection of transaction line item details. List
Conditional TransactionCode Specifies if a transaction should override the EVO duplicate charge check. Enum - NotSet, Override

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
Required IIASData Inventory Information Approval System (IIAS) data including amounts for Flexible Spending Account (FSA) eligible items. Object
Conditional - required when LineItemDetails are provided, otherwise optional if Service Information indicates PurchaseCardLevel (ServiceInformation) = 'Level2' or 'Level3'. Level2Data Aggregate of elements specific to Level 2/Purchase Card transactions. Object
Conditional - optional if Service Information indicates PurchaseCardLevel(ServiceInformation) = 'Level3'. LineItemDetails Collection of transaction line item details. Object
Conditional - optional if ManagedBilling(ServiceInformation) = 'true', otherwise not present. ManagedBilling Not currently supported.Configuration to setup and perform an automated recurring payment on the behalf of the merchant. Object
Conditional - optional when processing a recurring or installment MOTO or eCommerce transaction with a PIN Debit card without entering a PIN. PINlessDebitData Collection of transaction details related to PINless Debit cards. Object

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. Object

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 - NotSet = 0, Unsupported = 1, NewAccountInfoAvailable = 2, TryAgainLater = 3, DoNotTryAgainLater = 4, DoNotHonor = 5, TokenRequirementsNotFulfilled = 6
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 - NotSet = 0, NotImplemented = 1, PurchaseCard = 2, CorporateCard = 3, BusinessCard = 4, B2BSettlementEligible = 5, NonCommercialCard = 6, PurchaseCardDataUnsupported = 7, Unknown = 8, B2BLessOrEqualAuthClearing = 9, B2BEqualAuthClearing = 10
Optional ReturnedACI Provides information concerning the status of a transaction's CPS qualification. String