 |
Choice
 |
AddAttachment PosAddAttachmentReqType Complex Type
AddAttachment can be used to store and associate data (i.e. images and documents) to a prior transaction.
The referenced original transaction must have been approved and must be one of the following:
- CreditAuth
- CreditOfflineAuth
- CreditSale
- CreditOfflineSale
- CreditReturn
- DebitSale
- GiftCardSale
- GiftCardAddValue
- PrePaidAddValue
- CheckSale
- OverrideFraudDecline
This must be done within three months of the original transaction.
For Document attachment types:
- Up to five document attachments are allowed to be associated with a single transaction
- Document attachments can be submitted on one or more requests
- To replace a document attachment, a new document attachment with the same name can be provided
For other attachment types:
- Only one of each attachment type can be associated with a single transaction
- Only one of each attachment type can be submitted per request
- If a request includes an attachment type that is already associated with a given transaction, it will result in the attachment being replaced
 |
Sequence
|
GatewayTxnId txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
 |
All
|
AttachmentData Restriction of xs:string
The base64 encoded attachment data.
Note: The code limits the maximum size beyond the limit in the schema. The maximum document and image data size allowed is 300K which includes the encoding overhead.
|
|
AttachmentName optional Restriction of xs:string
A merchant assigned name for the associated attachment.
| | | | |
|
|
All
|
Buyer optional
Buyer Information for the authorization
|
Sequence 1..50
| |
|
Shipping optional
Shipping Information for the authorization
|
Sequence 1..10
| |
|
Payment optional
Payment Information for the authorization
|
Sequence 1..200
| |
|
LineItem optional
Line Item purchase information for the authorization
|
Sequence 1..100
| | | |
|
AltPaymentCapture PosAltPayCaptureReqType Complex Type
AltPaymentCapture takes a previously approved Alternate Payment Authorization or Alternate Payment Order and captures a portion of the original into the current open batch. If a batch is not open, this transaction will create one.
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway generated transaction identifier returned in the response of the original transaction. This indicates the AltPayment transaction to be captured against.
|
|
Payment optional
Payment Information for the capture
|
Sequence 1..200
| | | |
|
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway generated transaction identifier returned in the response of the original transaction. This indicates the original Alt Payment transaction to create an authorization against.
|
|
Shipping optional
Shipping Information for the new authorization
|
Sequence 1..10
| |
|
Payment optional
Payment Information for the new authorization
|
Sequence 1..200
| |
|
LineItem optional
Line Item purchase information for the new authorization
|
Sequence 1..100
| | | |
|
|
All
|
Buyer optional
Buyer Information for the session
|
Sequence 1..50
| |
|
Shipping optional
Shipping Information for the session
|
Sequence 1..10
| |
|
Payment optional
Payment Information for the session
|
Sequence 1..200
| |
|
LineItem optional
Line Item purchase information for the session
|
Sequence 1..100
| | | |
|
|
All
|
Buyer optional
Buyer Information for the order
|
Sequence 1..50
| |
|
Shipping optional
Shipping Information for the order
|
Sequence 1..10
| |
|
Payment optional
Payment Information for the order
|
Sequence 1..200
| |
|
LineItem optional
Line Item purchase information for the order
|
Sequence 1..100
| | | |
|
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway generated transaction identifier returned in the response of the original transaction. This indicates the Alt Payment transaction to be returned.
|
|
Return optional
Return information for the return
|
Sequence 1..50
| | | |
|
AltPaymentReversal PosAltPayReversalReqType Complex Type
AltPaymentReversal takes a Alternate Payment GatewayTxnId and performs a reversal against that transaction. Abanonded timed out transactions of AltPaymentSale, AltPaymentOrder, AltPaymentAuth and AltPaymentCapture can be reversed
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway generated transaction identifier returned in the response of the original transaction. This indicates the Alt Payment transaction to be reversed.
| | |
|
|
All
|
Buyer optional
Buyer Information for the sale
|
Sequence 1..50
| |
|
Shipping optional
Shipping Information for the sale
|
Sequence 1..10
| |
|
Payment optional
Payment Information for the sale
|
Sequence 1..200
| |
|
LineItem optional
Line Item purchase information for the sale
|
Sequence 1..100
| | | |
|
|
All
| |
|
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway generated transaction identifier returned in the response of the original transaction. This indicates the Alt Payment transaction to be voided.
| | |
|
Authenticate xs:anySimpleType
Authenticate is used to authenticate a specific user. For this call the header must include username and password.
Note: This is for internal use only.
|
|
BatchClose Extension of xs:string
BatchClose is used to settle and close the current open batch. If a batch is not open an error will be returned.
 |
