Skip to main content
In-Store Payments

Card transaction responses

Use the following information as a reference for interpreting card transaction responses from the Payment Terminal Application.

Response fields

The API response contains two fields related to the transaction type: transactionType and type. Use the value in type for business logic, such as internal calculations. Use the value in transactionType for user interface (UI) display.

The following table lists and defines the card transaction response fields.

Card transaction response fields
Field                                              Description
processorLine1 Top processor line.
headerLine1 Response header line.
headerLine2 Response header line.
headerLine3 Response header line.
headerLine4 Response header line.
headerLine5 Response header line.
headerLine6 Response header line.
processorLine2 Bottom processor line.
terminalID Terminal ID value configured for your merchant account.
reference

A point-of-sale (POS)-generated reference number.

  • Maximum of 12 alphanumeric characters.
  • If no value is supplied, a value will be generated by our payment host.
  • If this field is used, it must be unique per batch.
  • This value is inserted into the Retrieval Reference Number (RRN) field of the transaction response receipt data.

merchantID

 Merchant ID value configured for your merchant account.
storeID Store identification.
dateTime

Print the local date and time of the transaction on the receipt. The dateTime value has a custom format of [MM]-[DD]-[YYYY] [hh]:[mm]:[ss]. For example:

12-31-2024 13:59:59

invoice
  • Echo of the invoice number in the request. 
  • Maximum of 6 numeric characters.

customer
  • The customer number associated to the transaction. 
  • Maximum of 8 alphanumeric characters.

ticket
  • The ticket number associated to the transaction. 
  • Maximum 6 alphanumeric characters.

purchase
  • The purchase number to be associated to the transaction. 
  • Maximum 8 alphanumeric characters.
commercialCardType

When present, the card is assumed to be a commercial card. This field determines the type of commercial card:

  • 0 — Corporate
  • 1 — Purchasing

customerReference
  • Required for commercial card processing. 
  • Contains the customer reference number. 
  • Maximum of 17 alphanumeric characters.
operation Echo of the operation value in the request. For example, Transaction
type Echo of the type value in the request.
transactionType

Transaction type in printable form.

Value:

  • SALE
  • FORCE SALE
  • REFUND
  • AUTHORIZATION
  • STATUS CHECK
  • MOTO SALE
  • VOID
  • COMPLETION
  • BALANCE INQUIRY
  • CLOSE BATCH
account The account number masked according to Payment Card Industry (PCI) and card brand requirements.
accountType

Returns the determined account type for an Interac card.

  • 0=None
  • 1=Checking/Chequing
  • 2=Savings
cardBrand The card brand label inferred from the card Bank Identification Number (BIN).

cardToken

 Card token used for credential on file transactions.
entryMode

Indicates the interface used to capture the card data.

Values:

  • Manual
  • Swiped
  • Chip_Swiped
  • Chip
  • Contactless
  • COF

requestedAmount

 The original amount of the transaction. The value format is numeric with a single decimal between major and minor denominations.
surchargeAmount The surcharge amount (if applied to the transaction).
surchargePercentage The applied surcharge percentage (if applicable).
surchargeFixed The applied surcharge fixed amount (if applicable).
taxAmount The tax amount (if applied to the transaction).
subTotalAmount The subTotalAmount comprising the authorized amount, the surcharge, and tax.
tipAmount The tip amount as entered during the transaction.
cashBackAmount The cash back amount (if applicable).
totalAmount The sum of all the amounts in the transaction.
dueAmount If the transaction is partially authorized, this field contains the difference between the totalAmount and the amount approved by the issuer.
balance Contains the account balance provided by the issuer (if available).

transactionID

 Transaction ID number.

batchNumber

 Indicates the current batch number. The number is locally initialized with 0 and is updated by our payment host responses.
traceNumber Contains the trace number returned by our payment host for Electronic Benefits Transfer (EBT) and debit transactions.
result The result code from the Payment Terminal Application. Refer to the table of result codes for each value and definition.

approval
  • Whether the transaction is approved or declined. 
  • For errors and cancellations, this field contains the value declined. 
  • Determine specific information about the cause of a decline in result, responseCode, or hostMessage.

errorMessage
  • The display message from the host containing the description of the transaction decline. 
  • Applies to declined transactions.
hostError
  • The payment host numeric code for the decline. 
  • Only applies to declined transactions. 
  • Approved transactions contain 00000.

authCode
  • The authorization approval code returned from our payment host. 
  • This field only applies to approved transactions and is optional.

responseCode
  • The response code returned from our payment host. 
  • Only present when provided by our payment host.

preferredName
  • Print this name (application label) of the EMV application on the receipt. 
  • Only present on EMV and contactless payment (CTLS) transactions (if available). 
  • Maximum of 16 alphanumeric characters.
approvalMode

Indicates how the approval was obtained:

  • ISSUER

AID
  • Print the AID of the EMV application on the receipt. 
  • Only present on approved EMV transactions. 
  • Maximum of 32 alphanumeric characters.

