Capture Pre-auth request

An overview of the Capture Pre-auth request message for Android.

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 Android intents and URI calls 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 Card terminal support Character limit Type
scheme The Viva custom URL scheme, the host and the version. 'vivapayclient://pay/v1' Android Card Terminals'Viva.com Terminal' application for Android
merchantKey The merchant's key. For successful validation, should not be empty.
Deprecated: you may pass any value.
'SG23323424EXS3' Android Card Terminals'Viva.com Terminal' application for Android
appId The client app ID. For successful validation, should not be empty. 'com.example.myapp' Android Card Terminals'Viva.com Terminal' application for Android
action Pre-auth transaction. For successful validation, should not be empty. 'capture_pre_auth' Android Card Terminals'Viva.com Terminal' application for Android
callback The URI callback that will handle the result. For successful validation, should not be empty. 'mycallbackscheme://result' Android Card Terminals'Viva.com Terminal' application for Android
amount The amount to be captured, in cents. '1200' = 12 euro Android Card Terminals'Viva.com Terminal' application for Android integer (int32)
sourceCode The store/source code that will be linked to the transaction.
  • If a source code parameter is not specified, the source code assigned to the terminal will automatically be associated with the transaction.
  • When the sourceCode is specified, the transaction will be linked to the sourceCode accordingly.
[A payment source (physical store) that is associated with the transaction]

How to create a payment source for CP payments
'Viva.com Terminal' application for Android 20 integer (int32)
referenceNumber The STAN number of the transaction to be cancelled. If empty, after card presentment, the app will provide a list of the last 3 transactions made with the presented card, allowing the user to select the transaction to be canceled. If action is cancel and if not empty should be integer bigger than zero.' '833121' (optional) Please note the following options (if using the 'Viva.com Terminal' application for Android):

- Pass one or more of the identification parameters (referenceNumber, orderCode, shortOrderCode), but no date parameters: this will allow the capture to be completed directly

- Pass both of the date parameters (txnDateFrom & txnDateTo), but no identification parameters: this will allow the POS user to locate the desired transaction with filters (with the date range pre-filled but amendable)

- Pass neither the identification parameters or the date parameters: this will allow the POS user to locate the desired transaction with filters (with the date range not pre-filled)
Android Card Terminals'Viva.com Terminal' application for Android integer (int32)
orderCode If not empty should be integer bigger than zero and length 16. '1020304050607080' Android Card Terminals'Viva.com Terminal' application for Android integer (int32)
shortOrderCode If not empty should be integer bigger than zero and length 10. '1234567890' Android Card Terminals'Viva.com Terminal' application for Android integer (int32)
txnDateFrom If action is cancel and if not empty should be in "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format. '2021-03-18T14:42:53.341Z' 'Viva.com Terminal' application for Android date-time
txnDateTo If action is cancel and if not empty should be in "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format, txnDateFrom should be provided and txnDateTo should be after txnDateFrom. '2021-03-19T14:42:53.341Z' 'Viva.com Terminal' application for Android date-time
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' 'Viva.com Terminal' application for Android boolean
show_transaction_result A flag indicating whether transaction result will be shown. 'true' 'Viva.com Terminal' application for Android boolean
show_rating A flag indicating if the rating flow will be shown. 'true' 'Viva.com Terminal' application for Android boolean
aadeProviderId [*] 👉 Integration with Provider (ΥΠΑΗΕΣ)

