Open the Portico Developer Guide site
PosGateway Schema
CreditAuthReqBlock1Type Complex Type
PosGateway Schema : CreditAuthReqBlock1Type Complex Type
Namespace http://Hps.Exchange.PosGateway
Diagram
SCAExemptionData Element EUSingleTap Element ServiceLocation Element AccountReferenceReq Element IPSelectedTerms Element SubMerchantData Element WalletData Element Secure3D Element BillPay Element CurrencyConversion Element CardOnFileData Element CPCData Element TagData Element SecureECommerce Element EMVData Element SurchargeAmtInfo Element TxnDescriptor Element ShippingAmtInfo Element ConvenienceAmtInfo Element OrigTxnRefData Element AdditionalTxnFields Element Ecommerce Element AllowPartialAuth Element AutoSubstantiation Element LodgingData Element AllowDup Element DirectMktData Element CardHolderData Element CPCReq Element PinBlock Element GratuityAmtInfo Element AmountIndicator Element Amt Element PaymentMethodKeyData Element PaymentMethodKey Element CardData Element x_global_transaction_id Element GatewayTxnId Element All CreditAuthReqBlock1Type Complex Type
Overview
All
GatewayTxnId optional txnIdType Simple Type

Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction from which card data will be reused.

Note: When using a prior transaction id, card data should not be sent and original transaction reference data will be required.

x_global_transaction_id optional x_global_transaction_idType Simple Type

Client generated transaction identifier sent in the request of the original transaction.

Note: This is for internal use only.

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.

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.

PaymentMethodKeyData optional PaymentMethodKeyData Complex Type

These fields provide a way to override stored payment information or to provide additional information in card present situations. This is for the current transaction only and will not be stored for future use.

Note: This element is only valid when supplying a PaymentMethodKey.

All
ExpMonth optional monthType Simple Type

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

Expiration year

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.

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.

Amt amtTypeGlobal Simple Type

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

AmountIndicator optional amountIndicatorType Simple Type

Valid values include:

  • 'E' indicates that Amt is an estimated amount
  • 'F' indicates the Amt is final

Note: In the case of 'F', the Amt should not be manipulated and no CreditIncrementalAuth should be ran.

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: Only used for UnionPay transactions processing to the GSAP-NA and GSAP-AP authorization platforms. Not for use with EMV transactions. Refer to EMVData.

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.

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

DirectMktData optional DirectMktDataType Complex Type

Direct marketing data; eCommerce

All
DirectMktInvoiceNbr directMktInvoiceNbrType Simple Type

Invoice number

Note: The elements in the direct marketing data group are passed on through the settlement process.

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

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.

AutoSubstantiation optional AutoSubstantiationType Complex Type

Auto substantiation data; used for healthcare

All
FirstAdditionalAmtInfo AdditionalAmtType Complex Type

First additional amount information; this defines the portion of the total amount provided as part of this request that was specifically for healthcare charges. This will not alter the amount processed as part of the transaction.

Note: The first additional amount must be of type TOTAL_HEALTHCARE_AMT. This first amount includes the total of the over-the-counter (OTC) charges and any other healthcare additional amounts including prescriptions, vision, clinic, and dental. The total amount of this transaction must be greater than or equal to the total healthcare amount.

All
AmtType amtTypeType Simple Type

The type of healthcare amount; see the associated Type enumerations for specific values supported.

Amt amtTypeGlobal Simple Type

Amount associated with the specified type

SecondAdditionalAmtInfo optional AdditionalAmtType Complex Type

Second additional amount information; this defines the portion of the first additional amount provided as part of this request that was for a specific healthcare amount type. This will not alter the amount processed as part of the transaction.

All
AmtType amtTypeType Simple Type

The type of healthcare amount; see the associated Type enumerations for specific values supported.

Amt amtTypeGlobal Simple Type

Amount associated with the specified type

ThirdAdditionalAmtInfo optional AdditionalAmtType Complex Type

Third additional amount information; this defines the portion of the first additional amount provided as part of this request that was for a specific healthcare amount type. This will not alter the amount processed as part of the transaction.

All
AmtType amtTypeType Simple Type

The type of healthcare amount; see the associated Type enumerations for specific values supported.

