Cancel Request

An overview of the Cancel Request message.

• Overview
• txCancelRequest
• txCancelResponse
• Get Support

Overview

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

• txCancelRequest - originating from the application to initiate a request for a cancel transaction
• txCancelResponse - originating from the card terminal to return the response of a cancel request

txCancelRequest

txCancelRequest executes a typical transaction cancellation or refund. The operation depends on whether the Sale transaction to be cancelled/refunded was made on the same day (cancellation) or any day before that (refund). Please note the parameters below and how they apply to different cancellation/refund scenarios further down.

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.	0061	✅
sessionId	String	6	A unique number to control integrity of session sequence.	002690
msgType	String	3	200	200	✅
msgCode	String	2	04	04	✅
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. If the amount is less than the transaction's full amount and the transaction date is today, then an error is returned as only a void is possible and therefore a full amount must be given. In all other cases, the amount can be partial to enable partial refunds. If no amount is supplied, it is assumed that the transaction amount is to be returned.	123.00
refNum	String	6	The STAN number of the transaction to be cancelled. Note that if the STAN value is unknown the application may provide the value ‘000000’. In that case, after card presentment, the terminal will provide a list of the last 3 transactions made with the presented card, allowing the user to select the transaction to be canceled.	826987
sourceTerminalId	String	8	Optional The terminal ID of the source with which the transaction is associated.	12345678
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Receipt_UID	String	200	The unique identifier (UID) is a numeric or alphanumeric string that is associated with a single entity within the cashier system.	193302323D532594AD14B669BCCC60C74FCA8BB6	✅ Required for AADE Integration 👉 Applicable only in Greece
MARK	String	0	Unique ID provided by AADE. Commonly is null as this provided at the end of each successful transaction.	null	✅ Required for AADE Integration 👉 Applicable only in Greece
SignatureDateTime	String	200	The Date and time of the Provider's Digital Signature.	20240513134504	✅ Required for AADE Integration 👉 Applicable only in Greece
PaidAmount	String	200	The amount to be paid. This value should be the same as the amount parameter and should be specified without any special character, such as comma (,) or point (.)	12400	✅ Required for AADE Integration 👉 Applicable only in Greece
AmountWithoutTax	String	200	The amount without TAX to be paid. This value should be specified without any special character, such as comma (,) or point (.)	10000	✅ Required for AADE Integration 👉 Applicable only in Greece
VAT	String	200	The value of VAT percentage that applied to the total amount. This value should be specified without any special character, such as comma (,) or point (.) If different value of TAX applied to the items of the transaction, then should be specified in this parameter, the highest value of TAX.	24	✅ Required for AADE Integration 👉 Applicable only in Greece
AmountWithTax	String	200	The amount with TAX to be paid. This value should be specified without any special character, such as comma (,) or point (.)	12400	✅ Required for AADE Integration 👉 Applicable only in Greece
POSTerminalID	String	200	The POS ID through which the transaction will be handled. The value of POS ID is NOT be the Device Serial Number, and can be found through the Viva Softpos Application Settings.	16000198	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
ProviderID	String	200	The ID of the ΥΠΑΗΕΣ Provider that generates the Digital Signature for this transaction. To learn more about all licensed AADE providers, please visit this page. VivaDemo = 999 SoftOne = 101 EnterSoft = 102 Impact = 103 Epsilon Net = 104 Novus Conceptus = 105 Cloud Services IKE = 106 Primer Software = 107 ILYDA = 108 Prosvasis = 109 MAT = 110 Simply = 111 Kappa = 112 SBZ = 113 OneSys = 114 ORIAN = 115 TESAE = 116 Karpodinis = 117 Cloud T = 118 Πάροχος Λύσεων Πληροφορικής Α.Ε. = 119 BRATNET E.E = 120 INVOICESOFT = 121 BUSINESS CLOUD EE = 122 EDICOM = 123 MEGASOFT = 124	999	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
aadeProviderSignature	String	200	The fields of providerSignatureFields encrypted using a public key and the Elliptic Curve Digital Signature Algorithm (ECDSA): Algorithm: ECDSA Curve: NISTP256 HASH: SHA256 The signature should be sent to POS in base64 format.	MEUCIQDHGhz2KQ+gddCsryDxcF69wW3o7C5WpuULHJ8DPeuLBgIgVxgCbh+OFtuZCwAOp7O8kJ+ShPlcpw84RG2jLBAWp2c=	✅ Required for AADE Integration 👉 Applicable only in Greece
Reserved	String	0	Empty	null	✅ Required for AADE Integration 👉 Applicable only in Greece
txnDateFrom (NOT YET SUPPORTED)	String	24	Optional If supplied and no orderCode or refNum is given, then the returned transactions are within the txnDateFrom and txnDateTo bounds. If it is not supplied, then the last three transactions are returned as is the case with the current protocol.	2021-03-18T14:42:53.341Z
txnDateTo (NOT YET SUPPORTED)	String	24	Optional If supplied and no orderCode or refNum is given, then the returned transactions are within the txnDateFrom and txnDateTo bounds. If it is not supplied, then the last three transactions are returned as is the case with the current protocol. If a txnDateFrom is supplied and no txnDateTo is given, then the application assumes that txnDateTo is today's date. If a txnDateTo is supplied without a txnDateFrom, then an error must be returned.	2021-03-20T14:42:53.341Z
orderCode	String	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	String	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
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.

