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). Optional.

Note: Reference the ServiceInformation.BankcardServices.AVSData object returned by GetServiceInformation to determine which fields below must be set.

Parameter Description Data Type
CardholderName Cardholder name embossed on the front of the card. Conditional, required if specified in AVSData.CardholderName (ServiceInformation). String
City City. Conditional, required if specified in AVSData.City (ServiceInformation). String
Country Country. Conditional, required if specified in AVSData.Country (ServiceInformation). Enum
Email Cardholder email address. Conditional, reference AVS/Email service configuration for level of service provider support. String
Phone Cardholder phone number. Conditional, required if specified in AVSData.Phone (ServiceInformation). String
PostalCode Postal code. Conditional, required if specified in AVSData.PostalCode (ServiceInformation). String
StateProvince State or Province. Conditional, required if specified in AVSData.StateProvince (ServiceInformation). Enum
Street Street address. Conditional, required if specified in AVSData.Street (ServiceInformation). String

 


 

AVSResult

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

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

 


 

BankcardApplicationConfigurationData

Overrides application data for the specific transaction. Optional.

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

 


 

BankcardCapture

Contains information for capturing Bankcard transactions (Credit and PIN Debit). Required.

BankcardCapture provides differenceData support for the following Transaction Processing operations:

Parameter Description Data Type
Amount Amount to capture if different from the authorized amount. Conditional, required when capturing a different amount than what was authorized. Decimal
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. Conditional, required for Retail transactions. Enum
ShipDate Date of goods shipment. Conditional, required for MOTO transactions. DateTime
TipAmount Tip amount, if not specified at the time of authorization. Optional. Decimal

 


 

BankcardCaptureResponse

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

Note: BankcardCaptureResponse inherits the data elements in Response.

BankcardCaptureResponse is returned by the following Transaction Processing operation signatures:

Parameter Description Data Type
BatchId Batch identifier. Optional. String
IndustryType The industry type of the transaction(s). Expected. Enum
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. Optional. Enum
TransactionSummaryData Summary of transaction data. Conditional, expected for CaptureAll and CaptureSelective. Object

 


 

BankcardReturn

Contains information for returning Bankcard transactions (Credit and PIN Debit). Required.

BankcardReturn provides differenceData support for the following Transaction Processing operations:

Parameter Description Data Type
Amount Specifies the amount to return. Conditional, required when performing a partial return. Decimal
FeeAmount Specifies the fee amount associated with an authorization, such as convenience fees. Optional. Decimal
TenderData Details about the card tender. Conditional, required by ReturnById for PIN Debit transactions. Object

 


 

BankcardTenderData

Contains information about the Bankcard transaction tender data. Required.

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

 


 

BankcardTransaction

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

Note: BankcardTransaction inherits the data elements in Transaction.

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

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

 


 

BankcardTransactionData

Contains information about the Bankcard transaction data. Required.

Parameter Description Data Type
AccountType Indicates the bank account type. Optional. Enum
AlternativeMerchantData Alternative merchant data to appear on accountholder statements. Subject to Issuer discretion. Conditional. Object
ApprovalCode Approval code for this authorization. Conditional, required if prior authorization approval was obtained. String
BatchAssignment Specific batch number assignment, when allowed. Optional. String
BatchId Override for the default BatchId. Only used if BatchAssignment is supported. Optional. String
CashBackAmount Specifies a cash back amount for PIN Debit transactions. Optional. Decimal
CustomerPresent Presence of cardholder relative to the transaction point of service. Required. Enum
EmployeeId Clerk/cashier identifier. Conditional, required for Retail, Restaurant, and MOTO industry types. String
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). Required. Enum
FeeAmount Specifies a fee amount associated with the authorization, such as convenience fees. Optional. Decimal
GoodsType Type of goods purchased. Optional. Enum
IndustryType OBSOLETE. MerchantProfile must include IndustryType and should not be overridden at the transaction level. Enum
InternetTransactionData Gets or sets the internet transaction data value. Optional. Object
InvoiceNumber Informational field used to track invoice/receipt number. Optional. String
IsPartialShipment Indicates whether or not the transaction represents a partial shipment. Optional. Boolean
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. Optional. Boolean
LaneId Identifies the cashier location at which the transaction occurred. Optional. String
OrderNumber Order number as assigned by the merchant. Required. String
PartialApprovalCapable Indicates whether the merchant is capable of processing a partial approval for this transaction. Conditional, required if ServiceInformation.Tenders.PartialApprovalSupportType = 'Enabled'. Otherwise, not present. Enum
ScoreThreshold Specifies the Magensa MagnePrint® score threshold used in accepting or declining certain transactions. Optional. String
SignatureCaptured Specifies whether the cardholder provided a signature for the transaction. Required. Boolean
TerminalId Gets or sets the internet transaction data value. Optional. String
TipAmount Tip amount, if known at the time of authorization. Optional. Decimal

 


 

BankcardTransactionResponse

Response to the Bankcard transaction (Credit and PIN Debit). 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:

