☰

Navigation:

Cancel request

An overview of the Cancel request message for iOS.

Overview

👉 The Cancel request is used to Cancel/Reverse a payment which occurred within the same calendar day or to Refund/Void a successful payment - either partial or full.

The Cancel request is relevant for both Sale and Pre-auth transactions

The client app must implement a mechanism to send messages using URL schemes and to receive the result in a custom URI callback.

This request will only produce a success response in Viva Wallet’s Production environment (Viva Wallet POS App). Testing this functionality in the VW POS Demo environment will result in an UNEXPECTED (-999) error or display a blank transactions list

Cancel request 

For a typical Cancel request, the client app must provide the following information:

Field Description Example
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 VW POS. 'true'
show_transaction_result Option to show the transaction result screen, before returning to the InterApp, after performing a refund on VW POS. 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'

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

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

Cancel response

After executing a Cancel transaction, the Viva Wallet POS App responds with a Cancel 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'

Examples

A Cancel response result for an approved transaction looks as follows:

It is expected that certain transactions will fail for various reasons. A Cancel response result for a failed transaction looks as follows:

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 Wallet, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!