deviceId optional xs:int
| |
|
|
Sequence
|
|
All
|
BnplProvider Restriction of xs:string
Bnpl Provider choosen by customer
|
| | | |
|
CancelImpersonation xs:anySimpleType
CancelImpersonation is used to terminate a previously started impersonation session.
Note: This is for internal use only.
|
|
CashReturn PosCashReturnReqType Complex Type
CashReturn creates a log of a transaction that is returning cash to a customer. This is processed offline.
Note: The client is responsible for maintaining any required cash value totals for reconciliation.
|
Sequence
|
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This must refer to a prior CashSale.
|
| | | |
|
CashSale PosCashSaleReqType Complex Type
CashSale creates a log of a transaction, in which cash is collected from a customer. This is processed offline.
Note: The client is responsible for maintaining any required cash value totals for reconciliation.
|
Sequence
|
|
All
|
Amt amtTypeGlobal Simple Type
The cash amount paid by the customer; this is the sale total and includes all other "Info" amounts provided as part of this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
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.
|
|
TaxAmtInfo optional amtTypeGlobal Simple Type
Tax amount information; this defines the portion of the total amount provided as part of this request that was specifically for tax. This is informational only and will not alter the amount processed as part of the transaction.
|
| | | |
|
CheckSale PosCheckSaleReqType Complex Type
CheckSale transactions use bank account information as the payment method. There are sub-actions that can be taken as part of the CheckSale as indicated by the CheckAction field.
Note: Both GETI and Colonnade are supported. A check processor is chosen during the boarding process for each device. The choice of check processor will drive the available functionality as well as the required elements. See individual fields for additional information.
|
Sequence
|
|
All
|
CheckAction checkActionType Simple Type
A modifier that determines the backend functionality to perform; see the associated Type enumerations for specific values supported.
Note: Return and Override are only supported when processing with GETI.
Note: This sets the PACKET_ID sent to GETI.
|
|
AccountInfo optional AccountInfoType Complex Type
Account information to use as the payment method
Note: The check processor may allow MICR data to be sent in place of account and route or it may require both. This can be determined during certification.
|
|
DataEntryMode optional dataEntryModeType Simple Type
Indicates whether the provided data was entered manually or retrieved from a reader; see the associated Type enumerations for specific values supported.
Note: This sets the CONTROL_CHAR sent to GETI.
|
|
CheckType optional checkTypeType Simple Type
Indicates the type of check being processed; see the associated Type enumerations for specific values supported.
Note: This sets the IDENTIFIER sent to GETI.
|
|
VerifyInfo optional VerifyInfoType Complex Type
Verification only options
Note: If eBronze is selected as the SEC code for GETI during boarding, all requests will be verification only and this element is not required.
|
|
SECCode optional xs:string
NACHA Standard Entry Class Code for processing.
Valid values include:
- "PPD" (Prearranged Payment and Deposit)
- "CCD" (Cash Concentration or Disbursement)
- "POP" (GETI only, Point of Purchase Entry)
- "WEB" (Internet Initiated Entry)
- "TEL" (Telephone Initiated Entry)
- "EBRONZE" (GETI only)
Note: SECCode is a required field when the check processor is Colonnade.
Note: For GETI, this will be used to validate information returned from GETI during the transaction. This validation is not done when EBRONZE is chosen.
|
|
ConsumerInfo optional ConsumerInfoType Complex Type
Information about the consumer.
Note: While all these are optional in the schema, the check processor may require some of these fields in specific circumstances. For additional information on this, please consult the requirements of the specific processor.
|
|
PaymentMethodKey optional guidType Simple Type
Unique key generated by PayPlan associated with a stored payment method
Note: When using PaymentMethodKey, the following fields should not be sent as part of the transaction as they will be obtained from previously stored data:
- DataEntryMode
- CheckType
- VerifyInfo
- SECCode
- ConsumerInfo
- RoutingNumber
- AccountNumber
|
|
TokenValue optional xs:string
Token used to replace payment method data (route, account, and MICR).
Note: Multi-use tokens are not yet supported on check transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product and are primarily used in eCommerce situations.
| | | | |
|
|
Sequence
|
Block1 CheckQueryReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: GatewayTxnId and ClientTxnId are mutually exclusive, but it is required that one of these fields be provided.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be queried.
|
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be queried.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
| | | | |
|
CheckVoid PosCheckVoidReqType Complex Type
CheckVoid is used to cancel a previously successful CheckSale transaction. It can also be used to cancel a prior CheckSale transaction. This should be used in timeout situations or when a complete response is not received.
Note:CheckVoid transactions should be submitted within 31 days of the original transaction.
Note:If the CheckVoid also fails to return a complete response (likely due to a timeout), wait until connectivity is restored and try again or contact support to ensure the proper result was achieved. CheckQuery can be used to check the status of a prior CheckSale transaction.
|
Sequence
|
Block1 CheckVoidReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: GatewayTxnId and ClientTxnId are mutually exclusive, but it is required that one of these fields be provided.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
| | | | |
|
ChipCardDecline PosChipCardDeclineReqType Complex Type
ChipCardDecline is used to record an offline decline by an EMV chip card.This transaction is optional and can be used for record-keeping purposes only.
Note:This transaction is not used for a transaction that received an online approval. To cancel transactions that have been approved online but subsequently declined by the chip, a Credit/Debit Reversal must be sent.
|
All
|
|
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.
Note: Multi-use tokens cannot be requested on a ChipCardDecline.
|
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
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.
|
|
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
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
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.
|
| | | |
|
CreditAccountVerify PosCreditAccountVerifyReqType Complex Type
CreditAccountVerify is used to verify that the associated account is in good standing with the Issuer. This is a zero dollar transaction with no associated authorization. Since VISA and other Issuers have started assessing penalties for one dollar authorizations, this provides a way for merchants to accomplish the same task while avoiding these penalties.
There are differences in the processing of this transaction based on card type:
- VISA: an account verification is done at the Issuer
- MasterCard: an account status check is done at the Issuer
- Discover: an account verification is done at the Issuer
- AMEX: an AVS only verification is done; this still ensures that the account is valid but requires that AVS data is supplied (zip code at a minimum). Both manual and swiped/track entry methods are supported. However, EMV transactions are not supported.
Note:UnionPay cards do not support Verification when routing directly to UnionPay International for approval. UnionPay cards routing through either the Discover or JCB networks may obtain verification. (UnionPay direct routing available for Canada merchants on the GSAP authorization platform only).
|
All
|
|
All
|
CardData optional CardDataType Complex Type
A common element used in several different transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
| | | | |
|
CreditAdditionalAuth PosCreditAdditionalAuthReqType Complex Type
CreditAdditionalAuth is typically used in a bar or restaurant situation where the merchant obtains the payment information for an original CreditAuth but does not want to hold the card or ask for it on each additional authorization.
This uses data from a previously successful CreditAuth to authorize an additional amount. The additional authorization is run as a card not present transaction and cannot be placed in a batch. This can be repeated as needed. The final settlement amount including any additional authorized amounts must be provided in the CreditAddToBatch for the original CreditAuth. When the original transaction is added to the batch a reversal is automatically attempted for all additional authorizations.
The following rules apply:
- CreditAdditionalAuth is allowed only for restaurant merchants.
- The original transaction must be an approved open authorization run within the same day (i.e. a CreditAuth that has not been added to a batch).
- When the original authorization transaction is fully reversed or voided, any associated CreditAdditionalAuth transactions are reversed.
- An original authorization transaction with CreditAdditionalAuth transactions can be partially reversed for less than the full original auth amount. However, additional authorizations are still not reversed until the original is added to the batch.
- Additional authorizations cannot be voided, edited, or used for returns.
Note:CreditAdditionalAuth is not supported for UnionPay cards routing to UnionPay International for authorization. CreditAdditionalAuth may continue to be used for UnionPay cards routing through either the Discover or JCB networks. (UnionPay direct routing available for Canada merchants on the GSAP authorization platform only).
Note:This service has been deprecated. Refer to CreditIncrementalAuth.
|
All
|
|
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.
|
|
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.
| | | | |
|
CreditAddToBatch PosCreditAddToBatchReqType Complex Type
CreditAddToBatch is primarily used to add a previously approved open authorization (CreditAuth, CreditOfflineAuth, OverrideFraudDecline, or RecurringBillingAuth) to the current open batch. If a batch is not open this transaction will create one. It also provides the opportunity to alter data associated with the transaction (i.e. add a tip amount).
Note: The gateway will not submit an authorization or reversal when the settlement amount of a transaction is altered. The client is responsible for managing these adjustments as needed.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
Amt optional amtTypeGlobal Simple Type
If present, this amount replaces the amount to be settled for the original transaction; this includes all other "Info" amounts associated with the original transaction or provided in this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
If present, this amount is stored with the original transaction. If the original already had gratuity amount information, this will replace it. This defines the portion of the settlement amount that is specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
|
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
| |
|
SurchargeAmtInfo optional amtTypeGlobal Simple Type
If present, this amount is stored with the original transaction. If the original already had surcharge amount information, this will replace it. This defines the portion of the settlement amount that is 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.
|
|
EMVTagData optional emvTagDataType Simple Type
EMV tag data in TLV format consisting of the chip card results after applying the Issuer response tags.
Note: This field has been obsoleted.See the TagData field for the alternative.
|
|
TagData optional TagDataType Complex Type
EMV or Non-EMV tag data in TLV format. For EMV tag data this would consist of the chip card results after applying the Issuer response tags.
|
All
|
TagValues optional Extension of xs:string
This field holds the tag data values.
| | |
|
|
All
|
PFRecAccountNbr Restriction of xs:long
Account number of the merchant who will receive the secondary amount.
|
| |
|
RetryInd optional booleanType Simple Type
Indicates whether this transaction is a retry of the previous CreditAddToBatch request.
Note: This is for the UK market only.
|
|
NoShow optional booleanType Simple Type
Indicates that this charge is due to a "no show" on a reservation
Note: This is for the UK and AP markets only.
|
|
|
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.
| | | | |
|
CreditAuth PosCreditAuthReqType Complex Type
CreditAuth authorizes a credit card transaction. These authorization only transactions are not added to the batch to be settled. They can be added to a batch at a later time using CreditAddToBatch. Approved authorizations that have not yet been added to a batch are called open auths.
Note: If you prefer to have the authorization automatically added to the batch, use CreditSale.
Authorizations can be processed by sending card data, the GatewayTxnId from a previous authorization, or a key from a previously stored payment method.
When using a prior transaction id, the following rules apply:
- The original transaction must be an approved CreditAuth or CreditSale that was not also run using a prior transaction id.
- The original transaction must be fully reversed, voided, or returned.
- The original transaction must have occurred within the last 14 days.
- The original transaction may only be referenced once in this way.
- The new amount must be greater than 0.00 and cannot exceed 100% of the original.
- The new transaction is sent as "Card Not Present"
- The new transaction can be voided or reversed.
- OrigTxnRefData must be provided with AuthCode and/or CardNbrLastFour and the provided data must match the original transaction data.
|
All
|
Block1 CreditAuthReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: CardData, GatewayTxnId, and PaymentMethodKey are mutually exclusive, but it is required that one of these elements be provided.
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
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.
|
|
BillPay optional booleanType Simple Type
Indicates whether or not the transaction is a bill payment.
Merchants requiring Bill Payments should use RecurringBilling.
|
|
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.
|
|
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.
|
|
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
|
| | | |
|
|
|
CreditCPCEdit PosCreditCPCEditReqType Complex Type
CreditCPCEdit attaches Corporate Purchase Card (CPC) data to a prior transaction. This information will be passed to the issuer at settlement when the associated card was a corporate card or an AMEX card.
Note: This function only works against previously approved CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, and RecurringBillingAuth transactions.
Note: The amount of the original transaction is not altered by the CreditCPCEdit. This additional data is informational only. The original transaction will be processed regardless of whether or not the CreditCPCEdit is used by the client.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
|
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.
|
| |
| |
|
CreditIncrementalAuth PosCreditIncrementalAuthReqType Complex Type
CreditIncrementalAuth adds to the authorized amount for a prior transaction.
The following rules apply:
- The original transaction must have been an approved CreditAuth. NOTE: CreditSale is allowed for US merchants processing to the Exchange host only.
- The original transaction id should continue to be used for subsequent transactions (i.e., voids, reversals, edits, etc.); the transaction id of the incremental authorization should never be referred to by subsequent transactions.
- Each incremental authorization is not added to the batch. The total amount is maintained with the original transaction.
- If the final settlement amount of the original transaction is less than the total of all authorizations, reversals will automatically be generated as needed.
Note:UnionPay cards routed directly to UnionPay International do not support Incremental Authorizations. CreditIncrementalAuth may continue to be used for UnionPay cards routing through either the Discover or JCB networks. (UnionPay direct routing available for Canada merchants on the GSAP authorization platform only).
|
All
|
|
All
|
LodgingData optional ExtraChargesDataType 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
Note: The field name LodgingData can be confusing in this case as it is actually referring to the lodging extra charges data type.
|
|
CardOnFileData optional CardOnFileDataType Complex Type
Card On File Data
For Credit Incremental Auth transactions, this data is used for Exchange-hosted merchants only. For GSAP, GNAP, and AP hosted merchants, the card on file data is obtained from the original Credit Auth being incremented.
|
|
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.
| | | | |
|
|
All
|
|
All
|
CardData optional CardDataType Complex Type
A common element used in several different transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.
|
|
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.
|
|
PaymentMethodKey optional guidType Simple Type
Unique key generated by PayPlan associated with a stored payment method
Note: When using a key, card data should not be sent. However, stored customer data can be overridden using the card holder data.
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
EMVData optional EMVDataType Complex Type
When processing with an EMV capable client, this element may need to be provided. It consists of certain online authentication data or the reason for not utilizing the EMV capabilities. EMV tag data should be sent in the separate TagData field.
|
|
IPTerms optional IPTermsReqDataType Complex Type
The IPTerms block include information regarding the installment Program.
For Visa Installments Service (VIS), multiple plans are returned in the response. The VISOptions block includes additional filter options for the returned plans.
| | | | |
|
CreditOfflineAuth PosCreditOfflineAuthReqType Complex Type
CreditOfflineAuth records an authorization obtained outside of the gateway (e.g., voice authorization, chip card offline approval). These authorization only transactions are not added to the batch to be settled. They can be added to a batch at a later time using CreditAddToBatch. Approved authorizations that have not yet been added to a batch are called open auths.
Note:Depending on the Host Processor, a CreditOfflineAuth transaction may not be modified after it has been added to a batch.
|
All
|
|
All
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
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: This is not used in offlines.
|
|
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.
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
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.
|
|
EMVTagData optional emvTagDataType Simple Type
EMV tag data in TLV format; used for chip card offline approvals.
Note: This field has been obsoleted.See the TagData field for the alternative.
|
| | | |
|
CreditOfflineSale PosCreditOfflineSaleReqType Complex Type
CreditOfflineSale records an authorization obtained outside of the gateway (e.g., voice authorization, chip card offline approval). The authorization is placed in the current open batch. If a batch is not open this transaction will create one.
|
All
|
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction.
This field is used to indicate that the previous CreditOfflineSale that timed out should be retried.
Note: This is for the UK market only.
|
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
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: This is not used in offlines.
|
|
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.
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
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.
|
|
EMVTagData optional emvTagDataType Simple Type
EMV tag data in TLV format; used for chip card offline approvals.
Note: This field has been obsoleted.See the TagData field for the alternative.
|
| | | |
|
CreditReturn PosCreditReturnReqType Complex Type
CreditReturn allows the merchant to return funds back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.
For added fraud protection, CreditReturn can be run utilizing the GatewayTxnId from a previous sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.
The following rules apply when returning by GatewayTxnId:
- The original transaction must be a CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, or RecurringBillingAuth and must be in a batch. It cannot be an open authorization that still needs to be added to a batch.
- The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.
- A return amount must be greater than zero.
- The return must be run within 1 year.
- CreditReversal, CreditVoid, and CreditTxnEdit are not allowed against original transactions for which a full or partial return has been run.
- A return can be voided. If this results in the total return amount being adjusted back to zero, CreditVoid, CreditReversal, and CreditTxnEdit are allowed on the original transaction once again.
- If CardData is also supplied, the supplied card number and the card number of the original transaction must match.
Note: If the original transaction is in the current open batch, a CreditVoid or CreditReversal may be used instead. However, only a return can be used once the batch is closed.
|
All
|
Block1 CreditReturnReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: One or both of CardData and GatewayTxnId can be supplied, but it is required that one of these elements be provided.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the original sale this return is to be run against.
Note: If CardData is also sent, the provided data must match the original.
|
|
AuthCode optional authCodeType Simple Type
Authorization code returned by the Issuer on the original transaction. Supported for GSAP-hosted merchants only; necessary for returns in Mexico.
|
|
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.
|
|
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
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
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.
| | | | |
|
CreditReversal PosCreditReversalReqType Complex Type
CreditReversal cancels a prior authorization in the current open batch. This can be used in timeout situations or when a complete response is not received. This transaction can also be used to cancel a transaction that was approved online but subsequently declined by the chip.
This can be used on prior transactions of the following types: CreditAuth, CreditSale, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, RecurringBillingAuth, and OverrideFraudDecline.
Note:This can also be used to partially reduce the amount of a prior authorization.
Note:Credit reversal transactions must be submitted within 31 days of the original transaction.
Note:If the reversal also fails to return a complete response (likely due to a timeout), wait until connectivity is restored and try again or contact support to ensure the proper result was achieved.
Note:A credit reversal should be requested with the GatewayTxnID or ClientTxnID. Never send a reversal request with a multi-use token in the Card Data.
|
All
|
Block1 CreditReversalReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: CardData, ClientTxnId, and GatewayTxnId are mutually exclusive, but it is required that one of these fields be provided.
Note: Always run reversals with either GatewayTxnId or ClientTxnId. If only CardData is used the results are not guaranteed as the original transaction may not be uniquely identified.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
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.
|
|
Amt amtTypeGlobal Simple Type
This must match the authorization amount from the original transaction. This is required for both full and partial reversals. If not supplied an error response will be returned.
|
|
AuthAmt optional amtTypeGlobal Simple Type
This field is required for a partial reversal and indicates the desired new authorization amount once the reversal has been processed. If not supplied it will be defaulted to zero indicating a full reversal.
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
|
|
EMVTagData optional emvTagDataType Simple 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.
Note: This field has been obsoleted.See the TagData field for the alternative.
|
| | | |
|
|
All
|
|
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.
|
|
ConsumerId optional Restriction of xs:string
Unique token requestor specific consumer identifier (e.g. wallet account ID).
|
| | | |
|
|
All
|
|
All
|
NTRSToken Restriction of xs:long
The token itself. The token that payment data is being requested for.
|
| | | |
|
|
All
|
|
All
|
NTRSToken Restriction of xs:long
The token itself. The token that payment data is being requested for.
| | | | |
|
|
All
|
|
All
|
NTRSToken Restriction of xs:long
The network token generated by NTRS.
| | | | |
|
|
All
|
|
All
|
NTRSToken Restriction of xs:long
The token itself. The token that payment data is being requested for.
| | | | |
|
CreditSale PosCreditSaleReqType Complex Type
CreditSale authorizes a credit card transaction. These authorizations are automatically added to the batch to be settled. If a batch is not already open this transaction will create one.
Authorizations can be processed by sending card data or the GatewayTxnId from a previous authorization. When using a prior transaction id, the following rules apply:
- The original transaction must be an approved CreditAuth or CreditSale that was not also run using a prior transaction id.
- The original transaction must be fully reversed, voided, or returned.
- The original transaction must have occurred within the last 14 days.
- The original transaction may only be referenced once in this way.
- The new amount must be greater than 0.00 and cannot exceed 100% of the original.
- The new transaction is sent as "Card Not Present"
- The new transaction can be voided or reversed.
- OrigTxnRefData must be provided with AuthCode and/or CardNbrLastFour and the provided data must match the original transaction data.
|
All
|
Block1 CreditSaleReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: CardData and GatewayTxnId are mutually exclusive, but it is required that one of these elements be provided.
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
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.
|
|
CashbackAmtInfo optional amtTypeGlobal Simple Type
Cashback amount information; this defines the portion of the total amount provided as part of this request that was specifically for cashback. This is informational only and will not alter the amount processed as part of the transaction.
Note: This is only supported for the UK, AP, and Mexico markets 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.
|
|
BillPay optional booleanType Simple Type
Indicates whether or not the transaction is a bill payment.
Merchants requiring Bill Payments should use RecurringBilling.
|
|
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.
|
|
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
|
| | | |
|
CreditTxnEdit PosCreditTxnEditReqType Complex Type
CreditTxnEdit allows the merchant to alter the data on a previously approved CreditSale, CreditAuth, CreditOfflineSale, or CreditOfflineAuth (i.e. add a tip amount).
Note:Depending on the Host Processor, a CreditOfflineAuth transaction may not be modified after it has been added to a batch.
Note:The gateway will not submit an authorization or reversal when the settlement amount of a transaction is altered. The client is responsible for managing these adjustments as needed.
Note:Approved UnionPay authorizations routed directly to UnionPay International cannot be adjusted. UnionPay cards routing through either the Discover or JCB networks may be adjusted. (UnionPay direct routing available for Canada merchants on the GSAP authorization platform only).
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
Amt optional amtTypeGlobal Simple Type
If present, this amount replaces the amount to be settled for the original transaction; this includes all other "Info" amounts associated with the original transaction or provided in this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
If present, this amount is stored with the original transaction. If the original already had gratuity amount information, this will replace it. This defines the portion of the settlement amount that is specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
|
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
| |
|
SurchargeAmtInfo optional amtTypeGlobal Simple Type
If present, this amount is stored with the original transaction. If the original already had surcharge amount information, this will replace it. This defines the portion of the settlement amount that is 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.
|
|
EMVTagData optional emvTagDataType Simple Type
EMV Tag Data in TLV format consisting of the chip card results after applying the Issuer response tags.
Note: This field has been obsoleted.See the TagData field for the alternative.
|
|
TagData optional TagDataType Complex Type
EMV or Non-EMV tag data in TLV format. For EMV tag data this would consist of the chip card results after applying the Issuer response tags.
|
All
|
TagValues optional Extension of xs:string
This field holds the tag data values.
| | |
|
NoShow optional booleanType Simple Type
Indicates that this charge is due to a "no show" on a reservation
Note: This is for the UK and AP markets only.
|
|
|
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.
| | | | |
|
CreditVoid PosCreditVoidReqType Complex Type
CreditVoid is used to cancel an open auth or remove a transaction from the current open batch. The original transaction must be a CreditAuth, CreditSale, CreditReturn, CreditOfflineAuth, CreditOfflineSale, RecurringBilling, RecurringBillingAuth, or OverrideFraudDecline.
Note: Once a batch is closed, associated transactions can no longer be voided. In these cases, a CreditReturn can be used to adjust a customer's account.
Note: If a transaction has been fully or partially returned, it cannot be voided.
Note: Due to new issuer regulations, a void now automatically attempts to reverse the original transaction. If the reversal is successful, the original transaction status will be set to 'R'. If there is no need to reverse (i.e. offlines) or the reversal fails, the original transaction status will be set to 'V'. A successful response to the void will indicate that the original transaction has been removed from the batch in either case.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
| |
|
DebitAddValue PosDebitAddValueReqType Complex Type
DebitAddValue increases the amount on a stored value card. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.
Note: This transaction has been obsoleted. See the PrePaidAddValue for an alternative.
|
All
|
|
All
|
PinBlock pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
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
|
|
All
|
TokenValue optional xs:string
Token used to replace payment method data (track data and optionally PIN block).
Note: Multi-use tokens are not supported on debit transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product and are primarily used in eCommerce situations.
|
|
EMVChipCondition optional emvChipConditionType Simple Type
This must be provided when the POS was not able to successfully communicate to the chip card and was required to fall back to a magnetic stripe read on an EMV capable terminal.
The values can indicate multiple factors:
- The EMV chip read failed
- Did the previous attempt fail
See enumerations for specific values supported
|
|
TagData optional TagDataType Complex Type
EMV or Non-EMV tag data in TLV format. For EMV tag data this would consist of the chip card results after applying the Issuer response tags.
|
| | | |
|
DebitReturn PosDebitReturnReqType Complex Type
DebitReturn allows the merchant to return funds from a prior debit sale back to the cardholder. Returns can be for the entire amount associated with the original sale or a partial amount. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.
For added fraud protection, DebitReturn can be run utilizing the GatewayTxnId from a previous debit sale. When this feature is used, the gateway tracks returns against the original sale and applies several rules.
The following rules apply when returning by GatewayTxnId:
- The total of all returns cannot exceed the original sale amount. This is true for processing a single return as well as multiple returns against the same original transaction.
- A return amount must be greater than zero.
- DebitReversal is not allowed against original transactions for which a full or partial return has been run.
- The supplied card number (from the track data or token) and the card number of the original transaction must match.
Note: If the original transaction is in the current open batch, a DebitReversal may be used instead. However, only a return can be used once the batch is closed.
|
All
|
Block1 DebitReturnReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: TokenValue and TrackData are mutually exclusive, but it is required that one of these elements be provided. PinBlock can either be sent as part of the request or it can be associated with a token but it must be provided as well.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the original debit sale this return is to be run against.
Note: For debit returns, information is not pulled from the original debit sale for processing. The client must provide the PIN block and track data (or a token). The original transaction data will be used to validate that the card is the same and the return is less than or equal to the original amount, including any other returns against that 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: It is required that the order of the data be an encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
TokenValue optional xs:string
Token used to replace payment method data (track data and optionally PIN block).
Note: Multi-use tokens are not supported on debit transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product.
|
|
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.
|
|
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
|
|
MessageAuthenticationCode optional xs:string
A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.
|
|
PosSequenceNbr optional xs:string
POS sequence number for Canadian Debit transactions.
|
| | | |
|
DebitReversal PosDebitReversalReqType Complex Type
DebitReversal cancels a previous DebitSale transaction. This should be used in timeout situations or when a complete response is not received. This transaction can be used to cancel a transaction that was approved online but subsequently declined by the chip.
Note: Debit reversal transactions must be submitted within 31 days of the original transaction.
Note: Partial reversals are not supported for debit transactions.
Note: If the reversal also fails to return a complete response (likely due to a timeout), wait until connectivity is restored and try again or contact support to ensure the proper result was achieved.
Note: DebitReversal is not allowed after a pre-authorization is completed with a DebitAddToBatch. Use DebitRefund instead.
|
All
|
Block1 DebitReversalReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: Reversals should always be done by GatewayTxnId. If this is for a timeout reversal and the client does not have a transaction id, TrackData can be supplied, but the results are not guaranteed as the original transaction may not be uniquely identified.
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the original debit sale to be reversed.
Note: If TrackData is also sent, the provided data must match the original.
|
|
AuthAmt optional amtTypeGlobal Simple Type
Partial reversals are not supported for debit transactions. This field should not be sent. Debit reversals are always a full reversal of the original transaction.
|
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
|
|
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
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: It is required that the order of the data be an encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
MessageAuthenticationCode optional xs:string
A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.
|
|
PosSequenceNbr optional xs:string
POS sequence number for Canadian Debit transactions.
|
|
ReversalReasonCode optional reversalReasonCodeType Simple Type
(Optional) Defines the reason for reversing a previously approved transaction.
Required for Canadian merchants processing debit reversals.
See enumerations for specific values supported.
Note:This field is required for Canadian merchants.
|
| | | |
|
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
Amt optional amtTypeGlobal Simple Type
If present, this amount replaces the amount to be settled for the original transaction; this includes all other "Info" amounts associated with the original transaction or provided in this request.
|
|
MessageAuthenticationCode optional xs:string
A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.
|
|
TagData optional TagDataType Complex Type
EMV or Non-EMV tag data in TLV format. For EMV tag data this would consist of the chip card results after applying the Issuer response tags.
Note: Required on DebitAddtoBatch for Canadian Interac/Debit.
|
All
|
TagValues optional Extension of xs:string
This field holds the tag data values.
| | |
| |
|
DebitAuth PosDebitAuthReqType Complex Type
DebitAuth authorizes a debit transaction. These authorization only transactions are not added to the batch to be settled. They can be added to a batch at a later time by using DebitAddToBatch.
Note: DebitAuth is only allowed in Canada
|
All
|
Block1 DebitAuthReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: TokenValue and TrackData are mutually exclusive, but it is required that one of these elements be provided. PinBlock can either be sent as part of the request or it can be associated with a token but it must be provided as well.
|
All
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
PinBlock optional pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
TokenValue optional xs:string
Token used to replace payment method data (track data and optionally PIN block).
Note: Multi-use tokens are not supported on debit transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product and are primarily used in eCommerce situations.
|
|
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.
|
|
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
|
|
MessageAuthenticationCode optional xs:string
A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.
|
| | | |
|
DebitSale PosDebitSaleReqType Complex Type
DebitSale authorizes a debit card transaction. These authorizations are automatically added to the batch to be settled. If a batch is not already open this transaction will create one.
|
All
|
Block1 DebitSaleReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: TokenValue and TrackData are mutually exclusive, but it is required that one of these elements be provided. PinBlock can either be sent as part of the request or it can be associated with a token but it must be provided as well.
|
All
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
GratuityAmtInfo optional amtTypeGlobal Simple Type
Gratuity amount information; this defines the portion of the total amount provided as part of this request that was specifically for gratuity. This is informational only and will not alter the amount processed as part of the transaction.
|
|
PinBlock optional pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
TokenValue optional xs:string
Token used to replace payment method data (track data and optionally PIN block).
Note: Multi-use tokens are not supported on debit transactions. This is currently only used for single-use tokens. Single-use tokens are provided by the SecureSubmit product and are primarily used in eCommerce situations.
|
|
CashbackAmtInfo optional amtTypeGlobal Simple Type
Cashback amount information; this defines the portion of the total amount provided as part of this request that was specifically for cashback. This is informational only and will not alter the amount processed as part of the transaction.
|
|
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.
|
|
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
|
|
MessageAuthenticationCode optional xs:string
A block of encrypted data to be sent from the POS on every contact Interac sale and return request. Required for Canadian merchants processing debit reversals.
|
|
PosSequenceNbr optional xs:string
POS sequence number for Canadian Debit transactions.
| | | | |
|
|
All
|
|
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.
Note: Swiped EBT transactions require track 2 data. Manually entered account numbers can only be used in the following instances:
- Track cannot be read
- Card is not present
- Reader is not available
Note: Multi-use and single-use tokens are not supported for EBT.
|
|
|
|
PinBlock pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
| | | |
|
|
All
|
|
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.
Note: Swiped EBT transactions require track 2 data. Manually entered account numbers can only be used in the following instances:
- Track cannot be read
- Card is not present
- Reader is not available
Note: Multi-use and single-use tokens are not supported for EBT.
|
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
PinBlock pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
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.
|
|
CashBackAmount amtTypeGlobal Simple Type
Cashback amount information (considered one of the "Info" amounts); this defines the portion of the total amount provided as part of this request that was specifically for cashback. This is informational only and will not alter the amount processed as part of the transaction.
|
| | | |
|
|
All
|
|
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.
Note: Swiped EBT transactions require track 2 data. Manually entered account numbers can only be used in the following instances:
- Track cannot be read
- Card is not present
- Reader is not available
Note: Multi-use and single-use tokens are not supported for EBT.
|
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request
|
|
PinBlock pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
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.
|
|
CashBackAmount amtTypeGlobal Simple Type
Cashback amount information (considered one of the "Info" amounts); this defines the portion of the total amount provided as part of this request that was specifically for cashback. This is informational only and will not alter the amount processed as part of the transaction.
|
| | | |
|
|
All
|
|
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.
Note: Swiped EBT transactions require track 2 data. Manually entered account numbers can only be used in the following instances:
- Track cannot be read
- Card is not present
- Reader is not available
Note: Multi-use and single-use tokens are not supported for EBT.
|
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
PinBlock pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
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.
|
| | | |
|
EBTFSReturn PosEBTFSReturnReqType Complex Type
EBTFSReturn is used to credit previously debited funds to an EBT Food Stamps/SNAP account for merchandise returned. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.
|
All
|
|
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.
Note: Swiped EBT transactions require track 2 data. Manually entered account numbers can only be used in the following instances:
- Track cannot be read
- Card is not present
- Reader is not available
Note: Multi-use and single-use tokens are not supported for EBT.
|
|
|
|
PinBlock pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
|
|
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.
|
| | | |
|
EBTFSReversal PosEBTFSReversalReqType Complex Type
EBTFSReversal cancels a prior purchase in the current open batch. This can be used in timeout situations or when a complete response is not received. In either case, the client is unsure of the outcome of the prior transaction.
This can be used on prior transactions of the following types: EBTFSPurchase, EBTFSReturn, EBTCashBenefitWithdrawal and EBTCashBackPurchase.
Note: Partial reversals are not supported for EBT transactions.
Note: If the reversal also fails to return a complete response (likely due to a timeout), wait until connectivity is restored and try again or contact support to ensure the proper result was achieved.
|
All
|
|
All
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
|
|
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.
Note: Swiped EBT transactions require track 2 data. Manually entered account numbers can only be used in the following instances:
- Track cannot be read
- Card is not present
- Reader is not available
Note: Multi-use and single-use tokens are not supported for EBT.
|
| | | |
|
|
All
|
|
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.
Note: Swipe is not allowed for a voucher purchase.
Note: Multi-use and single-use tokens are not supported for EBT.
Note: For EBTVoucherPurchase transactions, a null expiration date is represented by setting the ExpMonth to 1 and the ExpYear to 9999 in the CardData.ManualEntry node.
|
|
Amt amtTypeGlobal Simple Type
The amount requested for authorization; this includes all other "Info" amounts provided as part of this request.
|
|
PinBlock optional pinBlockType Simple Type
PIN block generated from the encrypted cardholder PIN and key serial number (KSN); see the guide for the specific PIN pad device being used to determine how to obtain the data elements required to create a PIN block.
Note: Portico requires the order of the data to be encrypted PIN followed by the KSN. If the encrypted PIN was 11111111 and the KSN was 22222222, the PIN block would have to be 1111111122222222 when sent to the gateway.
Note:This field has been deprecated. EBTVoucherPurchase does not support PINBlock verification and is ignored when sent.
|
|
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.
|
|
ExprDate optional Restriction of xs:string
Voucher expiration date; format is MMYY
Note:This field has been deprecated. The CardData.ManualEntry field must be used for passing payment method details.
|
|
VoucherApprovalCd Restriction of xs:string
Approval code provided by the EBT voice authorization system
|
|
PrimaryAcctNbr optional Restriction of xs:string
This field has been deprecated. The CardData field must be used for passing payment method details.
|
| | | |
|
EndToEndTest
Test for internal use only.
Note: For a quick test, clients can use TestCredentials.
|
|
FindTransactions FindTransactionsReqType Complex Type
FindTransactions is used to search all current gateway transactions based on provided filter criteria.
Note: When possible, searching should be done by TxnId. This is a single transaction search unless used in conjunction with FindHistoryInd. Any additional criteria is ignored.
Note: The gateway is not a long-term storage service. Generally, data is only available for 90 days; however, recurring billing data is saved for two years. For longer periods, Heartland offers other services. Further information can be provided during boarding and certification.
|
All
|
Criteria optional SearchCriteriaType Complex Type
If the client does not have the associated transaction id or needs to search for multiple transactions, these filters can be applied.
Any transactions returned will match all criteria provided. Each filter is an exact match unless otherwise stated.
Note: Clients should make every effort to minimize the result set from a search. Breaking a search into parts based on date is a great way to do this. Response timeouts should also be adjusted accordingly as a search should not be expected to return in the same time as a transaction.
|
Sequence optional
|
StartUtcDT optional xs:dateTime
Start date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, start date time will be defaulted to six days prior at 00:00:00.
Transactions must have been run at or after this time to be returned.
|
|
EndUtcDT optional xs:dateTime
End date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, start date time will be defaulted to tomorrow at 00:00:00.
Transactions must have been run before or at this time to be returned.
Note: The end date/time must be after the start date/time.
|
|
CardNbrFirstSix optional Restriction of xs:string
The card number must start with this string.
|
|
CardNbrLastFour optional Restriction of xs:string
The card number must end with this string.
|
|
InvoiceNbr optional Restriction of xs:string
A specific invoice number; originally supplied in AdditionalTxnFields or DirectMktInvoiceNbr in DirectMktData
|
|
ServiceName 0..15 Restriction of serviceNameType Simple Type
A list of transaction types to search for (i.e. CreditSale); see the associated Type enumerations for specific values supported.
Note: If not supplied, 'all' is assumed.
|
|
PaymentType 0..2 paymentTypeType Simple Type
A list of payment methods to search for (i.e. Credit, Debit, etc.); see the associated Type enumerations for specific values supported.
Note: If not supplied, 'all' is assumed.
|
|
CardType 0..8 CardTypeType Simple Type
A list of card types to search for (i.e. VISA, MC, etc.); see the associated Type enumerations for specific values supported.
Note: If not supplied, 'all' is assumed.
|
|
IssuerResult optional Restriction of xs:string
A specific resulting status based on the issuer response:
- F - full approvals
- P - partial approvals
- A - all approvals (full and partial)
- D - declines
- FR - fraud declines
Note: If not sent then all will be included.
|
|
IssTxnId optional xs:string
A specific issuer transaction identifier
|
|
RefNbr optional xs:string
A specific retrieval reference number
|
|
ClerkID optional Restriction of xs:string
|
|
BatchSeqNbr optional xs:int
A specific batch sequence number
|
|
DisplayName optional Restriction of xs:string
A specific user display name
Note: This field is for future use and is ignored.
|
|
AcctNbrLastFour optional Restriction of xs:string
The check account number must end with this string
|
|
BankRoutingNbr optional Restriction of xs:string
A specific routing number
|
|
CheckNbr optional Restriction of xs:string
|
|
CheckFirstName optional Restriction of xs:string
A specific first name on the check
|
|
CheckLastName optional Restriction of xs:string
A specific last name on the check
|
|
CheckName optional Restriction of xs:string
A specific business name on the check
|
|
GiftCurrency optional currencyType Simple Type
A specific type of gift currency; see the associated Type enumerations for specific values supported
Note: If not supplied, 'all' is assumed.
|
|
GiftMaskedAlias optional Restriction of xs:string
A specific gift card alias
|
|
AltPaymentStatus optional Restriction of xs:string
A payment status of Altpayment transaction
|
|
SiteId optional siteIdType Simple Type
The Site identifier to query.
Note: The Site must belong to the same License as the requesting Site and Device. The Device identifier must also be specified. The Merchant must be enabled for this functionality.
|
|
DeviceId optional deviceIdType Simple Type
The Device identifier to query.
Note: The Device must belong to the Site in the request header or request body if used. The Merchant must be enabled for this functionality.
|
| |
|
|
|
TxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates a specific transaction to be returned.
If supplied, the search will return a single record unless used in conjunction with FindHistoryInd. Otherwise, any other criteria is ignored.
Note: This is the value referred to as GatewayTxnId in other messages.
|
|
FindHistoryInd optional booleanType Simple Type
Indicates whether to return any subsequent transactions associated with the Gateway-generated transaction identifier supplied.
Note: This will be ignored if the TxnId is not supplied.
|
| |
|
|
Sequence
|
ReturnAttachmentTypesOnly optional xs:boolean
Indicates that only the attachment types (no data) should be returned in the response; default is 'false'
|
|
AttachmentDataId optional xs:int
When specified, only the requested attachment will be returned
| | |
|
|
All
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
| | |
|
|
All
| |
|
|
|
GiftCardActivate PosGiftCardActivateReqType Complex Type
GiftCardActivate is used to activate a new stored value account and load it with an initial balance. If the specified stored value account is already active, the request will fail.
Note: Stored value accounts can also be activated implicitly via the GiftCardAddValue method depending on the platform configuration for a customer's specific program.
Note: This method supports loyalty points.
|
All
|
|
All
|
CardData GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
|
|
Currency optional currencyType Simple Type
Identifies the currency of the transaction amount; see the associated Type enumerations for specific values supported.
|
|
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
|
|
All
|
CardData GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
|
|
Currency optional currencyType Simple Type
Identifies the currency of the transaction amount; see the associated Type enumerations for specific values supported.
|
|
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
|
| | | |
|
GiftCardAlias PosGiftCardAliasReqType Complex Type
GiftCardAlias allows the client to manage stored account aliases. An alias is an alternate identifier used to reference a stored value account. Restrictions on the possible values of alias must be obtained from the gift processor.
|
All
|
|
All
|
Action Restriction of xs:string
The action to perform on the associated alias
Valid values include:
- CREATE provides a way to create a new account and assign a value to it as an alias (typically a phone number). The new account does not have a card associated with it.
- ADD provides a way to assign a value as an alias to a stored value account so that it can be used in place of a card or other device.
- DELETE allows a previously created alias to be removed from a stored value account.
|
|
CardData optional GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
|
|
Alias Restriction of xs:string
| | | | |
|
|
All
|
|
All
|
CardData GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
| | | | |
|
GiftCardCurrentDayTotals xs:anySimpleType
GiftCardCurrentDayTotals is used to retrieve stored value transaction totals for the current day.
Note: This has been obsoleted and should no longer be used. See FindTransactions for an alternative.
|
|
GiftCardDeactivate PosGiftCardDeactivateReqType Complex Type
GiftCardDeactivate is used to deactivate an active stored value account that otherwise has not been used. Attempts to deactivate an account that is not active or has had activity will fail.
Note: For some gift processors, once a stored value account has been deactivated it can never be re-activated.
|
All
|
|
All
|
CardData GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
| | | | |
|
GiftCardPreviousDayTotals xs:anySimpleType
GiftCardPreviousDayTotals is used to retrieve stored value transaction totals for the previous day.
Note: This has been obsoleted and should no longer be used. See FindTransactions for an alternative.
|
|
GiftCardReplace PosGiftCardReplaceReqType Complex Type
GiftCardReplace transfers balances from one stored value account to another. This is typically to replace a lost or stolen account with a new one or to consolidate two or more accounts into a single account. After a transfer has completed, the source account is closed/deactivated and can no longer be used. The balance for the destination account is returned in the response.
|
|
GiftCardReversal PosGiftCardReversalReqType Complex Type
GiftCardReversal is used to cancel a prior stored value transaction. This should be used in timeout situations or when a complete response is not received. In either case, the client is unsure of the outcome of the prior transaction.
This can be used on prior transactions of the following types:
- GiftCardActivate
- GiftCardAddValue
- GiftCardSale
- GiftCardReward
Note: When reversing a transaction, all changes to the account are cancelled, including any additional value added by rewards programs or automated promotions.
Note: If the reversal also fails to return a complete response (likely due to a timeout), wait until connectivity is restored and try again or contact support to ensure the proper result was achieved.
|
All
|
Block1 GiftCardReversalReqBlock1Type Complex Type
Contains a series of required and optional elements
Note: One of the following fields must be provided:
- CardData
- ClientTxnId
- GatewayTxnId
If more than one of these is provided, they must reference the same original transaction or payment information.
Note: Always run reversals with either GatewayTxnId or ClientTxnId. If only CardData is used the results are not guaranteed as the original transaction may not be uniquely identified.
|
All
|
CardData optional GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
|
|
GatewayTxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
ClientTxnId optional clientIdType Simple Type
Client generated transaction identifier sent in the request of the original transaction. This indicates the transaction to be updated.
Note: Client generated ids are critical for situations when the client never receives a response from the gateway.
|
| | | |
|
GiftCardReward PosGiftCardRewardReqType Complex Type
GiftCardReward is used when an account holder makes a payment using a payment form other than a stored value account (e.g. cash or credit card). The account holder may present their stored value account to earn points or other loyalty rewards, which would be added to their account. If successful, the rewarded amount is returned in the response.
Note: This transaction is not used for purchases. Instead, the purchase amount is used to help determine what potential rewards may be added based on the merchant's loyalty and rewards program.
|
All
|
|
All
|
CardData GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
|
|
Amt amtTypeGlobal Simple Type
The purchase amount of the previous transaction to use for rewards calculation; this includes all other "Info" amounts provided as part of this request
|
|
Currency optional currencyType Simple Type
Identifies the currency of the transaction amount; see the associated Type enumerations for specific values supported
|
|
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.
|
|
TaxAmtInfo optional amtTypeGlobal Simple Type
Tax amount information; this defines the portion of the total amount provided as part of this request that was specifically for tax. This is informational only and will not alter the amount processed as part of the transaction.
| | | | |
|
GiftCardSale PosGiftCardSaleReqType Complex Type
GiftCardSale is used to redeem value from a stored value account.
Note: Partial approvals are supported by default. If the account balance is non-zero but insufficient to cover the full redemption amount, the remaining balance is drained and the amount still owed is returned in the response for additional payment. The merchant may accept any additional tender to cover the amount still owed. If the account holder is unable to provide additional payment and the purchase is cancelled, this transaction should be voided to return the balance back to the account. See the "split tender card amount" and "split tender balance due amount" fields in the response.
|
All
|
|
All
|
CardData GiftCardDataType Complex Type
A common element used in stored value transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, card number, alias, and token information. It also includes options for specifying how the supplied data has been encrypted.
|
|
Amt amtTypeGlobal Simple Type
The amount to be deducted (redeemed) from the stored account; this includes all other "Info" amounts provided as part of this request.
|
|
Currency optional currencyType Simple Type
Identifies the currency of the transaction amount; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
TaxAmtInfo optional amtTypeGlobal Simple Type
Tax amount information; this defines the portion of the total amount provided as part of this request that was specifically for tax. This is informational only and will not alter the amount processed as part of the transaction.
|
|
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
|
| | | |
|
GiftCardTip PosGiftCardTipReqType Complex Type
GiftCardTip is used to add tip to an existing GiftCardSale. If successful, the tip amount will be subtracted from the stored value account.
Note: This transaction is for future use.
|
All
|
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
|
|
Currency optional currencyType Simple Type
Identifies the currency of the transaction amount; see the associated Type enumerations for specific values supported.
| | | | |
|
GiftCardVoid PosGiftCardVoidReqType Complex Type
GiftCardVoid is used to cancel a prior successful transaction. When voiding a transaction, all changes to the account are reversed, including any additional value added by rewards programs or automated promotions.
This can be used on prior transactions of the following types:
- GiftCardActivate
- GiftCardAddValue
- GiftCardDeactivate
- GiftCardReplace
- GiftCardSale
- GiftCardReward
Note: Only the most recent transaction is allowed to be referenced as the prior transaction for a gift void. For example, if an activate is run and then an add value is run, only the add value can be voided.
|
All
|
|
All
|
GatewayTxnId txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates the transaction to be updated.
| | | | |
|
|
All
| |
|
|
All
|
LocalDateTime optional xs:dateTime
Local Date and Time must be included here if PosReqDT is not set in the header. This value will override the header PosReqDT when both are present.
| | |
|
|
All
|
SettingActions
The operations that can be performed on the associated settings
|
Choice
| | | |
|
|
All
|
TokenValue xs:string
Multi-use token returned on a prior transaction to be used as a reference to a payment method; used to replace card data for this transaction.
|
|
TokenActions
The operations that can be performed on the data referenced by the token.
|
Choice
| | | |
|
|
All
|
UserActions
The operations that can be performed on the merchant's users
|
Choice
| | | |
|
OverrideFraudDecline PosOverrideFraudDeclineReqType Complex Type
OverrideFraudDecline is used to process a CreditSale, CreditAuth or CreditReturn that was previously declined due to fraud. An override causes the fraud concerns to be ignored. The use of this function on a client should require management approval. This can only be done once, and for the original auth amount.
Note: This is for internal use only.
|
All
|
|
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.
|
|
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
| | | | |
|
ParameterDownload PosParameterDownloadReqType Complex Type
ParameterDownload is used to initiate an EMV parameter download by clients interfacing to an EMV device. Typically, the client will only download new parameters after receiving an indicator that a download is needed in a prior response message. In addition, the client should time these downloads to be done between batches and during an idle time if possible.
Note: See the PDLNotification indicator in the response header.
|
All
|
|
Choice
|
PDLBlockReq xs:string
Pass-through PDL block request; full definition of this field must be obtained from the Parameter Data Download system.
|
| | | |
|
PrePaidAddValue PosPrePaidAddValueReqType Complex Type
PrePaidAddValue is used to increase the balance associated with a prepaid card. The transaction is placed in the current open batch. If a batch is not open, this transaction creates an open batch.
Note: For future use
|
All
|
|
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.
|
|
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
|
|
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.
|
| | | |
|
RecurringBilling PosRecurringBillReqType Complex Type
RecurringBilling authorizes a one-time or scheduled recurring transaction. The authorization is placed in the current open batch. If a batch is not already open, this transaction creates an open batch.
A scheduled recurring transaction is the default, but a one-time payment can be made by setting the OneTime value to 'Y'. One-time payments may be processed using card data managed by PayPlan. In this case, the stored payment PaymentMethodKey should be provided instead of CardData.
The PayPlan application allows a merchant to set up and schedule recurring payments, but also provides other features including customer information management, secure payment (card and ACH) information storage (card-on-file), and automated email notifications to customers.
|
All
|
|
All
|
CardData optional CardDataType Complex Type
A common element used in several different transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.
|
|
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.
|
|
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.
|
|
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.
|
|
DebtRepaymentIndicator optional debtRepaymentType Simple Type
Allows for flagging this transaction as being against a debt obligation. Only use this field with Heartland's explicit direction. This flag is used to identify transactions that might qualify for VISA's Debt Repayment Program special interchange rates.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
| | | |
|
RecurringBillingAuth PosRecurringBillReqType Complex Type
RecurringBillingAuth authorizes a one-time or scheduled recurring transaction. These authorization only transactions are not added to the batch to be settled. They can be added to a batch at a later time using CreditAddToBatch. Approved authorizations that have not yet been added to a batch are called open auths.
A scheduled recurring transaction is the default, but a one-time payment can be made by setting the OneTime value to 'Y'. One-time payments may be processed using card data managed by PayPlan. In this case, the stored payment PaymentMethodKey should be provided instead of CardData.
The PayPlan application allows a merchant to set up and schedule recurring payments, but also provides other features including customer information management, secure payment (card and ACH) information storage (card-on-file), and automated email notifications to customers.
|
All
|
|
All
|
CardData optional CardDataType Complex Type
A common element used in several different transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.
|
|
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.
|
|
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.
|
|
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.
|
|
DebtRepaymentIndicator optional debtRepaymentType Simple Type
Allows for flagging this transaction as being against a debt obligation. Only use this field with Heartland's explicit direction. This flag is used to identify transactions that might qualify for VISA's Debt Repayment Program special interchange rates.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
| | | |
|
ReportActivity PosReportActivityReqType Complex Type
ReportActivity returns all activity between the client devices and gateway for a period of time. This can be filtered to a single device if needed.
Note: This has been obsoleted and should no longer be used. See FindTransactions for an alternative.
|
All
|
RptStartUtcDT optional xs:dateTime
Start date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, start date time will be defaulted to today at 00:00:00.
Transactions must have been run at or after this time to be returned.
|
|
RptEndUtcDT optional xs:dateTime
End date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, end date time will be defaulted to tomorrow at 00:00:00.
Transactions must have been run before or at this time to be returned.
Note: The end date/time must be after the start date/time.
|
|
DeviceId optional deviceIdType Simple Type
Device identifier used to filter the report results to a particular device.
Note: If not provided, all devices associated with the site will be included.
|
| |
|
|
All
|
BatchId optional batchIdType Simple Type
Batch identifier used to filter the report results to a particular batch.
Note: If this is not provided, results will be returned for the current open batch.
|
|
SiteId optional siteIdType Simple Type
The Site identifier to query.
Note: The Site must belong to the same License as the requesting Site and Device. The Device identifier must also be specified. The Merchant must be enabled for this functionality.
|
|
DeviceId optional deviceIdType Simple Type
The Device identifier to query.
Note: The Device must belong to the Site in the request header or request body if used. The Merchant must be enabled for this functionality.
| | |
|
|
All
|
RptStartUtcDT optional xs:dateTime
Start date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, start date time will be defaulted to six days prior at 00:00:00.
Batches must have been opened at or after this time to be returned.
|
|
RptEndUtcDT optional xs:dateTime
End date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, end date time will be defaulted to tomorrow at 00:00:00.
Batches must have been opened before or at this time to be returned.
Note: The end date/time must be after the start date/time.
|
|
DeviceId optional deviceIdType Simple Type
Device identifier used to filter the report results to a particular device.
Note: If not provided, all devices associated with the site will be included.
|
| |
|
|
All
|
BatchId optional batchIdType Simple Type
Batch identifier used to filter the report results to a specific batch.
Note: If this is not provided, results will be returned for the current open batch.
|
|
RptStartUtcDT optional xs:dateTime
Start date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, dates are not used.
Transactions must have been run at or after this time to be returned.
|
|
RptEndUtcDT optional xs:dateTime
End date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, dates are not used.
Transactions must have been run before or at this time to be returned.
Note: The end date/time must be after the start date/time.
|
|
ClerkID optional Restriction of xs:string
Clerk id used to filter the report results
|
|
SiteId optional siteIdType Simple Type
The Site identifier to query.
Note: The Site must belong to the same License as the requesting Site and Device. The Device identifier must also be specified. The Merchant must be enabled for this functionality.
|
|
DeviceId optional deviceIdType Simple Type
The Device identifier to query.
Note: The Device must belong to the Site in the request header or request body if used. The Merchant must be enabled for this functionality.
| | |
|
|
All
|
DeviceId optional deviceIdType Simple Type
Device identifier used to filter the report results to a particular device.
Note: If not provided, all devices associated with the site will be included.
|
| |
|
|
All
|
ReturnHeaderOnly booleanType Simple Type
Indicates whether the report header containing transaction count information matching the given search criteria is the only information returned; default is 'N'.
|
|
RptStartUtcDT optional xs:dateTime
Start date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, start date time will be defaulted to six days prior at 00:00:00.
Transactions must have been run at or after this time to be returned.
|
|
RptEndUtcDT optional xs:dateTime
End date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time). If the element is not present, end date time will be defaulted to tomorrow at 00:00:00.
Transactions must have been run before or at this time to be returned.
Note: The end date/time must be after the start date/time.
|
|
|
Choice
| |
| |
|
|
All
|
TxnId optional txnIdType Simple Type
Gateway-generated transaction identifier returned in the response of the original transaction. This indicates a specific transaction to be returned.
Note: This is the value referred to as GatewayTxnId in other messages.
|
| |
|
|
All
|
StartUtcDT optional xs:dateTime
Start date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time).
|
|
EndUtcDT optional xs:dateTime
End date time used to filter the results to a particular date time range. The date time must be specified in UTC (Coordinated Universal Time).
| | |
|
|
All
|
Block1 RewardCashQueryBlock1Type Complex Type
RewardCashQuery returns available reward point balance for a participating accounts. Allowed for Reward Cash terminals configured for the Asia Pacific region only.
Note: This transaction is for Future Use.
|
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.
|
| | | |
|
|
All
|
Block1 RewardCashRedeemBlock1Type Complex Type
RewardCashRedeem is used to redeem available reward points for a participating account. These authorizations are automatically added to the reward cash batch to be settled.
If a batch is not already open this transaction will create one.
Note: Allowed for Reward Cash terminals configured for the Asia Pacific region only.
Note: This transaction is for Future Use.
|
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.
|
| | | |
|
|
All
|
|
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 SendFundCardDataType 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.
|
|
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.
|
|
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
|
|
Ecommerce optional eCommerceType Simple Type
Identifies this transaction as eCommerce or mail order/telephone order; see the associated Type enumerations for specific values supported.
|
|
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.
|
|
SendFundsData optional SendFundsDataType 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.
| | | | |
|
SendReceipt PosSendReceiptReqType Complex Type
SendReceipt allows a client to send a receipt from a prior transaction out to specific destinations. The prior transaction must belong to the site and device referenced in the header.
Note: This is for internal use only.
|
|
TestCredentials xs:anySimpleType
TestCredentials validates the credentials passed in the header, but does not perform an action.
Note: TestCredentials should only be used at the beginning of the certification period to validate credentials and connectivity to the certification environment. This should not be used as a "heartbeat" check and is not required for processing with the gateway.
|
|
|
All
|
|
All
|
CardData optional CardDataType Complex Type
A common element used in several different transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.
| | | | |
|
|
All
|
ReportEndDate optional xs:dateTime
End of the reporting date. If null, current date is used.
|
|
Limit optional Restriction of xs:int
Records to be returned limit. Default is no limit.
|
|
Offset optional Restriction of xs:int
Records to be returned limit. Default is no limit.
|
|
TokenValue optional xs:string
Multi-use or single-use token; used as a reference to a payment method for this transaction.
|
| |
|
|
All
|
|
All
|
CardData optional CardDataType Complex Type
A common element used in several different transactions for supplying payment method information.
This includes a choice of typical payment representations like track data, manually entered data, and token information. It also includes options for specifying how the supplied data has been encrypted or to request a multi-use token be supplied in the response.
|
|
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.
| | | | | |
