Pre-Card Entry

Overview

This hook allows activation before card detection but after modifiers such as Tips, catering to use cases where transactions are processed through alternative means, such as third-party gift cards or digital wallets, loyalty or charity.

Request Structure

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
action	String	"PRE_CARD_ENTRY"	V30	Required
transactionType	String	Transaction that the terminal is currently performing. Valid values: "PURCHASE" "PRE_AUTHORIZATION" "PRE_AUTHORIZATION_COMPLETION" "REFUND" "INDEPENDENT_REFUND" "VOID"	F8	Required
requestDateTime	String	Date and time of the request (YYYY-MM-DDTHH:MM:SSZ). The format is based on the standard RFC 3339 internet profile — a subset of ISO 8601.	F20	Required
language	String	Terminal Language. Provides the two-letter language code according to the ISO 639-1 standard. For a complete list of language codes, visit: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.	V30	Required
correlationId	String	Correlates a series of requests within the same flow.	V50	Required
terminalId	String	Terminal ID	F8	Required
merchantId	String	Merchant ID	V13	Required
merchantName	String	Merchant Name	V100	Required
merchantAddress	Object	Merchant Address	-	Required
unitNumber	String	Unit number	V19	Optional
streetNumber	String	Street number	V19	Optional
streetName	String	The full street name	V100	Optional
province	String	Province or state ISO 3166-2 code	V3	Optional
city	String	Name of the city / locality	V100	Optional
postalCode	String	Zip code or postal code	V30	Optional
country	String	The country code according to iso-3166-1-alpha-2	V2	Optional
totalAmount	Object	Total transaction amount	-	Required
amount	String	The value must be in cents. Therefore $10.59 must be sent as 1059	V10	Required
currency	String	Provides the three-letter currency code according to the ISO 4217 standard. For a complete list of currency codes, visit: ISO 4217	V4	Required
amountDetails	Object	Amount Details breakdown	-	Optional
tipAmount	Object	Tip transaction amount	-	Optional
amount	String	The value must be in cents. Therefore $10.59 must be sent as 1059	V10	Required
currency	String	Provides the three-letter currency code according to the ISO 4217 standard. For a complete list of currency codes, visit: ISO 4217	V4	Required
subtotalAmount	Object	Subtotal amount (before taxes)	-	Required
amount	String	The value must be in cents. Therefore $10.59 must be sent as 1059	V10	Required
currency	String	Provides the three-letter currency code according to the ISO 4217 standard. For a complete list of currency codes, visit: ISO 4217	V4	Required
taxes	Array	Maximum of 5 tax objects	-	Required
taxName	String	Name to be displayed on receipt (hst, gst etc)	V15	Required
taxAmount	Object	Corresponding amount	-	Required
amount	String	The value must be in cents. Therefore $10.59 must be sent as 1059	V10	Required
currency	String	Provides the three-letter currency code according to the ISO 4217 standard. For a complete list of currency codes, visit: ISO 4217	V4	Required

{
  "apiVersion": "2025-01-09",
  "action": "PRE_CARD_ENTRY",
  "transactionType": "PURCHASE",
  "requestDateTime": "2025-12-31T23:59:60Z",
  "language": "en",
  "correlationId": "example_correlationId",
  "terminalId": "example_terminalId",
  "merchantId": "example_merchantId",
  "merchantName": "example_merchantName",
  "merchantAddress": {
    "unitNumber": "1A",
    "streetNumber": "12",
    "streetName": "Yonge St",
    "province": "ON",
    "city": "Toronto",
    "postalCode": "M4W 3H7",
    "country": "CA"
  },
  "totalAmount": {
    "amount": "12000",
    "currency": "CAD"
  },
  "amountDetails": {
    "subtotalAmount": {
      "amount": "10000",
      "currency": "CAD"
    },
    "tipAmount": {
      "amount": "1000",
      "currency": "CAD"
    },
    "taxes": [
      {
        "taxName": "HST",
        "taxAmount": {
          "amount": "500",
          "currency": "CAD"
        }
      },
      {
        "taxName": "GST",
        "taxAmount": {
          "amount": "500",
          "currency": "CAD"
        }
      }
    ]
  }
}

Response Structure

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
correlationId	String	Echo from the request	V50	Required
responseDateTime	String	Date and time of the response (YYYY-MM-DDTHH:MM:SSZ). The format is based on the standard RFC 3339 internet profile—a subset of ISO 8601.	F20	Required
action	String	"PRE_CARD_ENTRY"	V50	Required
status	String	HTTP Status Codes for the overall transaction request	F3	Required
updatedTotalAmount	Object	Total transaction amount modified by the third party application. This amount can be greater than or less than the original transaction amount.	-	Optional
amount	String	The value must be in cents. Therefore $10.59 must be sent as 1059	V10	Required
currency	String	Provides the three-letter currency code according to the ISO 4217 standard. For a complete list of currency codes, visit: ISO 4217	V4	Required

{
  "apiVersion": "3.0",
  "correlationId": "example_correlationId",
  "responseDateTime": "2025-12-31T23:59:60Z",
  "action": "PRE_CARD_ENTRY",
  "status": "200",
  "updatedTotalAmount": {
    "amount": "2000",
    "currency": "CAD"
  }
}