|
Sequence
|
Header
The header includes credentials and transaction tracking information. These fields are included as optional in the schema to allow different options for providing credentials.
Note: One of the following combinations is required:
- License, Site, Device, Username, and Password or
- Secret API key
|
All
|
Password optional passwordType Simple Type
Password for the associated user; a temp password will be provided during the boarding process but must be altered before it is used for transaction processing
|
|
CredentialToken optional xs:string
The credential token is used to indicate a user session. Currently, this option is only available to internal Heartland applications and should not be used by integrators.
|
|
SiteTrace optional siteTraceType Simple Type
This element can be used by the client to provide a value that can be searched for later. Clients are free to provide any value that is useful to them but it must not contain sensitive data. This will also be echoed in the response if present.
|
|
DeveloperID optional Restriction of xs:string
Identifier assigned by Heartland during the certification process; this field is optional to support legacy integrations, but all new integrations require this value.
|
|
VersionNbr optional Restriction of xs:string
Software version number assigned by Heartland during the certification process; this field is optional to support legacy integrations, but all new integrations require this value.
|
|
OptionalPosData optional Restriction of xs:string
OptionalPosData as defined by your certification analyst. Required for Canadian integrations.
|
|
ClerkID optional Restriction of xs:string
Identifier assigned by the merchant or client to the clerk running this transaction; this must not contain sensitive data
|
|
|
All
| |
|
ClientTxnId optional clientIdType Simple Type
A client-generated transaction id. This must be unique for this device. If present, it will be attached to this transaction and echoed in the response. This allows the client to run a timeout reversal against a unique transaction in the event that a response is never received. When a response is received, the client will receive a gateway-generated transaction id.
|
|
UniqueDeviceId optional uniqueDeviceIdType Simple Type
A client-supplied device identifier to be sent when transactions for multiple devices are aggregated in the same batch. If present, the field will be sent to the issuer on authorization and settlement requests and echoed in the response header.
|
|
|
All
|
SAFOrigDT optional xs:dateTime
Date and time when the transaction was originally initiated.
| | |
|
SecretAPIKey optional secretAPIKeyType Simple Type
API key that can be used in place of license, site, device, username, and password. An API will be tied to a specific environment (i.e. certification or production).
Note: The use of SecretAPIKey is restricted.
|
|
PosReqDT optional xs:dateTime
POS request date and time. Required for Interac processing.
Note:This field is required for Canadian merchants.
|
|
DeviceConfiguration optional DeviceConfigurationType Complex Type
Device capabilities and/or attributes needed by a Host processor that are not otherwise able to be determined. Please refer to the Developer Guide for further details as this data may be required for certain Host processors..
|
All
|
Capabilities optional Restriction of xs:string
Capabilities for a Device
|
|
SerialNbr optional Restriction of xs:string
Serial number of PIN pad or PIN entry device (PED).
Note: Required for Interac debit services in Canada.
|
|
TxnMCC optional mccType Simple Type
MCC value that is passed from POS.
For original transactions only. Not used for transactions where the request contains an original transaction id.
| | |
|
x_global_transaction_id optional x_global_transaction_idType Simple Type
A client-generated transaction ID used for certain API integrations, which is echoed in the response. When not provided a value will be generated.
Note: If either x_global_transaction_id or x_global_transaction_source is present, both must be provided.
Note: This is for internal use only.
|
|
x_global_transaction_source optional x_global_transaction_sourceType Simple Type
A client-generated value used for certain API integrations, which is echoed in the response. When not provided a value will be generated.
Note: If either x_global_transaction_id or x_global_transaction_source is present, both must be provided.
Note: This is for internal use only.
|
|
CustomHashReq optional booleanType Simple Type
Indicates whether to return a hashed value of the card number using a custom salt value.
Note: For use by participating merchants only.
|
|
UPIAuthNetwork optional booleanType Simple Type
Indicates the authorization network to be used for co-branded UnionPay cards, based on cardholder choice at the Point of Sale. If True, authorizations will route to the UnionPay network. For UK merchants only.
Note: For future use
|
|
SDKNameVersion optional Restriction of xs:string
Name and Version of the SDK used for integration, where applicable.
|
|
RetryInd optional booleanType Simple Type
Indicates that this transaction is a retry of the previous, in case if a timeout error occurred. GTID and Source fields are required for RetryInd.
The time alloted for retries is 90 minutes.
Note: It is internal only
| | |
|
|
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
|
Buyer optional
Buyer Information for the authorization
|
|
Shipping optional
Shipping Information for the authorization
|
|
Payment optional
Payment Information for the authorization
|
|
LineItem optional
Line Item purchase information for the authorization
| | |
|
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
| | |
|
|
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
|
|
Payment optional
Payment Information for the new authorization
|
|
LineItem optional
Line Item purchase information for the new authorization
| | |
|
|
All
|
Buyer optional
Buyer Information for the session
|
|
Shipping optional
Shipping Information for the session
|
|
Payment optional
Payment Information for the session
|
|
LineItem optional
Line Item purchase information for the session
| | |
|
|
All
|
Buyer optional
Buyer Information for the order
|
|
Shipping optional
Shipping Information for the order
|
|
Payment optional
Payment Information for the order
|
|
LineItem optional
Line Item purchase information for the order
| | |
|
|
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
| | |
|
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
|
|
Shipping optional
Shipping Information for the sale
|
|
Payment optional
Payment Information for the sale
|
|
LineItem optional
Line Item purchase information for the sale
| | |
|
|
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
| |
|
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
| |
|
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
| |
|
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
| |
|
|
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.
| | |
|
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.
| | |
|
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
| |
|
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
| |
|
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
| |
|
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.
|
|
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.
|
|
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.
|
| |
|
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
| |
|
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.
|
| |
|
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
| |
|
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
| |
|
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
| |
|
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.
| | |
|
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
| |
|
|
All
| |
|
|
All
| |
|
|
All
| |
|
|
All
| |
|
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.
| | |
|
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.
|
|
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.
|
|
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.
|
| |
|
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
| |
|
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.
| | |
|
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 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.
|
| |
|
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.
| | |
|
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
| |
|
|
All
| |
|
|
All
| |
|
|
All
| |
|
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
| |
|
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
| |
|
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.
|
|
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
| |
|
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
| |
|
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
| |
|
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.
|
All
| |
|
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.
| | |
|
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
| |
|
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
| |
|
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
| |
|
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
| |
|
|
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
| | |
|
|
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.
| | |
|
|
All
|
UserActions
The operations that can be performed on the merchant's users
| | |
|
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
| |
|
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
| |
|
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
| |
|
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
| |
|
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
| |
|
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.
|
| |
|
|
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
|
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
| |
|
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.
|
All
| |
|
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
|
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
| | | | |