Sale Request

An overview of the Sale Request message.

• Overview
• txSaleRequest
• txSaleResponse
• Get Support

Overview

Please see below for information on configuring the Sale Request, as well as the expected Sale Response.

• txSaleRequest
• txSaleResponse

txSaleRequest

For a typical sale request the client must provide the following information:

Field	Type	Length (chars)	Description	Example	Required	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'	Required for ISV
ISV_clientId	String	200	The id of the ISV client. Refer to note below.	'qwerty123456'	Required for ISV
ISV_clientSecret	String	200	The secret of the ISV client. Refer to note below.	'qwerty123456'	Required for ISV
ISV_sourceCode	String	20	The reseller source code of the ISV. Important: Should not be empty. Use “Default“ if no custom value. Refer to note below.	'qwerty123456'	Required for ISV
protocol	String	20	The protocol used (for internal use only)	'ecr_default'

The above information elements must be joined into one single string using ‘|’ as a separator. i.e.

0107|002690|200|00|12345678901234567890123456789012|123.50|0000|||||0.10|qwerty123456|qwerty123456|qwerty123456

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.

• protocol - this is for internal use only and can therefore be excluded from your requests

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:

Linux Card Terminals:

0213|000032|210|00|00|CHIP/PIN~RRN:123456833121|VISA|479275******9999|833121|690882|000001|123.00|1010|00|00|00|00|00|00| 16016684||||629914XXXXXXXXX6770|629914XXXXXXXXX6770|qwerty123456|qwerty123456|my name|2212|1010

Android Card Terminals:

0247|000024|210|00|00|Contactless/None~RRN:204814800749|MASTERCARD|537535******9228|800749|008120|000001|1.11|00|00|00|00|00|00|00| 16000281|2048160108000202|2048160108||||||||0950f16c-1f52-4060-ac22-cb6b59c8990c|2022-02-17T16:15:15.1824947+02:00|1

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). Before considering the msgLength value, please make sure that you've decoded the terminal response with UTF-8.	'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. Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'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. Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'629914XXXXXXXXX6770'
CardholderReceiptText	variable up to 200	If is not empty then this value should be printed at the end of the customer receipt. Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'qwerty123456'
TransactionReceiptAcquirerZone	variable up to 200	If it is not empty then this value should be printed at the end of the customer receipt. Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'qwerty123456'
CardholderName	variable up to 50	Name of the cardholder. Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'CARDHOLDER NAME'
CardExpirationDate	4	Expiration date of the card (YYMM). Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'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. Note: this parameter is returned only for c-tap cards (meal vouchers, etc.)	'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:

0218|000026|210|00|51|Declined|MASTERCARD|537535******9228|800750||000001|1.01|1010|00|00|00|00|00|00| 16000281|2048160109000202|2048160109||||||||692676f4-7f9e-478c-b3fe-901dfa7b9bc8|2022-02-17T16:16:44.2677975+02:00|1

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.

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:

Transaction Types Table

Get Support

If you would like to integrate with Viva Wallet, or if you have any queries about our products and solutions, please see our Get Support page to see how we can help!