DebitSaleReqBlock1Type Complex Type

Namespace

http://Hps.Exchange.PosGateway

Diagram

Overview

DebitSaleReqBlock1Type

All

TrackData optional CardDataTypeTrackData Complex Type

Track data is the full magnetic stripe data.

Note: Only track 2 data is supported for debit transactions.

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.

Amt amtTypeGlobal Simple Type

The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.

GratuityAmtInfo optional amtTypeGlobal Simple Type

Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.

PinBlock optional pinBlockType Simple Type

PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.

Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.

TokenValue optional xs:string

Token used to replace payment method data (track data and optionally PIN block).

Note: Multi-use tokens are not supported on debit transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product and are primarily used in eCommerce situations.

CashbackAmtInfo optional amtTypeGlobal Simple Type

Cashback amount information; this defines the portion of the total amount provided as part of this request that was specifically for cashback. This is informational only and will not alter the amount processed as part of the transaction.

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.

AllowDup optional booleanType Simple Type

This is important in cases where the client processes a large number of similar transactions in a very short period of time; sending "Y" will skip duplicate checking on this transaction.

LodgingData optional LodgingDataType Complex Type

Lodging data

All

PrestigiousPropertyLimit optional prestigiousPropertyType Simple Type

This field is used by merchants participating in the Prestigious Lodging Program; see the associated Type enumerations for specific values supported.

Note: This field has been deprecated and should no longer be used.

NoShow optional booleanType Simple Type

Indicates that this charge is due to a "no show" on a reservation

AdvancedDepositType optional advancedDepositTypeType Simple Type

For AMEX only. Indicates the advanced deposit type; see the associated Type enumerations for specific values supported.

LodgingDataEdit optional LodgingDataEditType Complex Type

Lodging extra charge indicators; common group of elements that provide additional details specific to lodging transactions that may be required in certain situations as determined by the brands

All

FolioNumber optional folioNumberType Simple Type

Lodging system generated value used to group and manage charges during a stay

Duration optional xs:int

Duration of stay in days

The stay Duration range is from 1 to 99.

CheckInDate optional xs:date

Date of check-in

CheckOutDate optional xs:date

Date of check-out

Rate optional amtTypeGlobal Simple Type

Daily room rate

Note: This field is required by AMEX.

RoomTax optional amtTypeGlobal Simple Type

Total Room Tax Charges. For Feature Use

ExtraCharges optional ExtraChargesDataType Complex Type

Indicates the types of extra charges included in the extra charge amount information and the total transaction amount

ExtraChargeAmtInfo optional amtTypeGlobal Simple Type

Total extra charge amount information; this defines the portion of the total amount provided as part of this request that was specifically for lodging extra charges. This is informational only and will not alter the amount processed as part of the transaction.

ExtraChargeDetailAmtInfo optional ExtraChargeDetailAmtInfoDataType Complex Type

Defines the individual amounts of extra charges included in the extra charge amount information and the total transaction amount.

ExtraChargesDetailAmountInfo can be used by Asia Pacific merchants only.

PreferredCustomer optional booleanType Simple Type

For MasterCard only. Indicates whether or not the customer has a preferred status.

AllowPartialAuth optional booleanType Simple Type

Indicates whether or not a partial authorization is supported by terminal; the default is N.

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.

AdditionalTxnFields optional AdditionalTxnFieldsType Complex Type

A common group of optional fields that are supported in several different transaction types for Merchant use.

All

Description optional descriptionType Simple Type

Free-form description field. This must not contain sensitive information.

InvoiceNbr optional Restriction of xs:string

Used to log the invoice number on transactions that are not eCommerce.

CustomerID optional customerIDType Simple Type

Used to log Merchant specific customer identification.

Note: For GETI check transactions, this is sent in the CUSTOM3 field.

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

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.

AccountType optional accountTypeType Simple Type

Indicates the type of account provided; see the associated Type enumerations for specific values supported.

MessageAuthenticationCode optional xs:string

A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.

PosSequenceNbr optional xs:string

POS sequence number for Canadian Debit transactions.

Used By

Block1 Element

Source

<xs:complexType name="DebitSaleReqBlock1Type" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:all>
    <xs:element name="TrackData" type="CardDataTypeTrackData" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Track data is the full magnetic stripe data.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> Only track 2 data is supported for debit transactions.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="Amt" type="amtTypeGlobal">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="GratuityAmtInfo" type="amtTypeGlobal" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="PinBlock" type="pinBlockType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="TokenValue" type="xs:string" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Token used to replace payment method data (track data and optionally PIN block).</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> Multi-use tokens are not supported on debit transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product and are primarily used in eCommerce situations.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CashbackAmtInfo" type="amtTypeGlobal" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Cashback amount information; this defines the portion of the total amount provided as part of this request that was specifically for cashback. This is informational only and will not alter the amount processed as part of the transaction.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CardHolderData" type="CardHolderDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Card holder data</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="AllowDup" type="booleanType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">This is important in cases where the client processes a large number of similar transactions in a very short period of time; sending "Y" will skip duplicate checking on this transaction.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="LodgingData" type="LodgingDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Lodging data</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="AllowPartialAuth" type="booleanType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Indicates whether or not a partial authorization is supported by terminal; the default is N.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="EncryptionData" type="EncryptionDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">If the supplied card data was encrypted, this must be supplied.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="AdditionalTxnFields" type="AdditionalTxnFieldsType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">A common group of optional fields that are supported in several different transaction types for Merchant use.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="EMVChipCondition" type="emvChipConditionType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">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.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">
              The values can indicate multiple factors:
              <ul><li>The EMV chip read failed</li><li>Did the previous attempt fail</li></ul></p>
          <p xmlns="http://Hps.Exchange.PosGateway">See enumerations for specific values supported</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="TagData" type="TagDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">EMV or Non-EMV tag data in TLV format</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="AccountType" type="accountTypeType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Indicates the type of account provided; see the associated Type enumerations for specific values supported.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="MessageAuthenticationCode" type="xs:string" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="PosSequenceNbr" type="xs:string" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">POS sequence number for Canadian Debit transactions.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
  </xs:all>
</xs:complexType>