Capture Pre-auth request

An overview of the Capture 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 Capture Pre-auth request is used to capture 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.

Capture Pre-auth request

For a typical Capture 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 Capture Pre-auth transaction. 'capture_pre_auth'
amount The amount to be captured, in cents. '600' = 6 euro (optional)
referenceNumber The STAN number of the transaction to be captured. '833121' (optional)
orderCode The order code of the transaction to be captured. When provided, it will act as a search parameter and if a transaction with the same order code is found, the capture will take place. If a reference number has also been provided, only the order code will be taken into consideration. '109113919500020' (optional)
shortOrderCode Same as order code but in shorter length, although when provided, it will be reconstructed into a full length order code based on the terminal used. If the original sale has been made in a different terminal, the transaction wonโ€™t be retrieved and therefore captured. If both orderCode and shortOrderCode are provided, only the shortOrderCode will be taken into consideration. '1091139195โ€™ (optional)
txnDateFrom Specifies the minimum date on which the transaction search will take place. if txnDateFrom is provided and txnDateTo is not, the current date will be assigned as the value of txnDateTo.

The date should be in ISO 8601 format.
โ€˜2021-03-29T00:00:00.000+0300โ€™ (required if txnDateTo has been set, otherwise optional)
txnDateTo Specifies the maximum date on which the transaction search will take place. if txnDateFrom has not been provided but a txnDateTo has, an error is returned.

The date should be in ISO 8601 format.
โ€˜2021-03-30T00:00:00.000+0300โ€™ (optional)
show_receipt Option to show the receipt screen, before returning to the InterApp, after performing a refund on Viva.com | Terminal App. 'true'
show_transaction_result Option to show the transcation result screen, before returning to the InterApp, after performing a capture on Viva.com | Terminal App. If show_receipt is set to โ€˜trueโ€™ this value will be neglected, therefore the transcation result screen will be shown. 'true'
protocol The protocol used (internal use only) int_default
callback Your custom URI callback that will handle the result. 'interapp-callback'
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 createCapturePreauthRequest(captureAmount: Decimal?, reference: String?, orderCode: String?, shortOrderCode: String?, dateFrom: String?, dateTo: String?) -> String {
    
            // construct capture action url
            var capturePreauthActionURL = Constants.captureUrlString // vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=capture_pre_auth
    
            if let amount = refundAmount {
                capturePreauthActionURL += "&amount=\(((amount * 100) as NSDecimalNumber).intValue)" // The amount in cents without any decimal digits.
            }
    
            if let unwrappedReference = reference, unwrappedReference != "" {
                capturePreauthActionURL += "&referenceNumber=\(unwrappedReference)" // transaction reference number
            }
    
            if let unwrappedOrderCode = orderCode, unwrappedOrderCode != ""  {
                capturePreauthActionURL += "&orderCode=\(unwrappedOrderCode)" // transaction order code
            }
    
            if let unwrappedShortOrderCode = shortOrderCode, unwrappedShortOrderCode != ""  {
                capturePreauthActionURL += "&shortOrderCode=\(unwrappedShortOrderCode)" // transaction short Order Code
            }
    
            if let dateFrom = dateFrom {
                capturePreauthActionURL += "&txnDateFrom=\(dateFrom)"
            }
    
            if let dateTo = dateTo {
                capturePreauthActionURL += "&txnDateTo=\(dateTo)"
            }
    
            let showReceipt = UserDefaults.standard.value(forKey: "show_receipt") as? Bool ?? true
            capturePreauthActionURL += "&show_receipt=\(showReceipt)"
    
            let showResult = UserDefaults.standard.value(forKey: "show_transaction_result") as? Bool ?? true
            capturePreauthActionURL += "&show_transaction_result=\(showResult)"
    
            return capturePreauthActionURL
        }
        //USE LIKE THIS
            let capturePreauthActionURL: String = createCapturePreauthRequest(captureAmount: 5, reference: nil, orderCode: nil, shortOrderCode: "1091139195",, dateFrom: "2021-03-29T00:00:00.000+0300", dateTo: nil)
            (UIApplication.shared.delegate as? AppDelegate)?.performInterAppRequest(request: capturePreauthActionURL)
    

    Request example

    Request sample:vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=capture_pre_auth&amount=600&shortOrderCode=1091139195&txnDateFrom=2021-03-29T00:00:00.000+0300&show_receipt=false

    Request sample for merchants registered in Greece(including AADE parameters):vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=capture_pre_auth&amount=600&shortOrderCode=1091139195&txnDateFrom=2021-03-29T00:00:00.000+0300&show_receipt=false&aadeProviderId=999&aadeProviderSignatureData=AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1&aadeProviderSignature=o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw==

    Capture Pre-auth response

    After executing a Capture 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 Capture Pre-auth transaction. 'capture_pre_auth'
    clientTransactionId The client transaction ID. '12345678901234567890123456789012'
    amount The amount in cents without any decimal digits. '1200' = 12 euro
    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'
    orderCode The order code. '1091166300000136'
    shortOrderCode The order code in short format. '1091166300'
    tid A 12 character string indicating the terminal's TID number. '16016684'
    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 Capture Pre-auth response result for an approved transaction looks as follows:

    A Capture Pre-auth response result for an approved transaction using AADE parameters looks as follows:

    It is expected that certain transactions will fail for various reasons. A Capture Pre-auth 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.

    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!