Amt amtTypeGlobal Simple Type

Amount associated with the specified type

FourthAdditionalAmtInfo optional AdditionalAmtType Complex Type

Fourth additional amount information; this defines the portion of the first additional amount provided as part of this request that was for a specific healthcare amount type. This will not alter the amount processed as part of the transaction.

All
AmtType amtTypeType Simple Type

The type of healthcare amount; see the associated Type enumerations for specific values supported.

Amt amtTypeGlobal Simple Type

Amount associated with the specified type

MerchantVerificationValue optional xs:string

Merchant Verification Value; 10-character string provided by VISA that indicates participation in the Select Merchant Fee program

Note: This no longer needs to be sent as Heartland will pull this information from the merchant's profile automatically.

RealTimeSubstantiation optional booleanType Simple Type

Indicates if a merchant used an inventory approval system to verify that the items purchased qualify for healthcare auto-substantiation.

Note: This field is required for IIAS participants.

AllowPartialAuth optional booleanType Simple Type

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

Ecommerce optional eCommerceType Simple Type

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

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.

OrigTxnRefData optional origTxnRefDataType Complex Type

This element is required when a GatewayTxnId is used instead of card data. At least one of the sub-fields must be supplied. Any supplied data must match the corresponding data on the original transaction being referenced.

All
AuthCode optional xs:string

Authorization code returned by the Issuer on the original transaction

CardNbrLastFour optional Restriction of xs:string

Last four digits of the account number used on the original transaction

ConvenienceAmtInfo optional amtTypeGlobal Simple Type

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

ShippingAmtInfo optional amtTypeGlobal Simple Type

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

TxnDescriptor optional TxnDescriptorType Simple Type

Transaction description that is concatenated to a configurable merchant DBA name. The resulting string is sent to the card issuer as the Merchant Name.

Note: Updates to the device are required to utilize this feature. See your Heartland representative for more details.

SurchargeAmtInfo optional amtTypeGlobal Simple Type

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

Note: This field is limited to 8 digits with implied decimal.

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

SecureECommerce optional SecureECommerceType Complex Type

Allows for sending Secure ECommerce data associated with the transaction. This data must be obtained from a certified device that conform to the 3DSecure standard.

All
PaymentDataSource PaymentDataSourceType Simple Type

Payment Data Source is the API or source of the payment data.

TypeOfPaymentData optional TypeOfPaymentDataType Simple Type

Type of Payment Data. Required if PaymentData is included.

Note:Currently only 3DSecure is supported.

PaymentData optional Extension of PaymentDataType Simple Type

Payment Data received from payment tokenization service. Supported formats are Visa CAVV, Discover CAVV, AMEX Token Data Blocks, and MaterCard UCAF. All considered to be 3DSecure Type of Payment Data. Binary data must be encoded using base16 (Hex encoding) or base64 encoding.

Note:For Brand based 3DSecure Payment Data Sources, Payment Data is optional if no Payment Data was received due to a failed attempt to authenticate the card holder, in example.

For ApplePay, ApplePayApp, ApplePayWeb, GooglePayApp, GooglePayWeb, Payment Data is required.

encoding optional EncodingType Simple Type
Encoding used to encode binary PaymentData. Default is base64.
ECommerceIndicator optional ECommerceIndicatorType Simple Type

Optional Electronic Commerce Indicator or MasterCard UCI returned from the payment tokenization service to indicate the authentication results of the credit card payment.

Note:The ECommerceIndicator is ignored when PaymentDataSource is ApplePay, ApplePayApp, ApplePayWeb, GooglePayApp, GooglePayWeb.

XID optional Extension of XIDType Simple Type

XID genrated at the client which identifies the 3-D Secure transaction.

encoding optional EncodingType Simple Type
Encoding used to encode binary PaymentData. Default is base64.
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.

CPCData optional CPCDataType Complex Type

Corporate purchasing card data

All
CardHolderPONbr optional cardHolderPONbrType Simple Type

Purchase order number

TaxType optional taxTypeType Simple Type

Tax type indicator that qualifies the associated tax amount, see the associated Type enumerations for specific values supported.

TaxAmt optional amtTypeGlobal Simple Type

Tax amount

