Block1 Element

Description

Contains a series of required and optional elements

CardData and PaymentMethodKey are mutually exclusive, but it is required that one of these fields be provided.

Namespace

http://Hps.Exchange.PosGateway

Type

CreditIPQueryBlock1Type Complex Type

Diagram

Overview

Block1 CreditIPQueryBlock1Type Complex Type

Contains a series of required and optional elements

CardData and PaymentMethodKey are mutually exclusive, but it is required that one of these fields be provided.

All

CardData optional CardDataType Complex Type

A common element used in several different transactions for supplying payment method information.

This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.

Sequence

Choice

TrackData CardDataTypeTrackData Complex Type

Track data is the full magnetic stripe data.

Note: TrackData is unique in that it has an attribute "method" that is used to indicate how the associated data was obtained.

method optional CardDataTypeTrackDataMethod Simple Type

Indicates the method by which the track data was obtained; see the associated Type enumerations for specific values supported

Note: If not provided, the method is assumed to be a typical card swipe.

ManualEntry

This is typically manually entered card data, but can be used in any case where only the card number is used rather than the full track.

All

CardNbr cardNbrType Simple Type

Card number; also referred to as Primary Account Number (PAN)

ExpMonth monthTypeExp Simple Type

Card expiration month

ExpYear Restriction of yearType Simple Type

Card expiration year

CardPresent optional booleanType Simple Type

Indicates whether or not the card was present at the time of the transaction

ReaderPresent optional booleanType Simple Type

Indicates whether or not a reader was present at the time of the transaction

CVV2 optional Restriction of cvv2Type Simple Type

CVV Number ("Card Verification Value"); 3 digits on VISA, MasterCard, Discover and UnionPay and 4 on American Express.

CVV numbers are also known as CSC numbers ("Card Security Code"), as well as CVV2 numbers, which are the same as CVV numbers, except that they have been generated by a 2nd generation process.

Note: This field is not used for EBT transactions.

CVV2Status optional cvv2Status Simple Type

Indicates why the CVV2 value was not provided; see the associated Type enumerations for specific values supported.

Note: This field is not used for EBT transactions.

TokenData

This is used when the card number from a previous transaction has been tokenized. This supports both multi-use and single-use tokens.

All

TokenValue xs:string

Multi-use or single-use token; used as a reference to a payment method for this transaction

ExpMonth optional monthType Simple Type

Card expiration month

Note: If expiration month and year are provided, they will be used for processing the transaction rather than the stored values associated with the provided token. This is for the current transaction only and will not be stored for future use.

ExpYear optional Restriction of yearType Simple Type

CardPresent optional booleanType Simple Type

Indicates whether or not the card was present at the time of the transaction

ReaderPresent optional booleanType Simple Type

Indicates whether or not a reader was present at the time of the transaction

CVV2 optional Restriction of cvv2Type Simple Type

CVV Number ("Card Verification Value"); 3 digits on VISA, MasterCard, Discover and UnionPay and 4 on American Express.

CVV numbers are also known as CSC numbers ("Card Security Code"), as well as CVV2 numbers, which are the same as CVV numbers, except that they have been generated by a 2nd generation process.

Note: This field is not used for EBT transactions.

CVV2Status optional cvv2Status Simple Type

Indicates why the CVV2 value was not provided; see the associated Type enumerations for specific values supported.

Note: This field is not used for EBT transactions.

EncryptionData optional EncryptionDataType Complex Type

If the supplied card data was encrypted, this must be supplied.

All

DataFormat optional encryptedDataFormatType Simple Type

EncryptionDataFormat is an optional field to be used for encryption Version "05" to define the encryption encoding format

EncryptionDataFormat 1 Denotes the CardData sent to PORTICO is Binary

EncryptionDataFormat 2 Denotes the CardData sent to PORTICO is ASCII

Version encryptionVersionType Simple Type

The encryption version used on the supplied data.

For PAN encryption, use version "02" or "04" for Heartland E3 encryption. This requires the client to parse the E3 MSR output. The encrypted PAN is passed in the card data element as the manual entry card number. The KTB must be provided as part of the encryption data. If sending an encrypted CVV2, use version "04" which expects the PAN and CVV2 to be encrypted.

For PAN encryption, use version "05" for TDES DUKPT encryption with and without CVV encryption. This requires the client to parse the output. The encrypted PAN is passed in the card data element as the manual entry card number. The KSN must be provided as part of the encryption data.

For track encryption, use version "01", "02", or "04" for Heartland E3 encryption. Version "01" will not require parsing and it will not require additional fields in the encryption data, but the full E3 MSR output must be passed in the card data element as track data. Version "02" and "04" requires the client to parse the E3 MSR output. The KTB must be provided as part of the encryption data. In addition, the client must parse the data specific to either encrypted track 1 or track 2 and provide this in the card data element as track data as well as supply the track number as EncryptedTrackNumber.

For track encryption, use either version "03" for AES encryption with DUKPT, or "05" for TDES encryption with DUKPT. The "03" option supports the IdTECH card readers. The "05" option will work with any device that supports TDES with DUKPT data encryption per AINSI 9.24-1. Both options require the client to parse reader output. The KSN must be provided as part of the encryption data. In addition, the client must parse the data specific to either encrypted track 1 or track 2 and provide this in the card data element as track data as well as supply the track number as EncryptedTrackNumber.

