On Android
Refers to Android SDK v3.0
The Clover Connector Android SDK provides an interface that enables your point-of-sale (POS) software to interact with Clover’s customer-facing payment devices.
This tutorial guides you through the process of connecting to your Clover device, initiating a Sale request, and handling the response to your Sale request. It covers version 3.0 of the SDK.
Platform-specific prerequisites
In addition to the prerequisites in Use Clover Connector, this tutorial assumes you have already:
- Installed the USB Pay Display app on your Clover Mini. You can also use the Secure Network Pay Display app for a local network connection (currently available for Clover Flex, Clover Mini, and Clover Mobile).
- Installed Android Studio on your computer. You will need to require Maven in your Android Studio project.
- Updated the project's
build.gradle
with the followingbuildscript
settings:
buildscript {
repositories {
jcenter()
mavenCentral()
}
def mavenPlugin = "com.github.dcendents:android-maven-gradle-plugin:1.5"
dependencies {
classpath 'com.android.tools.build:gradle:2.3.0'
classpath mavenPlugin
}
}
- Updated your module's
build.gradle
with a dependency on the latest version of the Clover Remote Pay Android SDK:
repositories {
mavenCentral()
}
dependencies {
……
compile 'com.clover.sdk:remote-pay-android-connector:latest.release'
}
- Updated your module's manifest with the following permission declarations:
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
Connectivity
USB is the preferred method of communication with the Clover device. The Android SDK provides an .aar
file and a USB connector for tethering a Clover device to an Android device over USB. The USB connector requires the USB Pay Display app to communicate with a Clover device.
NOTE
If your point of sale does not use USB to communicate, please email [email protected].
Configure a connection
Configure the connection between your Android device and the Clover device. The following example demonstrates how to configure a USB connection. You can also configure a network connection. Both types of connections require your app to include your remote app ID, the application-specific value that Clover uses to log information about your integration.
new USBCloverDeviceConfiguration(this, "SWDEFOTWBD7XT.9MGLGMDLSYWTV");
Create a Clover Connector
Create a Clover Connector and pass in the configuration from the previous step. The following example is for a network connection. You can also pass in a USB configuration.
cloverConnector = new CloverConnector(getNetworkConfiguration("192.168.0.131",12345));
Add a listener to the Clover Connector
- Define an
ICloverConnectorListener
that will listen for callbacks when transactions finish and other events occur. Include the connection status methods that will be called.
OnDeviceDisconnected()
—Clover device is not available.OnDeviceConnected()
—Clover device is connected, but not available to process requests.OnDeviceReady()
—Device is connected and available to process requests. It will automatically pass in aMerchantInfo
object with information about the device, merchant, and some potential merchant payment configuration data, such assupportsAuths
orsupportsVaultCards
.
private final class TestListener extends DefaultCloverConnectorListener {
public TestListener(ICloverConnector cloverConnector) {
super(cloverConnector);
}
@Override
public void onConfirmPaymentRequest(ConfirmPaymentRequest request) {
}
//additional methods can be overriden later
}
- Add the listener to the Clover Connector.
cloverConnector.addCloverConnectorListener(new TestListener(cloverConnector));
Initialize the connection
Initialize the connection to start communication with the Clover device. Note that you must do this before calling any other methods (other than those that add or remove listeners).
cloverConnector.initializeConnection();
Send a test message to the Clover device.
cloverConnector.showMessage("Welcome to Clover Connector!");
Now that you’ve connected to the Clover device and sent a successful test message, you’re ready to start making requests.
Initiate a sale from your POS software
To make a Sale()
request:
- Define how to handle the
SaleResponse
in yourICloverConnectorListener
. The truncated code below provides a generalized overview of the methods you’ll need to use to get a response to your request for aSale
. A detailed interpretation of theSaleResponse
appears in the Handle the result of a Sale transaction section section.
private final class TestListener extends DefaultCloverConnectorListener {
public TestListener(ICloverConnector cloverConnector) {
super(cloverConnector);
}
@Override
public void onSaleResponse(SaleResponse response) {
// check response for success and process accordingly
// see below for more detail ‘Handling Results of a Sale Transaction’
…
}
@Override
public void onConfirmPaymentRequest(ConfirmPaymentRequest request) {
// must accept or reject the payment using the ICloverConnector
// see below for more detail ‘Handling Results of a Sale Transaction’
…
}
@Override
public void onVerifySignatureRequest(VerifySignatureRequest request) {
// must accept or reject the signature using the ICloverConnector
// see below for more detail ‘Handling Results of a Sale Transaction’
…
}
}
- Create a
SaleRequest
and call theSale()
method.
pendingSale = new SaleRequest(1000, MainActivity.getNextId());
cloverConnector.sale(pendingSale);
NOTE
The code snippets in this tutorial are not feature-rich. For the best way to implement the SDK in production, see the Example Android POS.
Once you call the Sale()
method, Clover will contact the payment gateway and return information about the result of the transaction to your POS.
Handle the result of a sale transaction
After Clover has finished processing the Sale
transaction request, OnSaleResponse()
will be called. Transaction responses have a boolean Success
property, as well as an enum Result
property that provides information on the success flag.
If the transaction is successful, the response will also have the Payment
object, which may contain the full or partial amount of the Sale
request.
NOTE
A Sale transaction may come back as a tip-adjustable
Auth
, depending on the payment gateway. TheSaleResponse
includes a booleanisSale
variable that indicates whether theSale
is final, or will be finalized during closeout.
private final class TestListener extends DefaultCloverConnectorListener {
public TestListener(ICloverConnector cloverConnector) {
super(cloverConnector);
}
@Override
public void onConfirmPaymentRequest(ConfirmPaymentRequest request) {
Log.d(TAG,"Confirm Payment Request");
addText("Confirm Payment Request");
Challenge[] challenges = request.getChallenges();
if (challenges != null && challenges.length > 0)
{
for (Challenge challenge : challenges) {
Log.d(TAG,"Received a challenge: " + challenge.type);
addText("Received a challenge: " + challenge.type);
}
}
addText("Automatically processing challenges");
Log.d(TAG, "Automatically processing challenges");
cloverConnector.acceptPayment(request.getPayment());
}
@Override
public void onSaleResponse(SaleResponse response) {
try {
if (response.isSuccess()) {
Payment payment = response.getPayment();
if (payment.getExternalPaymentId().equals(pendingSale.getExternalId())) {
String saleRequest = ("Sale Request Successful\n");
saleRequest += (" ID: " + payment.getId()+"\n");
saleRequest += (" External ID: " + payment.getExternalPaymentId()+"\n");
saleRequest += (" Order ID: " + payment.getOrder().getId()+"\n");
saleRequest += (" Amount: " + payment.getAmount()+"\n");
saleRequest += (" Tip Amount: " + payment.getTipAmount()+"\n");
saleRequest += (" Tax Amount: " + payment.getTaxAmount()+"\n");
saleRequest += (" Offline: " + payment.getOffline()+"\n");
saleRequest += (" Authorization Code: " + payment.getCardTransaction().getAuthCode()+"\n");
saleRequest += (" Card Type: " + payment.getCardTransaction().getCardType()+"\n");
saleRequest += (" Last 4: " + payment.getCardTransaction().getLast4());
addText(saleRequest);
Log.d(TAG,"sales request: "+saleRequest);
} else {
addText("Sale Request/Response mismatch - " + pendingSale.getExternalId() + " vs " + payment.getExternalPaymentId());
Log.d(TAG,"Sale Request/Response mismatch - " + pendingSale.getExternalId() + " vs " + payment.getExternalPaymentId());
}
} else {
addText("Sale Request Failed - " + response.getReason());
Log.d(TAG,"Sale Request Failed - " + response.getReason());
}
} catch (Exception ex) {
Log.d(TAG,"Error handling sale response");
ex.printStackTrace();
}
}
@Override
public void onVerifySignatureRequest(VerifySignatureRequest request) {
super.onVerifySignatureRequest(request);
addText("Verify Signature Request - Signature automatically accepted by default");
Log.d(TAG,"Verify Signature Request - Signature automatically accepted by default");
}
}
Sale transaction errors
OnSaleResponse()
also returns one of the following codes:
Error code | Description |
---|---|
SUCCESS | Call succeeded and was successfully queued or processed. |
FAIL | Call failed due to an incorrect value that was passed in, an invalid card, insufficient funds, or another reason. |
UNSUPPORTED | Current merchant configuration doesn’t support the capability. |
CANCEL | Merchant or customer has pressed the Cancel or Back button on the Clover device. |
ERROR | Unexpected error or error that wasn't handled appropriately. Returned when the SDK encounters one of the following problems: - Device Connection Error : Clover device is not connected.- Request Validation Error : Request that was passed in for processing is empty.- Request Validation Error : Request ExternalId cannot be null or blank.- Request Validation Error : Request amount cannot be zero.- Request Validation Error : Request tip amount cannot be less than zero.- Merchant Configuration Validation Error : Not offered by the merchant-configured gateway. |
Test your app
Test your app using the Test card numbers for declines and partial transactions. For information, see Test region-based payment flows page.
Additional resources
Updated about 2 months ago