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, Austria, Czech Republic, Ireland, Romania, and Sweden, Italy & Germany.

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 ^[*]	👉 Integration with Provider (ΥΠΑΗΕΣ) Set the Unique Number to identify your Provider VivaDemo - 999(provider id for testing purposes) 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 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) For integration through ΦΗΜΑΣ, please specify as `aadeProviderId' the value 800	Integration with Provider (ΥΠΑΗΕΣ) 999 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) 800	Please note that this parameter apply only for Greek merchants.
aadeProviderSignatureData ^[*]	👉 Integration with Provider (ΥΠΑΗΕΣ) 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 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) Use ECR TOKEN as in A.1098/2023 Request A/S< session number>/F< amount>:978:2 /D< datetime>/R< ecr-id>/H< operator-number>/T0 /M/Q< mac>} Result R/S< session number>/R< ecr-id>/T< receipt-number> /Μ/C00/D< trans-data>{/P< prn-data>}}	Integration with Provider (ΥΠΑΗΕΣ) AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1	Please note that this parameter apply only for Greek merchants.
aadeProviderSignature ^[*]	👉 Integration with Provider (ΥΠΑΗΕΣ) 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 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) Use SessionKey as in A.1098/2023	Integration with Provider (ΥΠΑΗΕΣ) 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!