Cancel/Refund request

An overview of the Cancel/Refund request message for iOS.

• Overview
• Cancel/Refund request
• Cancel/Refund response
• Get Support

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.

Cancel/Refund request 

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

[*] 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:

Examples

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

A Cancel/Refund response result for an approved transaction using AADE parameters looks as follows 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, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!