Android POS SDK Developer Page

You can integrate Android POS SDK (KernelClient SDK) into your mobile POS application quickly.

The SDK facilitates communication between your point of sale application logic and the Fairbit Cloud kernel API.

Get Free Consultation
 

Android POS SDK

Android POS SDK integration starts with your mobile POS application running on an Android phone. The application calls KernelClient SDK APIs to perform a contactless payment transaction. A typical integration is illustrated in the diagram below.

Android POS SDK

Setting Up KernelClient Library

Android POS SDK is given as an android library file. Please reach out to [email protected] to get the Android POS SDK.

This library is added to an android project as described in the following steps:

				
					Import AAR
File > New > New Module

Import JAR/.AAR Package > Next
Select "kernelclient.aar" file > Finish
				
			
				
					Add Dependency
in "build.gradle" file

dependencies {
implementation project(':kernelclient')
}
				
			
				
					Permissions
in "AndroidManifest.xml" file

Interacting with KernelClient

Client application interacts with EmvKernelClient class only. All methods of this class are static, the application doesn’t create an instance, all the flows and kernel logic are handled in this class. There are some callbacks made to the application.

Application calls some methods at startup, probably at the start of the main activity. setCloudUrl, setLastLocation and setSerial methods might be called multiple times whenever the value is changed. the latest value is used in a transaction.

				
					Kernel Initialize Function

        EmvKernelClient.start(MainActivity.this);
        EmvKernelClient.setCloudUrl(Preferences.getCloudUrl());
        EmvKernelClient.setLastLocation(location.getLatitude(), location.getLongitude());
        String serial = Secure.getString(this.getContentResolver(), Secure.ANDROID_ID);
        EmvKernelClient.setSerial(serial);

Fairbit EMV Terminal Parameters Configuration Portal

EMV terminal parameters are managed at cloud, hence client application doesn’t care about the EMV configuration parameters, only dynamic transaction parameters are passed to the kernel.

You can sign up to Fairbit EMV parameter portal to update EMV configuration parameters. Please reach out to [email protected] to get access to the portal.

Please see  EMV parameter portal for more details.

 

Start Transaction

To pass transaction parameters, TransactionParameters class is used, Below sample shows minimum items required in a transaction.

 

				
					Creating Transaction Parameters 

        TransactionParameters parameters = new TransactionParameters();
        parameters.setEmvConfigName_Version("EMVConfig_V1.1");
        parameters.setAcquirerName("TSYS");
        parameters.setTransactionType("00");
        parameters.setTransactionAmount("100");
        parameters.setCurrencyCode(840);
        parameters.setCurrencyExponent(2);
        parameters.setTransactionDate(20211231);
        parameters.setTransactionTime(235959);
        EmvKernelClient.setParameters(parameters);

Below sample code starts a transaction using an internal NFC reader. The transaction is continued in another thread and the application receives callbacks through an KernelCallback instance. Application may use its own card reader instead of NFC, by implementing CardReader an interface and passing an instance of reader class to setCardReader function.

 

				
					Starting Transaction 

        EmvKernelClient.resetTransaction(Preferences.acquirerId, Preferences.merchantId, Preferences.terminalId);
        EmvKernelClient.setKernelCallback(kernelCallback);
        EmvKernelClient.setCardReader(EmvKernelClient.createNfcCardReader(this));
        EmvKernelClient.initiateEMVTransaction());

End of Transaction

Normally application is informed about transaction result using callback functions (the result may be an approval, a decline, or an error). Also, an application may stop the transaction before the kernel is finished. There are 2 functions to end a transaction before it finishes.

stopTransaction : this call doesn’t terminate the transaction immediately. It signals the kernel about the stop request. Kernel stops the flow asap if it isn’t finished already. The application receives result callbacks after the kernel finishes its flow.

cancelTransaction : this function forcefully ends the kernel flow.

Kernel Callbacks

There are 2 types of callbacks,

  1. Synchronous callbacks: These callbacks are called in kernel thread, kernel suspends until application returns from the function.

    1. onAppSelectCompleted : Called after application selection, Aid list is passed to the application, the application may return preferred AID. If null is returned, the kernel selects the application according to EMV flow.

    2. onReadRecordsCompleted : Called after read records completed, the application may override some parameters according to records read.

    3. onCvmDecision : Called before CVM processing, the application may override the CVM method.

    4. onTryAgain : Called if card communication fails, and a new tap is required, the application may return false if a new try is not preferred.

    5. onSignalReceived : (optional) Called if DEK signal is received in Mastercard flow. Application may return a DET signal immediately or may callprocessDetSignal later. processDetSignal a signal may be called several times according to Mastercard flow.

  2. Informative (async) callbacks: These callbacks are run in the UI thread, the kernel continues its flow in parallel, nothing waits from the application.

    1. onNotifyCardWait : Inform user about card read

    2. onNotifyCardInProgress : Inform user about a card in progress

    3. onNotifyCardRemoval : Inform user about card removal

    4. onNotifyCardRetry : Inform user about card retry (note that before this call onTryAgain was called, if the application returns true on that call, this function is invoked, and kernel starts to listen for a card)

  3. Action (async) callbacks: These callbacks are also asynchronous, but the kernel does not continue processing, the application should reenter to kernel flow using appropriate calls.

    1. onOnlineAuthorization : Send an authorization request to the acquirer, and inform the kernel about the authorization result. After authorization completeEMVTransaction function is called.

    2. onTransactionCompleted : Called after kernel finishes. the result might be approved or declined.

    3. onTransactionTerminated : Called after kernel finishes with error.

    4. onPerformPinEntry : Online pin is acquired. After pin entry userInputEntered function is called.

    5. onPerformSignatureEntry : Signature is acquired. After signature entry userInputEntered function is called. If the signature will be acquired later, the application may immediately enter the kernel.