Note: If the tax type is 'TaxExempt', an amount should not be provided. If it is, the gateway discards the amount.

SalesTaxDetails optional SalesTaxDetailsType Complex Type

Allows sending the Canadian sales tax details for corporate card processing.

All
GSTAmt optional amtTypeGlobal Simple Type

Goods and Services Tax.

HSTAmt optional amtTypeGlobal Simple Type

Harmonized Sales Tax.

PSTAmt optional amtTypeGlobal Simple Type

Provincial Sales Tax.

QSTAmt optional amtTypeGlobal Simple Type

Quebec Sales Tax.

BuyerRecipientName optional Restriction of xs:string

Required on transactions with an amount over 150.

PSTTaxRegistration optional pstTaxRegistrationType Simple Type

Provincial Sales Tax Registration number.

MerchantVATRegistration Restriction of xs:string

Merchant Value Added Tax Registration number.

CustomerVATRegistration Restriction of xs:string

Customer Value Added Tax Registration number.

CustomerRefId Restriction of xs:string

Canadian customer reference Id.

All
CardBrandTxnId optional restrictedStringType Simple Type

Network Transaction Identifier

CardOnFile optional CardOnFileType Simple Type

Card On File Indicator

Valid values include:

  • 'C' - Cardholder initiated transaction
  • 'M' - Merchant initiated transaction

CategoryInd optional CategoryIndType Simple Type

Mastercard CIT/MIT indicator subcategory

Valid values include:

  • 01 - Unscheduled Credential-on-file
  • 02 - Standing Order (variable amount and fixed frequency)
  • 03 - Subscription (fixed amount and frequency)
  • 06 - Related/Delayed Charge
  • 07 - No Show Charge
  • 08 - Resubmission

Note: Future use for GSAP-AP merchants

CurrencyConversion optional CurrConversionDataType Complex Type

Data block for Currency Conversion.

Integration must be through GP-API

All
CurrConvOptOutFlag booleanType Simple Type

This setting indicates if the Customer has decided Opt Out of currency conversion and have the amount remain in the Merchants currency. If the customer does not opt out, the amount will be converted to currency associated with the card.

RateLookupTxnId optional guidType Simple Type

The Retrieval Reference Number (RRN) of the RateLookup or Incremental Authorization that provided the rate used for the calculations in this transaction, if it is different from the original Authorization.

CardHolderCurrCode optional currCodeType Simple Type

Indicates the currency associated with the cardholder card.

CardHolderAmt optional amtTypeGlobal Simple Type

The charge amount in the cardholder currency.

ExchangeRateApplied optional exchangeRateType Simple Type

The exchange rate used for currency conversion.

MarkupFee optional Restriction of xs:decimal

The mark up percentage applied to the transaction, resulting in the commission fee.

BillPay optional booleanType Simple Type

Indicates whether or not the transaction is a bill payment.

Merchants requiring Bill Payments should use RecurringBilling.

Secure3D optional Secure3DType Complex Type

Allows for sending 3DSecure Authentication data associated with the transaction.

All
Version optional versionType Simple Type

Indicates 3DS version used for authentication. Default version is 1.

AuthenticationValue optional Extension of authenticationValueType Simple Type

This value is the reference generated by the issuer to recognize that the authentication has taken place. Supported formats are CAVV, AEVV, UCAF. Must be encoded using base16 (Hex encoding) or base64 encoding.

encoding optional EncodingType Simple Type

Encoding used to encode binary AuthenticationValue. Default is base64.

ECI eciType Simple Type

Electronic Commerce Indicator shows the value of the result of the authentication.

Note: This value represents UCI for MasterCard.

DirectoryServerTxnId optional directoryServerTxnIdType Simple Type

The unique transaction identifier assigned by the Directory Server to identify a single transaction.

Note: Required for MasterCard Identity Check (3DS Version 2) transactions in Authorization.

WalletData optional WalletDataType Complex Type

Allows for sending Wallet Authentication data associated with the transaction.

All
PaymentSource PaymentDataSourceType Simple Type

Payment Source is the API or source of the cryptogram.

Cryptogram optional Extension of cryptogramType Simple Type

Cryptogram received from wallet payment. Supported formats are DSRP, TokenBlocks and TAVV cryptograms. Must be encoded using base16 (Hex encoding) or base64 encoding.

