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 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:

    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!