Parameter Description Data Type
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. Expected. Decimal
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. Expected. String
AVSResult Collection of AVS response data. Optional. Object
BatchId Batch Identifier. Optional. String
CardLevel Code returned by the card association that indicates the type of card used by the customer. Optional. String
CardType Type of card used in the transaction. Optional for Credit transactions. Optional. Enum
CashBackAmount The approved cash back amount. Optional. Decimal
CurrencyCode Specifies the settled currency code. Enum
CVResult Response code returned by the card issuer indicating the result of Card Verification (CVV2/CVC2/CID). Optional. Enum
DowngradeCode Downgrade reason. Optional. String
EMVData Data from the provider that needs to be sent back to the chip reader.  Optional. String
ExchangeRate Specifies the currency exchange rate. Decimal
FeeAmount Fee amount charged for the transaction. Optional. Decimal
FinalBalance The account balance after the transaction. Optional. Decimal
MaskedPAN The cardholder's PAN in masked format. Expected.

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 NAB Velocity 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
OrderId The order id generated by CWS. This value is often used by service providers for transaction correlation. Optional. String
PaymentAccountDataToken Token specified by a tokenization (offsite payment account data storage) service provider, used to retrieve securely stored payment account data. Conditional if any one of the following must be provided:
  • CardData
  • SecurePaymentAccountData
  • Tender-specific payment account data
String
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. Optional. Enum
Resubmit Specifies whether resubmission is supported for PIN Debit transactions. Optional. Enum
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. Optional. String
SettlementDate Settlement date. Optional. DateTime

 


 

BankcardUndo

Contains information for undoing (voiding) Bankcard transactions (Credit and PIN Debit). Required.

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

Parameter Description Data Type
CreditUndoReason Specifies a reason for the Undo.  Conditional (provider) Enum
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
PINDebitReason Specifies the reason for the undo. Conditional, required for PIN Debit transactions. Enum
TenderData Details about the card tender. Conditional, required if BankcardService.Tenders.PINDebitUndoTenderDataRequired is true. Object

 


 

CardData

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

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

 


 

CardSecurityData

Contains security information for the payment card. Conditional, required for PIN Debit transactions.

Parameter Description Data Type
AVSData Cardholder address data for Address Verification System (AVS). Optional. Object
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. Conditional, required in authorizations if CVDataInd = 'Provided', not used in settlement. String
CVDataProvided Indicates whether or not CV data provided. Optional, but recommended for card not present authorizations, not used in settlement. Enum
EMVChipCondition Indicates failure information about the chip and reader. Conditional. Only used when an EMV card can't be read by the reader.  Indicates how many failures there have been.   Enum
EMVData EMVData from the chip reader. String
IdentificationInformation Specifies identifying information about the tender, such as a magnetic stripe fingerprint. Optional. String
KeySerialNumber Key serial number for DUK/PT PIN encryption. Conditional, required for PIN Debit transactions. String
PIN Encrypted PIN. Conditional, required for PIN Debit transactions. String

 


 

EcommerceSecurityData

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

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

 


 

IIASData

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

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

 


 

InternetTransactionData

Contains information about the internet connection. Conditional, required by some service providers. If this value is set on the transaction and not required by the service provider, the data will not be present on the transaction.

Parameter Description Data Type
IpAddress The IP Address of the client application. Conditional, required by some service providers. If this value is set on the transaction and not required by the service provider, the data will not be present on the transaction. String
SessionId The Session Id of the application. Conditional, required by some service providers. If this value is set on the transaction and not required by the service provider, the data will not be present on the transaction. String

 


 

ItemizedTax

Contains itemized tax information. Optional.

Parameter Description Data Type
Amount Amount of tax applied. Required. Decimal
Rate Rate of tax applied. Optional. Decimal
Type Type of tax applied. Required. Enum

 


 

ItemizedTaxes

Collection of itemized tax information. Optional.

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

 


 

Level2Data

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

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

 


 

LineItemDetail

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

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

 


 

ManagedBilling

Configuration to setup and perform an automated recurring payment on behalf of the merchant. Conditional, optional if ManagedBilling (ServiceInformation) = 'true', otherwise not present.

Note: Managed Billing is not currently supported.

Parameter Description Data Type
DownPayment Amount the cardholder is initially paying towards the purchase. Optional. Decimal
Installments Installment data. Object
Interval Unit used in calculating the period. Required. Enum
Period Number of intervals between each payment. Required. Integer
StartDate Date when the recurring payments should be initiated. Required. DateTime

 


 

ManagedBillingInstallments

Installment data. Required.

Note: Managed Billing is not currently supported.

Parameter Description Data Type
Amount Amount the cardholder should be billed in each installment. Required. Decimal
Count Number of times the cardholder should be billed. Required. Integer

 


 

Tax

Aggregate of tax information. Optional.

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

 


 

TaxExempt

Tax exemption indicator and number. Optional.

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

 


 

Totals

Contains net amount and total count. Required.

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

 


 

TransactionSummaryData

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

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

 

Updated: 5/24/16 ~DS

Comments