encoding optional EncodingType Simple Type

Encoding used to encode binary Cryptogram. Default is base64.

ECI optional eciType Simple Type

Electronic Commerce Indicator associated with the Cryptogram. This is an optional field.

DigitalPaymentToken optional xs:string

Payment payload used to send encrypted apple or google pay data.

TokenRequestorId optional tokenRequestorIdType Simple Type

FOR FUTURE USE

Value associated with a specific network token that uniquely identifies the pairing of a token requestor with a token domain.

NetworkToken optional cryptogramTypeType Simple Type

FOR FUTURE USE

For use with NetworkToken only. If type is not provided, and a cryptogram is sent, Portico will use the default cryptogram type for the card brand.

SubMerchantData optional SubMerchantDataType Complex Type

Allows for sending Sub-Merchant data associated with the transaction. For Future Use.

Note: For internal use only.

All
SubMerchantId Restriction of xs:long

The ID assigned by the payment facilitator or aggregator to the sub-merchant.

Note: For internal use only.

Addr1 Restriction of xs:string

The street address of the sub-merchant.

Note: For internal use only.

City Restriction of xs:string

The city of the sub-merchant.

Note: For internal use only.

StateProvinceRegion optional Restriction of xs:string

The state or province of the sub-merchant.

Note: For internal use only.

ZipPostalCode Restriction of xs:string

The ZIP/Postal Code of the sub-merchant.

Note: For internal use only.

CountryCode Restriction of xs:int

The 3-digit ISO Numeric Country Code of the sub-merchant (eg, 840)

Note: For internal use only.

CustomerSvcPhone Restriction of xs:string

Sub-merchant phone number.

Note: For internal use only.

CustomerSvcEmail optional Restriction of xs:string

Sub-merchant email address.

Note: For internal use only.

TerminalId Restriction of xs:string

The sub-merchant Terminal ID assigned by the payment facilitator.

Note: For internal use only.

MCC Restriction of xs:string

Sub-merchant MCC.

Note: For internal use only.

IPSelectedTerms optional IPSelectedTermsReqType Complex Type

Information on the Installment Plan chosen by the customer. Usage varies by region and the Installments service provider.

Merchants located in the Asia Pacific region must provide the NbrInstallments and Program. SIPOptions is optional.

Merchants located in Mexico must provide the NbrInstallemnts, InstallmentPlan, and GracePeriod only.

Merchants located in Canada must provide the Program and VISOptions.

For Visa Installment Service (VIS) merchants must provide VISPlanOptions and Program.

All
Program optional programType Simple Type

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

For merchants in Canada, use VIS.

Valid values include:

  • HSBCIPP
  • mIPP
  • SIP
  • VIS

SIPOptions optional sipOptionsType Simple Type

Available to merchants in Asia Pacific. Required when the Program is SIP

Valid values include:

  • 01 - SIPZERO
  • 02 - SIPREGULAR
  • 03 - SIPMADNESS

InstallmentPlan optional installmentPlanType Simple Type

Required for merchants in Mexico

Valid values include:

  • 00 - No promotion
  • 03 - Without interest to the cardholder
  • 05 - With interest to the cardholder
  • 07 - Buy today, pay later

GracePeriod optional gracePeriodType Simple Type

The grace period before the first payment. 00 indicates no grace period

Required for merchants in Mexico

NbrInstallments optional nbrInstallmentsType Simple Type

The total number of installments

This field is available to merchants in Asia Pacific and merchants in Mexico

PlanId optional planIdReqType Simple Type

The PlanId of the customer's selected VIS installment plan

Required when the Program is VIS

TermsConditionVersion optional termsConditionVersionReqType Simple Type

The Terms and Conditions version the customer's selected VIS installment plan

Required when the Program is VIS

TermsConditionLanguage optional termsConditionLanguageReqType Simple Type

The Language Code the customer's selected VIS installment plan

Required when the Program is VIS

AccountReferenceReq optional accountReferenceReqType Simple Type

'Payment Account Reference' (PAR) is 29-character alphanumeric value requested by merchant. PAR is reference number associated with unique PAN and used by merchants to track transactions associated with customers PAN. Currently, PAR is only supported by Card Brand American Express.