A cancel/void/refund request without using AADE parameters looks as follows:

A cancel/void/refund request using AADE parameters looks as follows:

If the resulting string gets appropriately transmitted to the terminal, the terminal will respond with a txResponse message.

If only the amount is communicated during the refund and no order code is given:

• Show a list of transactions. Above the list show: Refund X EUR for which transaction?
• Each list item should contain the transaction ID, transaction date, original sale amount.
• Once a list item is chosen by the operator, show the refund confirmation (Are you sure you want to refund X EUR from the transaction with transaction ID A, transaction date B, original sale amount C?)
• Once confirmed, proceed with refund. No amount revalidation/entry necessary by terminal operator!

If the order code is communicated during the cancel/void/refund and no amount is given, then it is assumed that the entire amount is to be refunded:

• Proceed with refund. No amount revalidation/entry necessary by terminal operator!

If the order code is communicated during the refund and an amount is given:

• Proceed with refund. No revalidation/entry necessary by terminal operator!

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 any optional parameters you do not want to use, the position should be empty.

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

txCancelResponse

After executing a cancel/void/refund transaction the terminal responds with a txCancelResponse to indicate if the transaction has been approved or not.

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 character 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.	0073
seqTxnId	6	A 6-digit number matching the value sent in seqTnxNum field of the preceding txReady message.	000050
msgTypeResp	3	210	210
msgCodeResp	2	04	04
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	Empty	null
cardTypeResp	variable	A string indicating the card type.	MASTERCARD
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.	537535******1339
refNumResp	6	A number with up to 6 digits indicating the transaction's STAN (System Trace Audit Number).	856749
authCodeResp	6	000000	000000
terminalidResp	8	A 8-character string indicating the terminal's TID number, padded with spaces if required.	16016684
eftTidResp	12	A 12-character string indicating the terminal's TID number, padded with spaces if required.	16016684
aadeTransactionId	variable up to 50	An AADE-specific transaction ID. Format Acquirer Unique code + RRN + Authorization code. Example 116 + 123456833121 + 690882 = 116123456833121690882	116413607959451959451
paidAmount	variable	The transaction's amount.	12300
transactionDateTime	variable up to 50	The date of the transaction.	2021-12-15T16:34:49.4495733+02:00
orderCode	16	A 16-digit numeric string representing the order code.	1062160242000098
shortOrderCode	10	A 10-digit numeric string representing the short order code.	1062160242
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.	Text for customer receipt
TransactionReceiptAcquirerZone	Variable up to 200	If it is not empty then this value should be printed at the end of the customer receipt.	Text for acquirer zone
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.	1062160242
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

Linux Card Terminals:

A txCancelResponse for an approved cancel/void/refund transaction (without using AADE parameters) looks as follows:

A txCancelResponse for an approved cancel/void/refund transaction (with AADE parameters) looks as follows:

Android Card Terminals:

A txCancelResponse for an approved cancel/void/refund transaction (with AADE parameters) looks as follows:

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. The table of values provided in txSaleResponse provides typical response codes that may be returned.
• respMessageResp where a string is returned providing a textual description of the reason.

Obviously authCodeResp contain zeros since there is no STAN code available, nor an authorisation code.

Failure reasons

See Failure reasons and ISO codes under txSaleResponse. These are the same for all transaction types (Sales, Cancellations and Pre-auths).

Get Support

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