Set the Unique Number to identify your Provider. To learn more about all licensed AADE providers, please visit this page.

  • 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
  • BRATNET E.E = 120
  • INVOICESOFT = 121
  • BUSINESS CLOUD EE = 122
  • EDICOM = 123
  • MEGASOFT = 124


  • 👉 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.
    Android Card Terminals'Viva.com Terminal' application for Android 3 Numeric
    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.
    Android Card Terminals'Viva.com Terminal' application for Android 200 Alphanumeric
    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.
    Android Card Terminals'Viva.com Terminal' application for Android Alphanumeric

    [*] These parameters are only applicable in Greece

    The above parameters must be used to create a URI call. Please see the below example:

    Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse( "vivapayclient://pay/v1"
    				+ "?merchantKey="MY_MERCHANT_KEY"
    				+ "&appId=com.example.myapp"
    				+ "&action=capture_pre_auth"
    				+ "&referenceNumber=123456"
    				+ "&orderCode=1020304050607080"
    				+ "&shortOrderCode=1234567890"
    				+ "&txnDateFrom=2021-03-18T14:42:53.341Z"
    				+ "&txnDateTo=2021-03-19T14:42:53.341Z"
    				+ "&amount=100"
            + "&sourceCode=6532"
    				+ "&show_receipt="+true
    				+ "&show_transaction_result="+true
    				+ "&show_rating="+true
                    + "&aadeProviderId=999"
                    + "&aadeProviderSignatureData=AD33729F4ED749928AAFA00B90EE4EA91551BAC1;;20231204080313;1051;10000;2400;12400;POS_1"
                    + "&aadeProviderSignature=o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw=="
                    + "&callback=mycallbackscheme://result"));
    
    payIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
    payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
    //        Those two flags should be added for paydroid implementations
    //        payIntent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);
    //        payIntent.addFlags(Intent.FLAG_ACTIVITY_NO_HISTORY);
                    startActivity(payIntent);

    Capture Pre-auth response

    After executing a Capture Pre-auth transaction the ‘Viva.com Terminal’ application responds with a Capture Pre-auth response result to indicate if the transaction has been approved or not.

    The result is received as a URI in the callback activity intent:

    Uri result = getIntent().getData()`

    The table below summarises the contents of an approved response.

    Field Description Example Card terminal support
    callback The URI callback that will handle the result. 'mycallbackscheme://result' Android Card Terminals'Viva.com Terminal' application for Android
    status The status of the transaction. 'success' Android Card Terminals'Viva.com Terminal' application for Android
    message A string containing information about the transaction status. 'Transaction successful' Android Card Terminals'Viva.com Terminal' application for Android
    action Capture Pre-auth transaction. 'capture_pre_auth' Android Card Terminals'Viva.com Terminal' application for Android
    amount The amount in cents without any decimal digits. If action is cancel and amount is not empty must be integer and bigger than zero.
    (Used in successful and declined receipts)
    '1200' = 12 euro Android Card Terminals'Viva.com Terminal' application for Android
    sourceCode The source code associated with the transaction. '2412' 'Viva.com Terminal' application for Android
    cardType The card type. 'VISA' Android Card Terminals'Viva.com Terminal' application for Android
    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.
    (Used in successful and declined receipts)
    '479275\*\*\*\*\*\*9999' Android Card Terminals'Viva.com Terminal' application for Android
    tid A 12 character string indicating the terminal's TID number. ' 16016684' Android Card Terminals'Viva.com Terminal' application for Android
    referenceNumber A number with up to 6 digits indicating the transaction's STAN (System Trace Audit Number). '833121' Android Card Terminals'Viva.com Terminal' application for Android
    authorisationCode A 6-digit number indicating the transaction's Authorisation code provided by the host. '690882' Android Card Terminals'Viva.com Terminal' application for Android
    orderCode The order code. ' 9256110059000200' Android Card Terminals'Viva.com Terminal' application for Android
    shortOrderCode 10-digit integer. '1234567890' Android Card Terminals'Viva.com Terminal' application for Android
    transactionDate The transaction date in ISO 8601 format.
    (Used in successful and declined receipts)
    '2019-09-13T12:14:19.8703452+03:00' Android Card Terminals'Viva.com Terminal' application for Android
    transactionId A unique identifier for the transaction. 'a78e045c-49c3-4743-9071-f1e0ed71810c' Android Card Terminals'Viva.com Terminal' application for Android
    aid A string indicating the AID of the card.
    (Used in successful receipts)
    'A000000003101001' Android Card Terminals
    vatNumber The VAT number of merchant.
    (if print VAT is enabled in the 'Viva.com Terminal' application settings)
    (Used in successful and declined receipts)
    '123412341' Android Card Terminals
    address The address of merchant
    (if print address is enabled in the 'Viva.com Terminal' application settings)
    (Used in successful receipts)
    ‘Main St 123, 12312 Anytown’ Android Card Terminals
    businessDescription Merchant’s Business/Trade/Store name (depending on what option is selected in the 'Viva.com Terminal' application settings),
    (Used in successful receipts)
    'Wonka Industries' Android Card Terminals
    printLogoOnMerchantReceipt A boolean indicating weather the VivaWallet logo should be printed on merchant receipt.
    (Used in successful receipts)
    'false' Android Card Terminals
    merchantReceiptPAN This field contains the value of the PAN (and additional clipping) that should be printed in merchant receipt. If is empty, then apply the default clipping.
    (Used in successful receipts)
    '629914XXXXXXXXX6770' Android Card Terminals
    cardholderReceiptPAN This field contains the value of the PAN (and additional clipping) that should be printed in customer receipt. If is empty, then apply the default clipping. '629914XXXXXXXXX6770' Android Card Terminals
    transactionReceiptAcquirerZone If it is not empty then this value should be printed at the end of the customer receipt.
    (Used in successful receipts)
    'qwerty123456' Android Card Terminals
    cardholderReceiptText If is not empty then this value should be printed at the end of the customer receipt.
    (Used in successful receipts)
    'qwerty123456' Android Card Terminals
    merchantReceiptText If is not empty then this value should be printed at the end of the customer receipt.
    (Used in successful receipts)
    'qwerty123456' Android Card Terminals
    cardholderName Name of the cardholder.
    (Used in successful receipts)
    'JOHN DOE' Android Card Terminals
    cardExpirationDate Expiration date of the card (YYMM).
    (Used in successful receipts)
    '2212' Android Card Terminals
    cardholderNameExpirationDateFlags Each char may be 0 (false) or 1 (true) and indicates if the cardholder name and the expiration date should be printed on the merchant/cardholder receipts)

    1st char: if 1 then the Cardholder Name should be printed in the merchant's receipt. If 0, then it should not.

    2nd char: if 1 then the Cardholder Name should be printed in the cardholder's receipt. If 0, then it should not.

    3rd char: if 1 then the Expiration Date should be printed in the merchant's receipt. If 0, then it should not.

    4rd char: if 1 then the Expiration Date should be printed in the cardholder's receipt. If 0, then it should not.
    (Used in successful receipts)
    '1010' Android Card Terminals
    needsSignature A boolean indicating if the receipt needs a signature section.
    (Used in successful receipts)
    false Android Card Terminals
    addQRCode A boolean indicating if the order code should be printed as a QR.
    (Used in successful receipts)
    false Android Card Terminals
    terminalSerialNumber The serial number of the terminal.
    (Used in successful receipts)
    “1234567891“ Android Card Terminals
    currency The currency of the transaction.
    (Used in successful receipts)
    “EUR“ Android Card Terminals
    errorText Text to print on the receipt stating the error description and the error ccode.
    (Used in declined receipts)
    “Transaction failed - Z-3“ Android Card Terminals
    applicationVersion The version off the application.
    (Used in declined receipts)
    'v3.7.0(1956)' Android Card Terminals
    aadeTransactionId An AADE-specific transaction ID.

    Format: Acquirer Unique code + RRN + Authorization code.

    Example: ‘116’ + ‘123456833121’ + ‘690882’ = '116123456833121690882'
    '116123456833121690882' Android Card Terminals'Viva.com Terminal' application for Android

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

    A sale response for a successful capture pre-auth transaction using AADE parameters looks as follows:

    Key to card terminal product categories

    To understand the icons used on the above tables, see the below table.

    Product category Terminal models Icon
    Android Card Terminals Android Card Terminal Ethernet, Android Card Terminal 4G, Mobile Card Terminal Plus, Mobile Card Terminal. Android Card Terminals
    'Viva.com Terminal' application for Android Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the 'Viva.com Terminal' application for Android. Android Card Terminals
    Linux Card Terminals Countertop, IM20, S900, S800, D200. Linux Card Terminals

    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!