NTRSCreateTokenReqBlock1Type Complex Type

Namespace

http://Hps.Exchange.PosGateway

Diagram

Overview

NTRSCreateTokenReqBlock1Type

All

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

ConsumerId optional Restriction of xs:string

Unique token requestor specific consumer identifier (e.g. wallet account ID).

NTRSDeviceData NTRSDeviceDataType Complex Type

Data related to the user's browser or mobile device.

All

NTRSDeviceType optional Restriction of xs:string

The type of the user's browser or mobile device. It has pre-defined values.

Valid values PHONE, TABLET, PHONE_TABLET, PC, WATCH, TV, WEARABLE_DEVICE, AUTOMOBILE_DEVICE, SERVER, CARD, STICKER, DEVICE_PERIPHERAL, TAG, JEWELRY, FASHION_ACCESSORY, GARMENT, DOMESTIC_APPLIANCE, MEDIA_GAMING_DEVICE, OTHER

NTRSDevicePlatform optional Restriction of xs:string

The operating system of the user's browser or mobile device

Valid values ANDROID, IOS, WINDOWS, BLACKBERRY, TIZEN, WEB, PAGARE_EMBEDDED_OS, ANDROID_WEAR, EMBEDDED_OS, OTHER

OsVersion optional Restriction of xs:string

The version of the operating system of the user's browser or mobile device.

NTRSDeviceLanguage optional Restriction of xs:string

The language that the application communicates with the cardholder.

NTRSDeviceLocale Restriction of xs:string

The language that the application communicates with the cardholder. It is based on BCP 47 standard. The language must be lowercase and the country must be uppercase. The language and country should be separated using a hyphen (-)

NTRSDeviceName optional Restriction of xs:string

The name of the target provisioned device

NTRSDeviceLocation optional Restriction of xs:string

The latitude and longitude coordinates of the user's browser or mobile device location (no decimals provided)

NTRSDeviceLocationExtended optional Restriction of xs:string

The latitude and longitude coordinates of the target device location including up to two decimal places

NTRSDevicePhoneNumber optional Restriction of xs:string

The telephone number or the last few digits of the telephone number

NTRSDeviceIp optional Restriction of xs:string

The IP address of the user's browser or mobile device

Brand optional Restriction of xs:string

The brand of the user's browser or mobile device

Manufacturer optional Restriction of xs:string

The version of the operating system of the user's browser or mobile device

Model optional Restriction of xs:string

The model of the user's browser or mobile device

NetworkType optional Restriction of xs:string

The type of network

Vald values WIFI, CELLULAR, GPS, OTHER, DSL

ImeiNumber optional Restriction of xs:string

The IMEI number of the device

NTRSDeviceTimeZone optional Restriction of xs:string

The time zone of the user's browser or mobile device

WalletAccountEmail Restriction of xs:string

The email address of the client that is linked to his wallet account login

NTRSRiskData optional NTRSRiskDataType Complex Type

Risk related data. It SHOULD NOT be sent if the CardPresent = False.

All

NTRSWalletData optional NTRSWalletDataType Complex Type

Risk data of the wallet.

All

WalletScore optional Restriction of xs:long

The score of the wallet.

WalletAccountLength optional Restriction of xs:long

The time in days that the wallet account has been in use.

WalletTransactions optional Restriction of xs:long

The number of transactions performed with the wallet in the last 12 months.

WalletNameMatchesCardholderName optional Restriction of xs:boolean

It indicates if the name of the wallet account holder and the name of the cardholder match or not..

NTRSCardData optional NTRSCardDataDataType Complex Type

Risk data of the card.

All

CardScore optional Restriction of xs:long

The score of the card.

CardUsageLength optional Restriction of xs:long

The time in days that the card has been in use.

NTRSDeviceData optional NTRSDeviceDataDataType Complex Type

NTRS device risk data.

All

NTRSDeviceScore optional Restriction of xs:long

The score of the trustworthiness of the device.

NTRSDeviceUseLength optional Restriction of xs:long

The time in days that the device has been in use.

TokensOnDevice optional Restriction of xs:long

The number of tokens on the physical device.

NTRSDeviceCountry optional Restriction of xs:string

The country in which the device is used.

NTRSUserData optional NTRSUserDataDataType Complex Type

Risk data of the user.

All

UserAccountScore optional Restriction of xs:long

The score of the trustworthiness of the device user’s account.

UserAccountUsageLength optional Restriction of xs:long

The time in days that the user account has been in use.

UserTokens optional Restriction of xs:long

The number of the tokens owned by the user.

UserWallets optional Restriction of xs:long

The number of the wallets owned by the user.

UserCountry optional Restriction of xs:string

It indicates the country of the user account.

NewlyAdded optional Restriction of xs:boolean

True means that the user added the card on file during the current provisioning attempt.

DaysOnFile optional Restriction of xs:long

The time in days that the card has been on file.

CardHolderData optional CardHolderDataDataType Complex Type

Cardholder-related data.

All

CardHolderFirstName optional Restriction of xs:string

The firstname of the cardholder.

CardHolderLastName optional Restriction of xs:string

The lastname of the cardholder.

CardHolderAddr optional Restriction of xs:string

Billing address of the cardholder.

CardHolderCity optional Restriction of xs:string

City.

CardHolderState optional Restriction of xs:string

State.

CardHolderZip optional Restriction of xs:string

Postal Code.

CardHolderCountryCode optional Restriction of xs:string

Country Code.

Used By

Block1 Element

Source

<xs:complexType name="NTRSCreateTokenReqBlock1Type" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:all>
    <xs:element name="CardData" type="CardDataType" minOccurs="1">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">A common element used in several different transactions for supplying payment method information.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">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.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="ConsumerId" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Unique token requestor specific consumer identifier (e.g. wallet account ID).</p>
        </xs:documentation>
      </xs:annotation>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:maxLength value="36" />
        </xs:restriction>
      </xs:simpleType>
    </xs:element>
    <xs:element name="NTRSDeviceData" type="NTRSDeviceDataType" minOccurs="1">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Data related to the user's browser or mobile device.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="NTRSRiskData" type="NTRSRiskDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Risk related data. It SHOULD NOT be sent if the CardPresent = False.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CardHolderData" type="CardHolderDataDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Cardholder-related data.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
  </xs:all>
</xs:complexType>