Capture Pre-auth request
An overview of the Capture Pre-auth request message for Android.
- Overview
- Capture Pre-auth request
- Capture Pre-auth response
- Key to card terminal product categories
- Get Support
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 originating from the client app to initiate a request for a Capture Pre-auth transaction
- Capture Pre-auth response originating from the ‘Viva.com Terminal’ application to return the result of a Capture Pre-auth transaction
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' | ✅ | |||
merchantKey | The merchant's key. For successful validation, should not be empty. Deprecated: you may pass any value. |
'SG23323424EXS3' | ||||
appId | The client app ID. For successful validation, should not be empty. | 'com.example.myapp' | ✅ | |||
action | Pre-auth transaction. For successful validation, should not be empty. | 'capture_pre_auth' | ✅ | |||
callback | The URI callback that will handle the result. For successful validation, should not be empty. | 'mycallbackscheme://result' | ✅ | |||
amount | The amount to be captured, in cents. | '1200' = 12 euro | ✅ | integer (int32) | ||
sourceCode | The store/source code that will be linked to the transaction.
|
[A payment source (physical store) that is associated with the transaction] How to create a payment source for CP payments |
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) |
integer (int32) | ||
orderCode | If not empty should be integer bigger than zero and length 16. | '1020304050607080' | integer (int32) | |||
shortOrderCode | If not empty should be integer bigger than zero and length 10. | '1234567890' | 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' | 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' | 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' | boolean | |||
show_transaction_result | A flag indicating whether transaction result will be shown. | 'true' | boolean | |||
show_rating | A flag indicating if the rating flow will be shown. | 'true' | 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. 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) For integration through ΦΗΜΑΣ, please specify as `aadeProviderId' the value 800 |
Integration with Provider (ΥΠΑΗΕΣ) 999 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) 800 |
3 | Numeric | ||
aadeProviderSignatureData [*] | 👉 Integration with Provider (ΥΠΑΗΕΣ) The unencrypted signature that includes the fields below with semicolon as a delimiter “;”: 👉 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 |
200 | Alphanumeric | ||
aadeProviderSignature [*] | 👉 Integration with Provider (ΥΠΑΗΕΣ) The fields of providerSignatureFields encrypted using a public key and the Elliptic Curve Digital Signature Algorithm (ECDSA): 👉 Integration with ΦΗΜΑΣ (Φορολογικός Ηλεκτρονικός Μηχανισμός Ασφαλείας) Use SessionKey as in A.1098/2023 |
Integration with Provider (ΥΠΑΗΕΣ) o0094r3Yk3KTqASLkW3evlDsnIg/ZAdUUf6UCXDtjqpI/dquzAT4WNX3yzS/GLciVNbT75H4pj8hLOV0EpHtzw==" |
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.
A Capture Pre-auth response result for an approved transaction looks as follows:
mycallbackscheme://result?status=success&message=Transaction successful&action=capture_pre_auth&amount=10&verificationMethod=&rrn=235314357110&cardType=&referenceNumber=357110&accountNumber=************0178&authorisationCode=000445&tid=16022145&orderCode=2353151181022145&transactionDate=2022-12-19T16:08:10.9105065+02:00&transactionId=2ef43138-2a1a-433e-8df1-72911d53169f&shortOrderCode=2353151181&vatNumber=EL096019265&address=kifisias 10, 12342 Athens&businessDescription=AGROTIKOS SYNETAIRISMOS MESOLOGGIOU NAUPAKTIAS I ENOSI&printLogoOnMerchantReceipt=false&cardholderNameExpirationDateFlags=0000&needsSignature=false&addQRCode=false&terminalSerialNumber=1490355478¤cy=EUR&applicationVersion=v4.11.0(4800)&entryMode=00&cashless=false&sourceCode=6532
A sale response for a successful capture pre-auth transaction using AADE parameters looks as follows:
mycallbackscheme://result?status=success&message=Transaction successful&action=capture_pre_auth&amount=10&verificationMethod=CONTACTLESS&rrn=235314357110&cardType=MASTERCARD&referenceNumber=357110&accountNumber=615524******0178&authorisationCode=000445&tid=16022145&orderCode=2353151181022145&transactionDate=2024-02-19T16:08:10.9105065+02:00&transactionId=2ef43138-2a1a-433e-8df1-72911d53169f&shortOrderCode=2353151181&aadeTransactionId=116407412859092859078&sourceCode=6532
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. | |
'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. | |
Linux Card Terminals | Countertop, IM20, S900, S800, D200. |
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!