TVR
  • Print the Terminal Verification Results value on the receipt. 
  • Only present on EMV and CTLS transactions (if available). 
  • Maximum of 10 alphanumeric characters.

IAD
  • Print the Issuer Application Data on the receipt. 
  • Only present on EMV and CTLS transactions (if available). 
  • Maximum of 64 alphanumeric characters.
AC
  • Print the Application Cryptogram on the receipt. 
  • Only present on EMV and CTLS transactions. 
  • Maximum of 16 alphanumeric characters.

TSI
  • Print the Transaction Status Information on the receipt. 
  • Only present on EMV and CTLS transactions (if available). 
  • Maximum of 4 alphanumeric characters.

ARC
  • Print the Authorization Response Code on the receipt. 
  • Only present on EMV and CTLS transactions (if available). 
  • Maximum of 4 alphanumeric characters.
cvm

Indicates the cardholder verification method. Present on approved transactions.

Value:

  • NO CVM
  • Signature
  • PIN Verified
  • PIN and Signature
signatureRequired

Indicates if a signature is required. Present on approved transactions. Only present if the signature is required and not electronically captured at the payment terminal device.

Value:

  • yes
  • no

signatureData
  • Contains the signature image electronically captured by the payment terminal device. 
  • Encoded in base64 format and represents a PNG picture.
uniqueTransactionID
  • Echo from the request or a 30 character unique ID generated by the Payment Terminal Application. 
  • The first 22 characters are used for reporting. 
  • This field is alphanumeric.

PARData

 Payment account reference data. Present if on the EMV or CTLS card or returned by our payment host.
cardTypeProcessed

Contains the card type as processed with the host.

Value:

  • 1 = Credit
  • 2 = Debit
  • 3 = Gift card
  • 4 = EBT

footerLine1Merchant

 Response footer line.

footerLine2Merchant

 Response footer line.

footerLine3Merchant

 Response footer line.

footerLine1Cardholder

 Response footer line.

footerLine2Mercholder

 Response footer line.

footerLine3Cardholder

 Response footer line.
demoMode

Indicates if the Payment Terminal Application is running in demo mode.

Value:

  • yes
  • no

Response fields by supported transaction type

A field's inclusion in a card transaction request or response is categorized as mandatory, optional, conditional, or present with the following definitions:

  • Mandatory (or M) fields are required to be present.
  • Optional (or O) fields are not required and depend on the transaction context.
  • Conditional (or C) fields are required to support a specific feature or scenario.
  • Present (or P) fields are included by default in a response.

The following table lists and defines the card transaction response fields supported by transaction type.

Card transaction response fields by supported transaction type
Field                                              Sale Force
Sale		 Refund Auth. Only Status Check MOTO Sale Void Completion Balance Inquiry Settlement

processorLine1

C

C

C

C

-

C

C

C

C

-

headerLine1

P

P

P

P

-

P

P

P

P

-

headerLine2

P

P

P

P

-

P

P

P

P

-

headerLine3

P

P

P

P

-

P

P

P

P

-

headerLine4

P

P

P

P

-

P

P

P

P

-

headerLine5

P

P

P

P

-

P

P

P

P

-

headerLine6

P

P

P

P

-

P

P

P

P

-
processorLine2

C

C

C

C

-

C

C

C

C

-
terminalID P P

P

P

P

P

P

P

P

-
reference

P

P

P

P

P

P

P

P

P

-

merchantID

P

P

P

P

P

P

P

P

P

-
storeID P

P

P

P

P

P

P

P

P

-
dateTime

P

P

P

P

P

P

P

P

P

-
invoice O

O

-

-

-

O

-

-

-

-
customer O

O

-

O

-

O

-

-

-

-
ticket O

O

-

O

-

O

-

-

-

-
purchase O

O

-

O

-

O

-

-

-

-
commercialCardType

O

-

-

-

-

-

-

-

-

-
customerReference O

-

-

-

-

-

-

-

-

-
operation P

P

P

P

P

P

P

P

P

P
transactionType

P

P

P

P

P

P

P

P

P

P
account P

P

P

P

P

P

P

P

P

-
accountType

C

C

C

-

-

-

-

C

-

-
cardBrand P

P

P

P

P

P

P

P

P

-
cardToken O

-

-

O

-

-

-

-

-

-
entryMode

P

P

P

P

P

P

P

P

P

-
requestedAmount O

O

O

O

-

O

O

O

O

-
surchargeAmount O

O

-

-

-

O

O

-

-

-
surchargePercentage O

O

-

-

-

O

-

-

-

-
surchargeFixed O

O

-

-

-

O

-

-

-

-
taxAmount O

O

O

-

-

O

O

O

-

-
subTotalAmount P

P

-

-

-

O

O

-

-

-
tipAmount O

O

-

-

-

O

O

-

-

-
cashBackAmount O

-

-

-

-

-

O

-

-

-
totalAmount P

P

P