Note: Account Reference is supported only for HOST Exchange.

ServiceLocation optional ServiceLocationType Complex Type

Details of the location where services are provided, if different from the merchant’s location. Should be provided for Mastercard transactions where applicable.

Note: Currently only used by Mastercard.

All
ServiceCity optional serviceCityType Simple Type

City where the cardholder received the services, if different from the merchant’s city

ServiceCountrySubdivision optional serviceCountrySubdivisionType Simple Type

Country subdivision where the cardholder received the services, if different from the merchant’s country subdivision

ServiceCountryCode optional serviceCountryCodeType Simple Type

Postal code where the cardholder received the services, if different from the merchant’s postal code.

ServiceZipPostalCode optional serviceZipPostalCodeType Simple Type

Details of the location where services are provided, if different from the merchant’s location. Should be provided for Mastercard transactions where applicable.

EUSingleTap optional booleanType Simple Type

This field provides a way for a European merchant to indicate whether a transaction is a Single Tap contactless transaction, or whether the request contains an intentionally duplicated (replayed) ATC value. Applies to MC transactions only. Valid values: Y - SingleTap N - ReplayedATC

SCAExemptionData optional SCAExemptionDataType Complex Type

This fields provides a way for a European merchant to indicate that the transaction can take advantage of one of the exemptions to SCA. Applies to visa transactions only.

All
SCAExemptionType SCAExemptionTypeType Simple Type

Eligible exemption to Strong Customer authentication (SCA) for the transaction.

Valid values include:

  • 'TrustedMerchant' Trusted merchant exemption claimed/requested.
  • 'LowValue' Transaction exemption from SCA as the merchant has determined it to be a low value payment.
  • 'SecureCorporatePayment' Transaction exemption from SCA as the merchant has determined it as a SCP.
  • 'TxnRiskAnalysis' TRA exemption claimed/requested.
  • 'DelegatedAuth' Issuer has delegated SCA.
  • 'AuthenticationOutage' Authentication outage
  • 'MerchantInitiated' Merchant initiated
  • 'RecurringPayment' Recurring payment

Note: Visa Merchant ID is required when the SCA Exemption Type is Trusted Merchant or Delegated Authentication.

SCAVisaMerchantId optional Restriction of xs:string

Note: Visa Merchant ID for Trusted Merchant and Delegated Authentication exemptions, required when the SCA Exemption Type is Trusted Merchant or Delegated Authentication

