For a typical sale request the client must provide the following information:
Field
Type
Length (chars)
Description
Example
Card terminal support
msgLength
String
4
A 4-digit number padded with leading zeros indicating message length minus 4 (including any separators). The request will be rejected if the correct message length is not provided.
‘0063’
sessionId
String
6
A unique number to control integrity of session sequence.
‘002690’
msgType
String
3
‘200’
‘200’
msgCode
String
2
‘00’
‘00’
uniqueTxnId
String
32
A unique transaction ID transmitted to the host for storage with the transaction. Note that this value will be provided in the MerchantTrns field provided in the sales export response.
‘12345678901234567890123456789012’
amount
String
variable up to 13
Amount always including 2 decimal digits following the decimal point. A dot must always be used as a decimal point.
‘123.00’
msgOpt
String
4
‘0000’
‘0000’
Reserved
String
0
Empty
"
Reserved
String
0
Empty
"
Reserved
String
0
Empty
"
Reserved
String
0
Empty
"
ISV_amount
String
Variable up to 13
ISV fee amount always including 2 decimal digits following the decimal point. A dot must always be used as a decimal point.
'123.00'
ISV_clientId
String
200
The id of the ISV client.
Refer to note below.
'qwerty123456'
ISV_clientSecret
String
200
The secret of the ISV client.
Refer to note below.
'qwerty123456'
ISV_sourceCode
String
20
The reseller source code of the ISV. Important: Should not be empty. Use “Default“ if no custom value.
If the resulting string gets appropriately transmitted to the terminal, the terminal will respond with a txResponse message (200).
Notes
msgLength – indicates the length of the message starting from the first separator. Since msgLength has always a length of 4, the value stored in msgLength is the total message length minus 4. The request will be rejected if the correct message length is not provided.
uniqueTxnId – must be exactly 32 characters, so padding (even with space characters) is required.
|| – for each reserved parameter, the position should be empty.
txSaleResponse
After executing a Sale transaction the terminal responds with a txSaleResponse to indicate if the transaction has been approved or not.
A txSaleResponse for an approved transaction looks as follows:
The table below summarises the contents of the response.
Field
Length (chars)
Description
Example
Card terminal support
msgLength
4
A 4-digit number padded with leading zeros indicating the length of the message that follows (including separators). Note that this is the total number of bytes and not of characters (in some languages, some characters consist of 2 bytes).
'0129'
seqTxnId
6
A 6 digit number matching the value sent in seqTnxNum field of the preceding txReady message.
'000032'
msgTypeResp
3
'210'
'210'
msgCodeResp
2
'00'
'00'
respCodeResp
2
Approval status. '00' indicates approval. All other values indicate failure codes. See failure code table at the end.
'00'
respMessageResp
variable up to 60
A string containing information on how the transaction was made, the card holder verification method used, the RRN and the Auth.code provided by the host.
'CHIP/PIN~RRN:123456833121'
cardTypeResp
variable
A string indicating the card type.
'VISA'
accNumberResp
variable
A string indicating the card number. Note that only the 6 first and the 4 last digits are provided. All the rest digits are masked with stars.
'479275******9999'
refNumResp
6
A 6-digit number indicating the transaction's STAN number.
'833121'
authCodeResp
6
A 6-digit number indicating the transaction's Authorisation code provided by the host.
'690882'
batchNumResp
6
A 6-digit number indicating the batch number. Not to be taken into account.
'000001'
amountResp
variable
The transaction's amount.
'123.00'
msgOptResp
4
Ignore
'1010'
tipAmountResp
2
'00' (currently not used)
'00'
foreignAmountResp
2
'00' (currently not used)
'00'
foreignCurrencyCode
2
'00' (currently not used)
'00'
exchangeRageInclMarkupResp
2
'00' (currently not used)
'00'
dccMarkcupPercentage
2
'00' (currently not used)
'00'
dccExchangeDateOfRateResp
2
'00' (currently not used)
'00'
eftTidResp
12
A 12 character string indicating the terminal's TID number, padded with spaces if required.
'16016684'
orderCode
16
Optional. Can be provided instead of or together with a refNum number. If a txnDateFrom/txnDateTo is provided, then the returned transaction results are bound by these dates, otherwise the last three transactions are returned.
'1069120310000201'
shortOrderCode
10
Optional. Can be provided instead of or together with a refNum number. If a txnDateFrom/txnDateTo is provided, then the returned transaction results are bound by these dates, otherwise the last three transactions are returned.
'1069120310'
MerchantReceiptPAN
variable up to 19
This field contains the value of the PAN (and additional clipping) that should be printed in merchant receipt. If is empty, then apply the default clipping
'629914XXXXXXXXX6770'
CardholderReceiptPAN
variable up to 19
This field contains the value of the PAN (and additional clipping) that should be printed in customer receipt. If is empty, then apply the default clipping.
'629914XXXXXXXXX6770'
CardholderReceiptText
variable up to 200
If is not empty then this value should be printed at the end of the customer receipt.
'qwerty123456'
TransactionReceiptAcquirerZone
variable up to 200
If it is not empty then this value should be printed at the end of the customer receipt.
'qwerty123456'
CardholderName
variable up to 50
Name of the cardholder.
'CARDHOLDER NAME'
CardExpirationDate
4
Expiration date of the card (YYMM).
'2212'
CardholderName&ExpirationDateFlags
4
Each char may be 0 (false) or 1 (true) and indicates if the cardholder name and the expiration date should be printed on the merchant/cardholder receipts).
1st char: if 1 then the Cardholder Name should be printed in the merchant's receipt. If 0, then it should not.
2nd char: if 1 then the Cardholder Name should be printed in the cardholder's receipt. If 0, then it should not.
3rd char: if 1 then the Expiration Date should be printed in the merchant's receipt. If 0, then it should not.
4th char: if 1 then the Expiration Date should be printed in the cardholder's receipt. If 0, then it should not.
'1010'
transactionId
variable up to 50
The id of the transaction
b3e2744a-71ec-4d51-a856-c2f70249bdd4
transactionDate
variable up to 50
The date of the transaction
2021-12-15T16:34:49.4495733+02:00
transactionType
variable up to 2
The type of the transaction. You can see all the possible transaction types in the Transaction Type Table
1
It is expected that certain transactions will fail for various reasons. A txSaleResponse for a failed transaction looks as follows:
The structure of the message is the same as in the case of an approved transaction.
Differences are limited to two specific fields.
respCodeResp field where a response code is returned indicating the reason the transaction failed.
respMessageResp where a string is returned providing a textual description of the reason.
Obviously refNumResp and authCodeResp contain zeros since there is no STAN code available, nor an authorisation code.
Failure reasons and ISO codes
The table below summarises the failure reasons that can be provided by the terminal.
Code
Description
Event
51
Declined By Host
Declined by the issuer
UD
Unsupported Card
Card is not supported
UC
User Cancelled
User pressed cancel or the user failed to present card in due time
LC
Lost Carrier (Communication Error)
No network
TO
Time Out (Communication Error)
Time out with host
CE
Communication Error (Other)
No connectivity
ND
Communication Error (Other)
Request failed
NA
Host Not Available
Host is not unreachable
IM
Invalid MAC received from host
...
UN
Error – Wrong Transaction
…
EC
Expired Card
Expired Card
XC
Transaction approved. EMV fail. Autoreversal
Transaction approved but automatically canceled
RC
Error during card reading
An error occurred while reading the card.
NO
Error after void request
No transactions found.
Notes
The list of codes may differ slightly between different versions of the software. Therefore, it is strongly suggested to use the response code (as well as any informational text provided), merely for display or troubleshooting purposes, i.e. when reporting the issue to the customer service.
In cases where the transaction gets declined by the Host (51), the terminal provides extra text on screen as well as a special code indicating the exact reason the transaction was declined by the host. The full list is described in the table below:
IsoCode
Description
10001
ReferToCardIssuer
10003
InvalidMerchant
10004
PickupCard
10005
DoNotHonor
10006
GeneralError
10012
InvalidTransaction
10013
InvalidAmount
10014
InvalidAccountNumber
10030
FormatError
10041
LostCard
10043
StolenCard
10051
InsufficientFunds
10054
ExpiredCard
10055
IncorrectPin
10057
TransactionNotPermittedToCardHolder
10058
TransactionNotPermittedToAcquirerOrTerminal
10061
ActivityAmountLimitExceeded
10062
RestrictedCard
10063
SecurityViolation
10065
ActivityCountLimitExceeded
10068
LateResponse
10070
CallIssuer
10075
PinEntryTriesExceeded
10086
PinValidationNotPossible
10087
PurchaseAmountOnlyNoCashBackAllowed
10090
CutOffInProgress
10094
DuplicateTransmissionDetected
10096
SystemMalfunction
10199
Empty
10200
Unmapped
*
Anyother
Transaction Types Table
Transaction type
Id
PREPARE_SALE
0
SALE
1
CANCEL
2
PREAUTH
3
CAPTURE
4
CANCEL_PREAUTH
5
SALE_ENGINE
6
EXECUTE_SALE
7
SCA_SALE
8
SCA_PREAUTH
9
REFUND
11
Get Support
If you have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.