P

-

P

P

P

-

-
dueAmount O

-

-

O

-

O

-

-

-

-
balance O

-

-

-

-

-

-

-

P

-
transactionID P

P

P

P

P

P

P

P

P

-
batchNumber P

P

P

P

P

P

P

P

P

P
traceNumber O

-

-

O

-

-

-

O

-

-
result P

P

P

P

P

P

P

P

P

P
approval P

P

P

P

P

P

P

P

P

-
errorMessage O

O

O

O

O

O

O

O

O

-
hostError O

O

O

O

O

O

O

O

O

-
authCode O

O

O

O

O

O

O

O

O

-
responseCode O

O

O

O

O

O

O

O

O

-
preferredName O

O

O

O

O

-

-

O

O

-
approvalMode

P

P

-

-

-

-

-

P

-

-
AID C

-

C

C

C

-

-

C

C

-
TVR O

-

O

O

O

-

-

O

O

-
IAD O

-

O

O

O

-

-

O

O

-
AC O

-

O

O

O

-

-

O

O

-
TSI O

-

O

O

O

-

-

O

O

-
ARC O

-

O

O

O

-

-

O

O

-
cvm

C

 -

C

C

C

-

-

C

C

-
signatureRequired

C

C

C

C

-

-

-

C

-

-
signatureData C

C

C

C

-

-

-

C

-

-
uniqueTransactionID C

C

C

C

C

C

C

C

-

-
PARData C

C

C

C

C

C

C

C

C

-
cardTypeProcessed P P P P P P   P    

footerLine1Merchant

P

P

P

P

-

P

P

P

P

-

footerLine2Merchant

P

P

P

P

-

P

P

P

P

-

footerLine3Merchant

P

P

P

P

-

P

P

P

P

-

footerLine1Cardholder

P

P

P

P

-

P

P

P

P

-

footerLine2Mercholder

P

P

P

P

-

P

P

P

P

-

footerLine3Cardholder

P

P

P

P

-

P

P

P

P

-
demoMode

P

P

P

P

P

P

P

P

P

P

Result codes

The following table lists and defines the result codes.

Result codes
Result code Description

0

OK: The operation completed successfully. The result field does not indicate whether the transaction was approved; it is an indicator of whether the transaction operation was able to successfully gather payment information and communicate with our payment host.

1

Application Error: These errors represent failures of processes internal to the application, such as being unable to create a new thread, file access errors, or loss of communication.

2

Card Error: This is usually due to the removal or failure of a contact card.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

4

Invalid Reference or Key: For a void transaction request, this indicates that the reference number does not match one in the terminal’s batch. For a parameter operation, this indicates an invalid key name.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

6

PIN debit key error: The terminal does not have a PIN debit key injected.

7

PIN Encryption Error: PIN hardware failure or over 1 million transactions limit reached.

8

P2PE key error: The terminal does not have a point-to-point encryption key injected.

9

Card Removed: The card was removed during the transaction processing.

10

Timeout occurred on the user interface.

11

Canceled by user: The user pressed the cancel key on one of the screens that allow user cancellation.

12

Canceled: The operation was canceled by a cancel operation from the POS.
13 Cancel not available.
14 Nothing to cancel.

15

Parse Error trying to parse the incoming API request.

17

Declined by the card.

19

Declined by our payment host.

20

Pre-condition failed before reaching our payment host. Provide this error code and the ‘500’ Host Error Code to troubleshoot the issue.

21

Connection to our payment host failed.

22

Sending request to our payment host failed.

23

Payment host response could not be processed.

24

Invalid payment host response.

25

Invalid clerk identification.

26

Fraud control validation failed (account number does not match).

27

Printer not operational.

28

Card is not supported.

29

Debit refund error.

31

Store and Forward (SAF) Maximum amount per transaction exceeded.

32

SAF Maximum number of transactions reached.

33

SAF Maximum cumulative amount exceeded.

34

SAF Entry mode not supported.

35

SAF Mask conditions not fulfilled.

36

SAF Transaction type not allowed.

37

SAF CVM not allowed.

38

SAF International card not allowed.

39

SAF not supported.

40

SAF CIT not supported.

41

AVS Address no match.

42

AVS ZIP no match.

43

AVS Address and ZIP no match.

70

Printer cover is open.

71

Printer paper jam.

72

Printer not supported.

80

Terminal is not operational.

81

Terminal is not connected.

82

Transaction in progress.

83

Missing credentials.

84

Key injection failed.

85

Load EMV configuration failed.

86

Load security data error.

87

Low battery.

88

MAC verification failed.

89

Key sync failed.

90

Invalid configuration

91

Network connection failed.

92

Pending parameters.

93

EMV Kernel error.

94

Kernel initialization.

95

Mercchant Advice Code (MAC) failed.

97

No data found for the request.

98

Not implemented.

99

Unknown Error: This is a catch-all error that occurs only if an error condition has not been specifically accounted for in the application.
Is this page helpful?