Used By
Block1 Element
Source
<xs:complexType name="CreditAuthReqBlock1Type" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:all>
    <xs:element name="GatewayTxnId" type="txnIdType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction from which card data will be reused.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> When using a prior transaction id, card data should not be sent and original transaction reference data will be required.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="x_global_transaction_id" type="x_global_transaction_idType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Client generated transaction identifier sent in the request of the original transaction.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> This is for internal use only.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CardData" type="CardDataType" minOccurs="0">
      <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="PaymentMethodKey" type="guidType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Unique key generated by PayPlan associated with a stored payment method</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> When using a key, card data should not be sent. However, stored customer data can be overridden using the card holder data.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="PaymentMethodKeyData" type="PaymentMethodKeyData" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">These fields provide a way to override stored payment information or to provide additional information in card present situations. This is for the current transaction only and will not be stored for future use.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> This element is only valid when supplying a PaymentMethodKey.
            </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="AmountIndicator" type="amountIndicatorType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">
              Valid values include:
              <ul><li><strong>'E'</strong> indicates that Amt is an estimated amount
                </li><li><strong>'F'</strong> indicates the Amt is final
                </li></ul></p>
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> In the case of <strong>'F'</strong>, the Amt should not be manipulated and no CreditIncrementalAuth should be ran.
            </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> Only used for UnionPay transactions processing to the GSAP-NA and GSAP-AP authorization platforms. Not for use with EMV transactions. Refer to EMVData.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CPCReq" type="booleanType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">This is used to request the issuer to return whether or not the supplied card is a commercial card</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> See the CPCInd in the corresponding response transaction detail.
            </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="DirectMktData" type="DirectMktDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Direct marketing data; eCommerce</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="AutoSubstantiation" type="AutoSubstantiationType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Auto substantiation data; used for healthcare</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="Ecommerce" type="eCommerceType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.</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="OrigTxnRefData" type="origTxnRefDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">This element is required when a GatewayTxnId is used instead of card data. At least one of the sub-fields must be supplied. Any supplied data must match the corresponding data on the original transaction being referenced.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="ConvenienceAmtInfo" type="amtTypeGlobal" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Convenience fee amount information; this defines the portion of the total amount provided as part of this request that was specifically for a convenience fee. 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="ShippingAmtInfo" type="amtTypeGlobal" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Shipping amount information; this defines the portion of the total amount provided as part of this request that was specifically for shipping. 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="TxnDescriptor" type="TxnDescriptorType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Transaction description that is concatenated to a configurable merchant DBA name. The resulting string is sent to the card issuer as the Merchant Name.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> Updates to the device are required to utilize this feature. See your Heartland representative for more details.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="SurchargeAmtInfo" type="amtTypeGlobal" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Surcharge amount information; this defines the portion of the total amount provided as part of this request that was specifically for a surcharge. This is informational only and will not alter the amount processed as part of the transaction. </p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> This field is limited to 8 digits with implied decimal.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="EMVData" type="EMVDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">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.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="SecureECommerce" type="SecureECommerceType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Allows for sending Secure ECommerce data associated with the transaction.  This data must be obtained from a certified device that conform to the 3DSecure standard.</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="CPCData" type="CPCDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Corporate purchasing card data</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CardOnFileData" type="CardOnFileDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Card On File Data</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="CurrencyConversion" type="CurrConversionDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Data block for Currency Conversion.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">Integration must be through GP-API</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="BillPay" type="booleanType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Indicates whether or not the transaction is a bill payment.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">Merchants requiring Bill Payments should use RecurringBilling.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="Secure3D" type="Secure3DType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Allows for sending 3DSecure Authentication data associated with the transaction.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="WalletData" type="WalletDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Allows for sending Wallet Authentication data associated with the transaction.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="SubMerchantData" type="SubMerchantDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Allows for sending Sub-Merchant data associated with the transaction. For Future Use.</p>
          <p xmlns="http://Hps.Exchange.PosGateway" />
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> For internal use only.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="IPSelectedTerms" type="IPSelectedTermsReqType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">Information on the Installment Plan chosen by the customer. Usage varies by region and the Installments service provider.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">Merchants located in the Asia Pacific region must provide the NbrInstallments and Program. SIPOptions is optional.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">Merchants located in Mexico must provide the NbrInstallemnts, InstallmentPlan, and GracePeriod only.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">Merchants located in Canada must provide the Program and VISOptions.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">For Visa Installment Service (VIS) merchants must provide VISPlanOptions and Program.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="AccountReferenceReq" type="accountReferenceReqType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">'Payment Account Reference' (PAR) is 29-character alphanumeric value requested by merchant. PAR is reference number associated with unique PAN and used by merchants to track transactions associated with customers PAN. Currently, PAR is only supported by Card Brand American Express.</p>
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> Account Reference is supported only for HOST Exchange.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="ServiceLocation" type="ServiceLocationType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">
              Details of the location where services are provided, if different from the merchant’s location. Should be provided for Mastercard transactions where applicable.
            </p>
          <p xmlns="http://Hps.Exchange.PosGateway">
            <strong>Note:</strong> Currently only used by Mastercard.
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="EUSingleTap" type="booleanType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">This field provides a way for a European merchant to indicate whether a transaction is a Single Tap contactless transaction, 
              or whether the request contains an intentionally duplicated (replayed) ATC value. Applies to MC transactions only.
              Valid values:
                Y - SingleTap 
                N - ReplayedATC 
            </p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
    <xs:element name="SCAExemptionData" type="SCAExemptionDataType" minOccurs="0">
      <xs:annotation>
        <xs:documentation>
          <p xmlns="http://Hps.Exchange.PosGateway">This fields provides a way for a European merchant to indicate that the transaction can take advantage of one of the exemptions to SCA. Applies to visa transactions only.</p>
        </xs:documentation>
      </xs:annotation>
    </xs:element>
  </xs:all>
</xs:complexType>
See Also
PosGateway Schema