Sale request

An overview of the Sale request message for iOS.

• Overview
• Sale request
• Sale response
• Get Support

Overview

👉 The Sale request is used to prompt payment from the customer for a specific amount, including the desired tip amount. Once the customer has attempted or completed payment, a related transaction (either successful or unsuccessful) will be created.

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

• Sale request originating from the client app to initiate a request for a new Sale transaction.
• Sale response originating from the Viva.com Terminal App to return the result of a Sale transaction.

Sale request 

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

[*] These parameters are only applicable in Greece.

Using the information above, our custom URI should be created like this.

typealias ISVDetails = (clientId: String, amount: Decimal, clientSecret: String, sourceCode: String?)

func createSaleRequest(amount: Decimal, tipAmount: Decimal?, clientTransactionId: String?, isvDetails: ISVDetails?, numberOfInstallments: Int?) -> String {
// construct sale action url
var saleActionURL = Constants.saleUrlString // vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=sale

saleActionURL += "&amount=\(((amount * 100) as NSDecimalNumber).intValue)" // The amount in cents without any decimal digits.

if let tip = tipAmount {
    saleActionURL += "&tipAmount=\(((tip * 100) as NSDecimalNumber).intValue)" // The tip amount in cents without any decimal digits.
}

// append clientTransactionId parameter (if any)
if let transactionId = clientTransactionId, transactionId != "" {
    saleActionURL += "&clientTransactionId=\(transactionId)"
}

// append number of installments parameter (if any) - available for Greek merchants only
if let preferredInstallments = numberOfInstallments, preferredInstallments > 1 {
    saleActionURL += "&withInstallments=true" // enable installments parameter - available for Greek merchants only
    saleActionURL += "&preferredInstallments=\(preferredInstallments)" // available for Greek merchants only
}
else {
    saleActionURL += "&withInstallments=false" // no installments parameter (should be used)
}

if let isvDetails = isvDetails {
    saleActionURL += "&ISV_clientId=\(isvDetails.clientId)"
    saleActionURL += "&ISV_amount=\(((isvDetails.amount * 100) as NSDecimalNumber).intValue)" // The ISV amount in cents without any decimal digits.
    saleActionURL += "&ISV_clientSecret=\(isvDetails.clientSecret)"
    if let sourceCode = isvDetails.sourceCode {
        saleActionURL += "&ISV_sourceCode=\(sourceCode)"
    }
}

let showReceipt = UserDefaults.standard.value(forKey: "show_receipt") as? Bool ?? true
saleActionURL += "&show_receipt=\(showReceipt)"

let showRating = UserDefaults.standard.value(forKey: "show_rating") as? Bool ?? true
saleActionURL += "&show_rating=\(showRating)"

let showResult = UserDefaults.standard.value(forKey: "show_transaction_result") as? Bool ?? true
saleActionURL += "&show_transaction_result=\(showResult)"

return saleActionURL
}

//USE LIKE THIS
let saleActionURL = createSaleRequest(amount: 12.00, tipAmount: 2.00, clientTransactionId: nil, isvDetails: nil, numberOfInstallments: nil)
(UIApplication.shared.delegate as? AppDelegate)?.performInterAppRequest(request: saleActionURL)

Request example

Request sample:vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=sale&amount=1200&tipAmount=200&withInstallments=false&show_receipt=false&show_rating=true

Request sample for merchants registered in Greece(including AADE parameters):vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=sale&amount=1200&tipAmount=200&withInstallments=false&show_receipt=false&show_rating=true&aadeProviderId=999&aadeProviderSignatureData=AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1&aadeProviderSignature=o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw==

Sale response

After executing a Sale transaction the ‘Viva.com Terminal’ application responds with a Sale 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 sale response result for an approved transaction looks as follows:

A sale response for a successful transaction using AADE parameters looks as follows:

It is expected that certain transactions will fail for various reasons. A Sale 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. Fields such as referenceNumber and authorisationCode may not have values since there is no STAN code available, nor an authorisation code.

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!