|
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.
|
|
|
|
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
|
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.
|
|
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.
| | | |
|
|
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.
|
|
|
| |
|
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.
|
|
|
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".
|
| |
|
|
All
| |
|
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
|
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
|
Duration optional xs:int
Duration of stay in days
The stay Duration range is from 1 to 99.
|
|
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.
|
| |
|
| | |
|
|
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
| |
|
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
| |
|
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
| |
|
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
| |
|
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.
| | |
|
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
|
All
|
InvoiceNbr optional Restriction of xs:string
Used to log the invoice number on transactions that are not eCommerce.
|
| |
|
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
|
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
|
| |
|
|
All
|
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.
|
|
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.
| | |
|
|
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.
| | | |
|
|
All
|
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.
|
|
|
All
|
BuyerRecipientName optional Restriction of xs:string
Required on transactions with an amount over 150.
|
|
CustomerRefId Restriction of xs:string
Canadian customer reference Id.
| | | | |
|
|
All
|
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
| | |
|
|
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.
|
|
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.
|
|
|
All
|
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.
|
|
ECI eciType Simple Type
Electronic Commerce Indicator shows the value of the result of the authentication.
Note: This value represents UCI for MasterCard.
|
| |
|
|
All
|
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.
|
|
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.
|
|
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.
| | |
|
|
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:
|
|
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
|
| |
|
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
| |
|
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
|
|
|
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
| | | |