Cancel/Refund request
An overview of the Cancel/Refund request message for iOS.
Our ‘Viva.com Terminal’ application (tap-on-phone) supports Apple Tap to Pay in the UK, the Netherlands, France, Austria, Czech Republic, Ireland, Romania, and Sweden, Italy & Germany.
Overview
👉 The Cancel/Refund request is used to Cancel/Void a payment which occurred within the same calendar day or to Refund a successful payment - either partially or fully. See below for further details
Cancellations/Voids: You can cancel/void (reverse) a payment made on the same calendar day. This means you are able to ‘undo’ a payment you have made, ensuring no money is charged from the customer’s card. In such cases, the cancellation appears in the customer’s account instantly.
Refunds: This is available for transactions which are cleared and ready to be settled in your account. You are able to refund the entire payment amount or just a portion of it (i.e. a ‘partial refund’). The time it takes for the refund to appear in the customer’s account can vary depending on the customer’s bank or card issuer. Please note: even if you trigger a same-day partial refund, the refund will be processed after clearance of the original transaction.
The client app must implement a mechanism to send messages using URL schemes and to receive the result in a custom URI callback.
- Cancel/Refund request originating from the client app to initiate a request for a Cancel/Refund transaction.
- Cancel/Refund response originating from the Viva.com Terminal App to return the result of a Cancel/Refund transaction.
This request will only produce a success
response in Viva’s Production environment (Viva.com Terminal App). Testing this functionality in the Viva.com Terminal Demo App will result in an UNEXPECTED (-999)
error or display a blank transactions list
Cancel/Refund request
For a typical Cancel/Refund request, the client app must provide the following information:
Field | Description | Example | Required |
---|---|---|---|
scheme | The Viva's custom URL scheme, the host and the version. | 'vivapayclient://pay/v1' | |
merchantKey | The merchant's key. For successful validation, should not be empty. Deprecated: you may pass any value. |
'SG23323424EXS3' | |
appId | The client app id. | 'com.example.myapp' | |
action | Cancel transaction. | 'cancel' | |
amount | The amount to refund in cents, without any decimal digits. If no amount provided, a full refund will be performed. | '600' = 6 euro (optional) | |
referenceNumber | The STAN number of the transaction to be cancelled. | '833121' (optional) | |
orderCode | The order code of the transaction to be cancelled. When provided, it will act as a search parameter and if a transaction with the same order code is found, the cancel/refund will take place. If a reference number has also been provided, only the order code will be taken into consideration. | '109113919500020' (optional) | |
shortOrderCode | Same as order code but in shorter length, although when provided, it will be reconstructed into a full length order code based on the terminal used. If the original sale has been made in a different terminal, the transaction won’t be retrieved and therefore cancelled. If both orderCode and shortOrderCode are provided, only the shortOrderCode will be taken into consideration. | '1091139195’ (optional) | |
txnDateFrom | Specifies the minimum date on which the transaction search will take place. if txnDateFrom is provided and txnDateTo is not, the current date will be assigned as the value of txnDateTo. The date should be in ISO 8601 format. | '2021-03-29T00:00:00.000+0300' (required if txnDateTo has been set, otherwise optional) | |
txnDateTo | Specifies the maximum date on which the transaction search will take place. if txnDateFrom has not been provided but a txnDateTo has, an error is returned. The date should be in ISO 8601 format. | '2021-03-30T00:00:00.000+0300' (optional) | |
show_receipt | Option to show the receipt screen, before returning to the InterApp, after performing a refund on Viva.com Terminal App. | 'true' | |
show_transaction_result | Option to show the transaction result screen, before returning to the InterApp, after performing a refund on Viva.com Terminal App. If show_receipt is set to 'true’ this value will be neglected, therefore the transaction result screen will be shown. | 'false' | |
protocol | The protocol used (internal use only) | Always pass this value: int_default | |
callback | Your custom URI callback that will handle the result. | 'interapp-callback' | |
aadeProviderId [*] | 👉 Integration with Provider (ΥΠΑΗΕΣ) Set the Unique Number to identify your Provider. To learn more about all licensed AADE providers, please visit this page. 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) For integration through ΦΗΜΑΣ, please specify as `aadeProviderId' the value 800 |
Integration with Provider (ΥΠΑΗΕΣ) 999 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) 800 |
|
aadeProviderSignatureData [*] | 👉 Integration with Provider (ΥΠΑΗΕΣ) The unencrypted signature that includes the fields below with semicolon as a delimiter “;”: 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) Use ECR TOKEN as in A.1098/2023 Request A/S< session number>/F< amount>:978:2 /D< datetime>/R< ecr-id>/H< operator-number>/T0 /M/Q< mac>} Result R/S< session number>/R< ecr-id>/T< receipt-number> /Μ/C00/D< trans-data>{/P< prn-data>}} |
Integration with Provider (ΥΠΑΗΕΣ) AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1 |
|
aadeProviderSignature [*] | 👉 Integration with Provider (ΥΠΑΗΕΣ) The fields of providerSignatureFields encrypted using a public key and the Elliptic Curve Digital Signature Algorithm (ECDSA): 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) Use SessionKey as in A.1098/2023 |
Integration with Provider (ΥΠΑΗΕΣ) o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw==" |
[*] These parameters are only applicable in Greece.
The above information elements must create a URI call, i.e.
func createCancelRequest(refundAmount: Decimal?, reference: String?, orderCode: String?, shortOrderCode: String?, dateFrom: String?, dateTo: String?) -> String {
// construct cancel action url
var cancelActionURL = Constants.cancelUrlString // vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=cancel
if let amount = refundAmount {
cancelActionURL += "&amount=\(((amount * 100) as NSDecimalNumber).intValue)" // The amount in cents without any decimal digits.
}
if let unwrappedReference = reference, unwrappedReference != "" {
cancelActionURL += "&referenceNumber=\(unwrappedReference)" // transaction reference number
}
if let unwrappedOrderCode = orderCode, unwrappedOrderCode != "" {
cancelActionURL += "&orderCode=\(unwrappedOrderCode)" // transaction order code
}
if let unwrappedShortOrderCode = shortOrderCode, unwrappedShortOrderCode != "" {
cancelActionURL += "&shortOrderCode=\(unwrappedShortOrderCode)" // transaction short Order Code
}
if let dateFrom = dateFrom {
cancelActionURL += "&txnDateFrom=\(dateFrom)"
}
if let dateTo = dateTo {
cancelActionURL += "&txnDateTo=\(dateTo)"
}
let showReceipt = UserDefaults.standard.value(forKey: "show_receipt") as? Bool ?? true
cancelActionURL += "&show_receipt=\(showReceipt)"
let showResult = UserDefaults.standard.value(forKey: "show_transaction_result") as? Bool ?? true
cancelActionURL += "&show_transaction_result=\(showResult)"
return cancelActionURL
}
//USE LIKE THIS
let canceRequestStringURL: String = createCancelRequest(refundAmount: 5, reference: nil, orderCode: nil, shortOrderCode: "1091139195",, dateFrom: "2021-03-29T00:00:00.000+0300", dateTo: nil)
(UIApplication.shared.delegate as? AppDelegate)?.performInterAppRequest(request: canceRequestStringURL)
The above information elements must create a URI call. i.e.
Request example
Request sample:vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=cancel&amount=600&shortOrderCode=1091139195&txnDateFrom=2021-03-29T00:00:00.000+0300&show_receipt=false
Request sample for merchants registered in Greece(including AADE parameters):vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=cancel&amount=600&shortOrderCode=1091139195&txnDateFrom=2021-03-29T00:00:00.000+0300&show_receipt=false&aadeProviderId=999&aadeProviderSignatureData=AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1&aadeProviderSignature=o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw==
Cancel/Refund response
After executing a Cancel/Refund request, the Viva.com Terminal App responds with a response result to indicate if the transaction has been approved or not.
The result is received as a URI in the callback activity.
The table below summarises the contents of an approved response:
Field | Description | Example |
---|---|---|
callback | The URI callback that will handle the result. | 'interapp-callback://result' |
status | The status of the transaction. | 'success' |
message | A string containing information about the transaction status. | 'Transaction successful' |
action | Cancel transaction. | 'cancel' |
amount | The amount in cents without any decimal digits. | '1200' = 12 euro |
cardType | The card type. | 'Debit Mastercard' |
accountNumber | The card number. Note that only the 6 first and the 4 last digits are provided. All other digits are masked with stars. | '537489******1831' |
orderCode | The order code. | '1091159196000136' |
shortOrderCode | The order code in short format. | '1091159196' |
tid | A 12 character string indicating the terminal's TID number. | '16016684' |
transactionDate | The transaction date in ISO 8601 format. | '2021-03-30T00:00:00.000+0300' |
transactionId | A unique identifier for the transaction. | 'a78e045c-49c3-4743-9071-f1e0ed71810c' |
aadeTransactionId | An AADE-specific transaction ID. Format: Acquirer Unique code + RRN + Authorization code. Example: ‘116’ + ‘123456833121’ + ‘690882’ = '116123456833121690882' |
'116123456833121690882' |
Examples
A Cancel/Refund response result for an approved transaction looks as follows:
interapp-callback://result?status=success&message=Transaction%2520successful&action=cancel&accountNumber=537489******1831&amount=500&cardType=Debit%2520Mastercard&orderCode=1092156115000136&shortOrderCode=1092156115& referenceNumber=30378&rrn=109212030376&tid=16000136&tipAmount=0&transactionDate=2021-04-02T15%253A18%253A51.416+0300&transactionId=063c17d5-f5f5-4ee3-8524-6dbb0d09ebeb
A Cancel/Refund response result for an approved transaction using AADE parameters looks as follows looks as follows:
interapp-callback://result?status=success&message=Transaction%2520successful&action=cancel&accountNumber=537489******1831&amount=500&cardType=Debit%2520Mastercard&orderCode=1092156115000136&shortOrderCode=1092156115& referenceNumber=30378&rrn=109212030376&tid=16000136&tipAmount=0&transactionDate=2021-04-02T15%253A18%253A51.416+0300&transactionId=063c17d5-f5f5-4ee3-8524-6dbb0d09ebeb&aadeTransactionId=116407412859062859062
It is expected that certain transactions will fail for various reasons. A Cancel response result for a failed transaction looks as follows:
interapp-callback://result?status=failure&message=Transaction%2520declined&action=cancel&accountNumber=537489******1831&amount=159&cardType=Debit%2520Mastercard&orderCode=1092156114000136&shortOrderCode=1092156114&rrn= 109212030372&tid=16000136&tipAmount=0&transactionDate=2021-04-02T15%253A12%253A16.068+0300
The structure of the message is the same as in the case of an approved transaction.
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!