Sale request

An overview of the Sale request message.

Overview

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 

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

Field Description Example
scheme The Viva 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 Sale transaction. 'sale'
clientTransactionId A unique transaction ID transmitted to the host for storage with the transaction. Note that this value will be provided in the Merchant Reference field provided in the sales export response. '12345678901234567890123456789012'
amount Amount in cents without any decimal digits. This value must not be empty and must be an integer larger than zero. '1200' = 12 euro
tipAmount The tip that will be added on top of the amount. This must be less than or equal to the amount. '200' = 2 euro
withInstallments Enable card installments. 'true'
preferredInstallments Number of preferred card installments. If the number is between the allowed range and the card supports installments then the flow complete without any prompt for installments. If the number is 0 or > max allowed number of installments then the user will be prompt to enter the number in the app. If the card does not support installments then the app will request from the user how to proceed with the flow. '10'
show_receipt Option to show the receipt screen, before returning to the InterApp, after performing a sale on VW POS. 'false'
show_rating Option to show the rating/feedback screen, before returning to the InterApp, after performing a sale on Viva Wallet POS. 'false'
show_transaction_result Option to show the transaction result screen, before returning to the InterApp, after performing a sale on VW POS. If show_receipt is set to 'true’ this value will be neglected, therefore the transaction result screen will be shown. 'false'
ISV_amount The fee charged by the ISV on the sale. Amount in cents. Only for ISV Partners '10' =0.1€
ISV_clientId The id of the ISV client. It is mandatory that if client id is provided the ISV_amount and ISV_clientSecret parameters should be provided too. Only for ISV Partners
Refer to note below.
'auyf99x03sachvn3f5ogldykz8214c2o4vl8cvvs97p19.apps.vivapayments.com'
ISV_clientSecret The secret of the ISV client. Only for ISV Partners
Refer to note below.
'qwerty123456'
ISV_sourceCode The reseller source code of the ISV.Only for ISV Partners
Refer to note below.
'qwerty123456'
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'

ISV parameter info:

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

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

Sale response

After executing a Sale transaction the card terminal app 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.

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 Sale transaction. 'sale'
clientTransactionId The client transaction ID. '12345678901234567890123456789012'
amount The amount in cents without any decimal digits. '1200' = 12 euro
tipAmount How much of the amount in cents is considered as tip without any decimal digits. '200' = 2 euro
verificationMethod The verification method used. 'Contactless'
rrn The Retrieval Reference Number of the transaction RRN. '123456833121'
cardType The card type. 'Debit Mastercard'
accountNumber The card number masked. Note that only the 6 first and the 4 last digits are provided. All other digits are masked with stars. '537489******1831'
referenceNumber A 6-digit number indicating the transaction's STAN number. '833121'
authorisationCode A 6-digit number indicating the transaction's Authorisation code provided by the host. '690882'
tid A 12 character string indicating the terminal's TID number. '16016684'
orderCode The order code. '1091166300000136'
shortOrderCode The order code in short format. '1091166300'
installments Number of card installments. '10'
transactionDate The transaction date in ISO 8601 format. '2019-09-13T12:14:19.8703452+03:00'
transactionId A unique identifier for the transaction. 'a78e045c-49c3-4743-9071-f1e0ed71810c'

Examples

A Sale response result for an approved transaction 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 Wallet, or if you have any queries about our products and solutions, please see our Get Support page to see how we can help!