For track encryption "05" is used for TDES encryption with DUKPT. The "05" option will work with any device that supports TDES with DUKPT data encryption per ANSI 9.24-1. Both options require the client to parse reader output. The KSN must be provided as part of the encryption data. In addition, the client must parse the data specific to either encrypted track 1 or track 2 and provide this in the card data element as track data, as well as supply the track number as EncryptedTrackNumber.

EncryptedTrackNumber optional encryptedTrackNumberType Simple Type

Required for encryption version "02","03","04" and "05"; indicates which track is being supplied encrypted (i.e. "1" or "2").

KTB optional encryptionKTBType Simple Type

Required for encryption version "02" or "04"; the Key Transmission Block (KTB) used at the point of sale.

KSN optional encryptionKSNType Simple Type

Required for encryption version "03" and "05"; the Key Serial Number (KSN) used at the point of sale.

TokenRequest optional booleanType Simple Type

This is used to request the gateway to return a multi-use token for the supplied card data. If a token is provided in the card data and this flag is set, it will be echoed in the response.

TokenParameters optional TokenParametersType Complex Type

Parameters allowing the client to control aspects of how a requested multi-use token is generated.

Not Applicable for Reward Cash transactions.

All

Mapping optional TokenMappingType Simple Type

This indicates the type of token to return; see the associated Type enumerations for specific values supported.

Note: If not supplied, "CONSTANT" is assumed. This means that the same token will be returned for the same card data.

Amt amtTypeGlobal Simple Type

Amount

CPCReq optional booleanType Simple Type

This is used to request the issuer to return whether or not the supplied card is a commercial card

Note: See the CPCInd in the corresponding response transaction detail.

CardHolderData optional CardHolderDataType Complex Type

Card holder data

All

CardHolderFirstName optional firstNameType Simple Type

First name

CardHolderLastName optional lastNameType Simple Type

Last name

CardHolderAddr optional addrType Simple Type

Address

CardHolderCity optional cityType Simple Type

City

CardHolderState optional stateType Simple Type

State

CardHolderZip optional zipType Simple Type

Zip or postal code; see the associated Type pattern for restrictions.

Note: Canadian postal codes should be sent in the format "A0A0A0".

CardHolderPhone optional phoneType Simple Type

Phone number; see the associated Type pattern for restrictions.

CardHolderEmail optional emailType Simple Type

Email address

CardHolderLanguage optional languageIndicatorType Simple Type

CardHolder preferred language.

Note:This field is required for Canadian merchants.

PaymentMethodKey optional guidType Simple Type

Unique key generated by PayPlan associated with a stored payment method

Note: When using a key, card data should not be sent. However, stored customer data can be overridden using the card holder data.

Ecommerce optional eCommerceType Simple Type

Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.

EMVData optional EMVDataType Complex Type

When processing with an EMV capable client, this element may need to be provided. It consists of certain online authentication data or the reason for not utilizing the EMV capabilities. EMV tag data should be sent in the separate TagData field.

All

EMVTagData optional emvTagDataType Simple Type

EMV tag data in TLV format.

Note: This field has been obsoleted.See the TagData field for the alternative.

EMVChipCondition optional emvChipConditionType Simple Type

This must be provided when the POS was not able to successfully communicate to the chip card and was required to fall back to a magnetic stripe read on an EMV capable terminal.

The values can indicate multiple factors:

The EMV chip read failed
Did the previous attempt fail

See enumerations for specific values supported

PINBlock optional pinBlockType Simple Type

Chip card PIN block for online authentication

TagData optional TagDataType Complex Type

EMV or Non-EMV tag data in TLV format

All

TagValues optional Extension of xs:string

This field holds the tag data values.

source required Restriction of xs:string

This field specifies the source of the tag data value. It can be either chip or msd.

IPTerms optional IPTermsReqDataType Complex Type

The IPTerms block include information regarding the installment Program.

For Visa Installments Service (VIS), multiple plans are returned in the response. The VISOptions block includes additional filter options for the returned plans.

All

Program programType Simple Type

Available to merchants in Asia Pacific, Mexico, and Canada.

For merchants in Canada, use VIS.

Valid values include:

mIPP
SIP
VIS

VISPlanOptions optional VISPlanOptionsType Complex Type

The VISOptions block includes filter criteria for installment plans requested from Visa Installments Service (VIS)

All

ReturnAllEligiblePlans optional xs:boolean

By default only two eligible plans are returned for the VIS Program. When sent as True all eligble plans are returned, and the merchant may choose which plans to present to the customer.

PlanType optional PlanOptionType Simple Type

Indicates whether the installment plans returned should be Customer Funded or Merchant Funded.

Valid values include:

MERCHANT_FUNDED
CONSUMER_FUNDED
ANY

MaxTermMonths optional xs:int

Sets the maximum number of months for the installment plan. Used only when PlanType is MERCHANT_FUNDED.

AmountThreshold optional xs:int

Compared to the Amt value and used to determine whether installment plans are returned in the order of the longest duration (Amt is greater than or equal to AmountThreshold) or shortest duration (Amt is less than AmountThreshold).

Note: While the Amt element value is sent as a decimal (e.g. 100.00), the AmountThreshold element is an integer value with an implied decimal position based on local currency (e.g. 10000).

Source

<xs:element name="Block1" type="CreditIPQueryBlock1Type" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:annotation>
    <xs:documentation>
      <p xmlns="http://Hps.Exchange.PosGateway">Contains a series of required and optional elements</p>
      <p xmlns="http://Hps.Exchange.PosGateway">CardData and PaymentMethodKey are mutually exclusive, but it is required that one of these fields be provided.</p>
    </xs:documentation>
  </xs:annotation>
</xs:element>