Pre-auth request

An overview of the Pre-auth request message for iOS.

Our ‘viva.com | Terminal’ application (tap-on-phone) supports Apple Tap to Pay in the UK, the Netherlands & France

Overview

👉 The Pre-auth request is used to initiate a pre-authorisation transaction.

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

Pre-auth request 

For a typical Pre-auth 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 Pre-auth transaction. 'pre_auth'
amount Amount in cents without any decimal digits. '1200' = 12 euro
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'
callback Your custom URI callback that will handle the result. 'interapp-callback'
show_receipt A flag indicating if the receipt and transaction result will be shown. If true both transaction result and receipt will be shown. If false receipt will not be shown and result will be shown if show_transaction_result is true. 'true'
show_transaction_result A flag indicating whether transaction result will be shown. 'true'
show_rating A flag indicating if the rating flow will be shown. 'true'

The above information elements must create a URI call, such as:

func createPreauthRequest(
    amount: Decimal
) -> String {
    // construct sale action url
    var preauthActionURL = Constants.preauthUrlString  // vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=pre-auth

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

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

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

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

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

    return preauthActionURL
}

Request example

vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=pre_auth&amount=1200&show_receipt=false&show_rating=true

Pre-auth response

After executing a Pre-auth transaction, the ‘viva.com | Terminal’ application responds with a 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 Pre-auth transaction. 'pre_auth'
clientTransactionId The client transaction ID. '12345678901234567890123456789012'
amount The amount in cents without any decimal digits. '1200' = 12 euro
verificationMethod The verification method used. 'Contactless'
rrn The Retrieval Reference Number of the transaction. '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'
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 Pre-auth response result for an approved transaction looks as follows:

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!