UUID: Transactions are kept with this value on Payment Gate Way and bank application in case of a power cut. Payment Gate Way sends this value and waits for the return of the transaction result.
isDovizPOS : false: not Doviz Txn, true: Doviz Txn
currenyRate : Exchange Rate for currency. 4 bytes decimal. Ex: 1USD = 34,1234 is written as 341234
currencyUnit: Integer: This data is from MB currency Table and defines the unit scale for a particular currency used in exchange rate calculations. It specifies whether the exchange rate is based on 1 unit of the currency (like USD or EUR) or 100 units (like JPY).
Ex:
If the currencyUnit for JPY is 100, and the exchangeRate is21.1234 TL for JPY, it means 100 JPY = 21.1234 TL.
If the currencyUnit for USD is 1, and the exchangeRate is 35.1234 TL for USD, it means 1 USD = 35.1234 TL.
currencyCode : Currency Code for Sale (TRY, USD, EUR, RUB, GBP, JPY)
currenyAmount : Integer: Ex: 1.25 TL is written 125
Manifest Modifications
To be able to get data from payment gateway, there should be intent filter like below in related class.
paymentStatus : If discount or surcharge is applied, paymentStatus must be set accordingly.
enumRESPONSE_CODE{ NORMAL, DISCOUNTED, SURCHARGE // Reserved for future use }
amount : Integer. Amount that is charged by the payment application. If amount is less than the Broadcasted Amount by Payment Gateway, it means Partial Limit is applied.
amount2 : Integer. If a discount is made by the payment application, this value should be set according to the amount.
Ex: Amount from Payment Gateway : 1000 Amount : 900 Discount Amount : 100
batchNo : It is the current Batch No which includes current sale.
txnNo : It is the current Txn No of the sale in current Batch.
CardNo : Masked Card Number, first eight and last four digit is visible others are masked with '*' 12345678****7890
TID : Terminal ID
MID : Merchant ID
IsSlip: Indicates that if a payment slip will be printed or not. (true to print slip)
SlipType: Value that presents which slip types will be printed.
responseCode : Return of the pos settings request.
6. Power Cut Inquiry
If there has been a power cut during a sale transaction, transaction is inquired after device reboot. In order to receive inquiry and return transaction information, a broadcast receiver must be registered in the Android manifest file with action "check_sale" like below:
When inquiry broadcast is received, in the broadcast receiver's onReceive() method, if transaction is successful, transaction info must be returned in a bundle like below.
@OverridepublicvoidonReceive(Context context,Intent intent) {if (intent.hasExtra("UUID")) {String uuid =intent.getExtras().getString("UUID");...//check if a successful transaction with uuid exists...Intent resultIntent =newIntent();if (transaction !=null) {Bundle bundle =newBundle();bundle.putInt("ResponseCode",ResponseCode.SUCCESS.ordinal());bundle.putInt("PaymentStatus",0);bundle.putInt("Amount",...);bundle.putInt("Amount2",...);bundle.putString("customerSlipData",...);bundle.putString("merchantSlipData",...);bundle.putInt("BatchNo",...);bundle.putInt("TxnNo",...);bundle.putInt("SlipType",SaleSlipType.BOTH_SLIPS.value);bundle.putBoolean("IsSlip",true);resultIntent.putExtras(bundle); }resultIntent.setAction("check_sale_result");resultIntent.setPackage("com.tokeninc.sardis.paymentgateway");context.sendBroadcast(resultIntent); } }
If you are using SQLite database to store transactions, you should configure your database to insert record instantly when a transaction completed in case of a power cut scenario. https://www.sqlite.org/pragma.html#pragma_synchronous
To do this, in your SQLiteOpenHelper class, override onConfigure() method and add the following code:
Following code snippet is used by PaymentGateway in order to check the payment, if there is a power cut PaymentGateway checks for the last sale result then returns UUID to ask for the result of the last sale status.
Void/Refund transaction is started outside of Bank Application. In order for this to work, bank apps must return Refund Info at the end of a successful sale transaction along with other sale data.
RefundInfo is a string which could be in any format that your bank application could use later in case of a refund. Remember, this info will be used only by regarding Bank's application itself.
For your refund activity to be triggered by platform, register your activity with action named "Refund_Action".
In case your refund activity is triggered, the same RefundInfo string you returned with sale data will be delivered to you. In your activity, you could retrieve it this way:
//In this case, RefundInfo is a JSON value, but you could use any format you want.String refundInfo =getIntent().getStringExtra("RefundInfo");try {JSONObject json =newJSONObject(refundInfo); batchNo =json.getInt("BatchNo"); txnNo =json.getInt("TxnNo");}//Customer shouldn't need to enter any input about transaction except card information.//All the other transaction data should be retrieved in RefundInfo string.//Do the void/refund transaction and return the result:Intent resultIntent =newIntent();Bundle bundle =newBundle();bundle.putInt("ResponseCode",responseCode.ordinal());resultIntent.putExtras(bundle);setResult(Activity.RESULT_OK, resultIntent);finish();// Always return activity result "RESULT_OK" with "ResponseCode".// On Back Press, return activity result "RESULT_CANCELED", platform will consider as "5002", "CANCELED".@OverridepublicvoidonBackPressed() {setResult(Activity.RESULT_CANCELED); super.onBackPressed();}
8. Remote Activation
To be able to list your bank application in device, you need to support remote activation system as example given below. Let's say you have an activity to run activation process. For that activity or other ui element, you have to support given intent filter below to run activation process.
Inside intent bundle, you'll see parameters for use that are merchantID and terminalID as string. It's up to you to use this parameters as it totally depends your design. This will start your activation process remotely. When activation on your app is complete
and your intent should contain field "message" to understand and log it.
9. Update Parameters on Active Bank App
If your bank application on same fiscal id has changeable merchantID and terminalID, you have to support given intent filter below to run activation process. Let's say you have an activity to run activation process. For that activity or other ui element,
Inside intent bundle, you'll see parameters for use that are merchantID and terminalID as string. It's up to you to use this parameters as it totally depends your design. This will start your terminalID and merchantID update process remotely. When update on your app is complete
and your intent should contain field "message" to understand and log it.
10. Manual Bank Activation
Let's say some operator needs to install your application manually and doesn't have a chance to send remote activation process. For that kind of situations, please use function setBankParams at
Important Note: If you don't implement this function, your application can't be activated and it can't seen in atms. Therefore you couldn't see your bank applications on POS transactions and sale menu! You can read Pos Settings on the Template Banking app for more information.
DeviceInfo deviceInfo =newDeviceInfo(context);deviceInfo.setBankParams(new DeviceInfo.DeviceInfoBankParamsSetterHandler() { @OverridepublicvoidonReturn(boolean success) {//Handle result, it might not be written for some case.//If it's successfully written, you will get result as true }},"yourTerminalId","yourMerchantId");
11. Auto Card Routing
The bank that will be include the card forwarding system must share the current EMV Contactless Config file, BIN table, allowed transaction types and supported AID list with the Token platform. Relevant information will be shared with the platform in the response of the parameter command initiated in the Trigger time. CL Config files shared by banks will be combined into a single file and used in the card routing infrastructure. The shared BIN ranges will be added to the BIN table created with the relevant bank's ID, and the shared ranges will be updated at the next trigger by deleting the old BIN ranges.
For detailed documentation:
11.1 Sale
11.1.1 Card Route Flow
11.1.2 Card Read Type & Card Data
ICC
In addition to the amount, the card reading type will be sent to the relevant bank in integer value. The relevant bank will initiate its own card reading processes as it currently uses. In addition, the TCardService API, which is started during card reading, will continue by closing the card reading screen.
In order to perform "Single Tap" CL transactions, card reading will be done by Token Platform and after validation, the card type and card information provided by TCardService will be forwarded to the relevant bank in String format in the same way. The relevant bank will parse and use the shared card data as they currently use it.
In order to perform "Single Swipe" MSR transactions, card reading will be done by Token Platform and after validation, the card type and card information provided by TCardService will be forwarded to the relevant bank in String format in the same way. The relevant bank will parse and use the shared card data as they currently use it.
{"resultCode":0,"mCardReadType":2,"mCardNumber":"5168881167113299","mTrack2Data":"1201530011?",//other than pan and exp date"mExpireDate":"2711","mTranAmount1":123,"mTrack1CustomerName":"REMZI SEPIK","Track1Data":"%B5168881167113299^SEPIK\/REMZI ^27111201100000000153000000?","Track2Data":";5168881167113299=27111201530011?"}
11.2 Card Routing Configuration and Requirements by Bank
11.2.1 Parameter_Action Response Data
Relevant information will be shared with the platform at the end of the parameter action process initiated on the Trigger time. If the current application parameter loading is successful, the Activity Result returns as "RESULT_OK". In unsuccessful cases, it returns as "RESULT_CANCELLED". If parameter loading is successful at the end of the parameter action in the new flow, the bundle containing the necessary information should be added to the Activity Result Intent.
The CL Config file will be added with the tag "clConfigFile" in String format, as it is also used for the setEMVCLConfig API.
BIN Ranges
BIN Ranges will be shared as a JSON Array constructed with the Start value "cardRangeStart", the End value "cardRangeEnd", the Card property "OwnerShip" and the Card type "CardType". BIN range start and end values will be shared as 13 digits.
Note: NOTONUS BIN's were removed as part of the project. Banks do not need to share NOTONUS BIN ranges. Not-ISSUER and non-BRAND BIN's will be considered as NOTONUS.
Allowed Operations will be added with the "AllowedOperations" tag. The allowed transactions will be added as JSON Object, whether the terminal allows payment with QR or not and whether it allows Key In transactions. It will be indicated with “1” if the operation is allowed, “0” if not.
Supported Currencies will be added with the "SupportedCurrencies" tag and shared as a String Array.
Supported Currencies Bundle Example
SupportedCurrencies=[USD, EUR, GBP, JPY, RUB]// USD = US Dollar// EUR = Euro// GBP = British Pound// JPY = Japanese Yen// RUB = Russian Ruble
11.3 Device Info
A "CARD_REDIRECTION" field has been added to the currently used Device Info library to determine whether 400TR and 1000TR devices are included in the card routing system. This parameter will be set via ATMS and it will be possible to determine whether there is a card forwarding compatible device from within the application.
