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.
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.
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,
Synchronous callbacks: These callbacks are called in kernel thread, kernel suspends until application returns from the function.
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.onReadRecordsCompleted
: Called after read records completed, the application may override some parameters according to records read.onCvmDecision
: Called before CVM processing, the application may override the CVM method.onTryAgain
: Called if card communication fails, and a new tap is required, the application may return false if a new try is not preferred.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.
Informative (async) callbacks: These callbacks are run in the UI thread, the kernel continues its flow in parallel, nothing waits from the application.
onNotifyCardWait
: Inform user about card readonNotifyCardInProgress
: Inform user about a card in progressonNotifyCardRemoval
: Inform user about card removalonNotifyCardRetry
: Inform user about card retry (note that before this callonTryAgain
was called, if the application returns true on that call, this function is invoked, and kernel starts to listen for a card)
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.
onOnlineAuthorization
: Send an authorization request to the acquirer, and inform the kernel about the authorization result. After authorizationcompleteEMVTransaction
function is called.onTransactionCompleted
: Called after kernel finishes. the result might be approved or declined.onTransactionTerminated
: Called after kernel finishes with error.onPerformPinEntry
: Online pin is acquired. After pin entryuserInputEntered
function is called.onPerformSignatureEntry
: Signature is acquired. After signature entryuserInputEntered
function is called. If the signature will be acquired later, the application may immediately enter the kernel.