Navigation:

Pre-auth request

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

Overview
Pre-auth request
Pre-auth response
Get Support

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

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 originating from the client app to initiate a request for a new Pre-auth transaction.
Pre-auth response originating from the Viva POS App to return the result of a Pre-auth transaction.

Pre-auth request

For a typical Pre-auth request, the client app must provide the following information:

Field	Description	Example	Required
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
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'
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'
aadeProviderId ^[*]	Unique Number to identify specific Provider (ΥΠΑΗΕΣ): VivaDemo - ‘999’ SoftOne - ‘101’ EnterSoft - ‘102’ Impact - ‘103’ Epsilon Net - ‘104’ Novus Conceptus - ‘105’ Cloud Services IKE - ‘106’ Primer Software - ‘107’ ILYDA = ‘108’ Prosvasis = ‘109’ MAT = ‘110’ Simply = ‘111’ Kappa = ‘112’ SBZ = ‘113’ OneSys = ‘114’ ORIAN = ‘115’ TESAE = ‘116’ Karpodinis = ‘117’ Cloud T = ‘118’ Πάροχος Λύσεων Πληροφορικής Α.Ε. = ‘119’	'999'	Please note that this parameter apply only for Greek merchants.
aadeProviderSignatureData ^[*]	The unencrypted signature that includes the fields below with semicolon as a delimiter “;”: Receipt UID MARK (Unique ID provided by AADE - commonly null as this provider after the end of the transaction) Date and time of the Signature Amount to be paid Sum Amount without TAX VAT percentage Sum Amount with TAX TID	AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1	Please note that this parameter apply only for Greek merchants.
aadeProviderSignature ^[*]	The fields of providerSignatureFields encrypted using a public key and the Elliptic Curve Digital Signature Algorithm (ECDSA): Algorithm: ECDSA Curve: NISTP256 HASH: SHA256 The signature is sent to POS in base64 format	o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw=="	Please note that this parameter apply only for Greek merchants.
callback	Your custom URI callback that will handle the result.	'interapp-callback'

[*] These parameters are only applicable in Greece.

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

Request sample:vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=pre_auth&amount=1200&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=pre_auth&amount=1200&show_receipt=false&show_rating=true&aadeProviderId=999&aadeProviderSignatureData=AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1&aadeProviderSignature=o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw==

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'
aadeTransactionId	An AADE-specific transaction ID. Format: Acquirer Unique code + RRN + Authorization code. Example: ‘116’ + ‘123456833121’ + ‘690882’ = '116123456833121690882'	'116123456833121690882'

Examples

A Pre-auth response result for an approved transaction looks as follows:

interapp-callback://result?status=success&message=Transaction%2520successful&action=pre_auth&accountNumber=537489******1831&amount=1400&authorisationCode=006373&cardType=Debit%2520Mastercard&orderCode=1091166300000136&shortOrderCode=1091166300&referenceNumber=27388&rrn=109113027388&tid=16000136&transactionDate=2021-04-01T16%253A47%253A59.251+0300&transactionId=728d7fe1-4426-4d29-8fee-510ae6c932e5&verificationMethod=Contactless

A Pre-auth response for a successful transaction using AADE parameters 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!