If you are currently using 5.x of the Android SDK, take a look at the migration guide to 6.x

The new generation of Handpoint APIs and SDKs are engineered to make your life simpler and happier.

Awesomely simple

Created for humans, coders, geeks, no need of a dark and complex knowledge of the payment industry.

Super secure

We take care of PCI compliance so you can be kept out of scope

The Handpoint terminals encrypt all sensitive cardholder data so your app does not have to deal with it.

Available through Maven Central

The Handpoint Android SDK is compatible with Android version 5.1.1 (API level 22) and up.

The latest version is compiled with java 1.8

Maven:

                    	
    <dependency>
      <groupId>com.handpoint.api</groupId>
      <artifactId>sdk</artifactId>
      <version>[6.0.0,7.0.0)</version>
      <type>aar</type>
    </dependency>
                    	
                

Gradle:

                    	
    implementation 'com.handpoint.api:sdk:6.+'





                    	
                

If you have any questions, do not hesitate to contact us.

Version 6.0.0 introduces a well defined, typed, way of passing extra values, options, parameters or flags to the financial transactions.

We have unified all the extra and optional parameters in an Options object. Different operations have different options.

1. For a Sale or Sale and Tokenize operation, please see SaleOptions

If you use a customer reference:

                    
	options.setCustomerReference("Your customer reference");
                    
                

If you need Multi MID / Custom merchant Authentication:

                    
	MerchantAuth auth = new MerchantAuth();
	Credential credential = new Credential();
	//Optionally
	credential.setAcquirer(YOUR_ACQUIRER);
	//Optionally
	credential.setMerchantId(mid);
	//Optionally
	credential.setTerminalId(tid);
	//Add as many credentials as Acquirers your merchant have agreements with
	auth.add(credential);
	options.setMerchantAuth(auth);
                    
                

If you need to enable pin bypass:

                    
	options.setPinBypass(true);
                    
                

If you want to specify the budget period Only available for SureSwipe:

                    
	options.setBudgetNumber(YOUR_BUDGET_NUMBER);
                    
                

If you want to specify tip options Only available for PAX and Telpo terminals:

                    
	TipConfiguration config = new TipConfiguration();
	//Optionally
	config.setHeaderName(HEADER);
	//Optionally
	config.setFooter(FOOTER);
	//Optionally
	config.setEnterAmountEnabled(true);
	//Optionally
	config.setSkipEnabled(true);
	//Optionally
	config.setTipPercentages(percentages);

	options.setTipConfiguration(config);
                    
                

Alternatively, you can set the tip amount directly:

                    
	options.setTipConfiguration(new TipConfiguration(AMOUNT));
                    
                

Finally:

                    
	api.sale(amount, currency, options);
                    
                

2. Similar to SaleOptions, but with less possible parameters, for a Refund operation, please see RefundOptions

If you use a customer reference:

                    
	options.setCustomerReference("Your customer reference");
                    
                

If you need Multi MID / Custom merchant Authentication:

                    
	MerchantAuth auth = new MerchantAuth();
	Credential credential = new Credential();
	//Optionally
	credential.setAcquirer(YOUR_ACQUIRER);
	//Optionally
	credential.setMerchantId(mid);
	//Optionally
	credential.setTerminalId(tid);
	//Add as many credentials as Acquirers your merchant have agreements with
	auth.add(credential);
	options.setMerchantAuth(auth);
                    
                

If you need to enable pin bypass:

                    
	options.setPinBypass(true);
                    
                

Finally:

                    
	api.refund(amount, currency, options);
                    
                

3. For the rest of operations, please see Options

If you use a customer reference:

                    
	options.setCustomerReference("Your customer reference");
                    
                

Supported functionality

• List the available payment terminals
• Connect/disconnect to and from a payment terminal.
• Automatically or manually reconnect to a payment terminal.
• Execute financial transactions.
• Get the status of transactions.
• Control and access the device logs.

Processing Payments Simulation

Your test payments are sent against a test server on the Handpoint side which simulates the behavior of an acquiring bank. Funds are not moved and sensitive data from the card is fully encrypted. You can use trigger amounts to generate some specific responses from our server:

We support the following connection methods

1. Android Payment Terminal
2. Bluetooth
3. Cloud

Android Terminal Native Integration

Introduction

Let's start programming!

1. Modify the AndroidManifest.xml

We strongly recommend you add the following to your main <activity>:

android:launchMode="singleTask"

2. In the gradle.build

android {
	defaultConfig {
		minSdkVersion 22 //Required to support all PAX & Telpo models
		targetSdkVersion 29
		multiDexEnabled true
	}

    packagingOptions {
        pickFirst '**/*.so'
        exclude 'META-INF/*'
        exclude '**/anim/*.xml'
        exclude '**/layout/*.xml'
        exclude 'resources.arsc'
        exclude 'AndroidManifest.xml'
        exclude ‘**/animator/*.xml'
    }
}

3. Create a Java class

Create a new java class called HandpointDelegate.java and include com.handpoint.api.* as a dependency:

package com.yourpackage.name;

import com.handpoint.api.HandpointCredentials;
import com.handpoint.api.Hapi;
import com.handpoint.api.HapiFactory;
import com.handpoint.api.shared.ConnectionMethod;
import com.handpoint.api.shared.ConnectionStatus;
import com.handpoint.api.shared.Currency;
import com.handpoint.api.shared.Device;
import com.handpoint.api.shared.Events;
import com.handpoint.api.shared.SignatureRequest;
import com.handpoint.api.shared.StatusInfo;
import com.handpoint.api.shared.TipConfiguration;
import com.handpoint.api.shared.TransactionResult;
import com.handpoint.api.shared.agreements.Acquirer;
import com.handpoint.api.shared.agreements.Credential;
import com.handpoint.api.shared.agreements.MerchantAuth;
import com.handpoint.api.shared.options.SaleOptions;

import java.math.BigInteger;
import java.util.Arrays;
import java.util.List;

//Check all the events available in the Events interface.
//If you want to subscribe to more events, just add to the list of implemented interfaces.
public class HandpointDelegate implements Events.Required, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus {

    private Hapi api;

    public HandpointDelegate(Context context) {
        initApi(context);
    }

    public void initApi(Context context) {
        String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret);
        this.api = HapiFactory.getAsyncInterface(this, context, handpointCredentials);
        // The api is now initialized. Yay! we've even set default credentials.
        // The shared secret is a unique string shared between the payment terminal and your application, it is unique per merchant.
        // You should replace this default shared secret with the one sent by the Handpoint support team.

        //Since we're running inside the terminal, we can create a device ourselves and connect to it
        Device device = new Device("some name", "address", "", ConnectionMethod.ANDROID_PAYMENT);
        this.api.connect(device);
    }

    @Override
    public void connectionStatusChanged(ConnectionStatus status, Device device) {
        if (status == ConnectionStatus.Connected) {
            //Connection Status connected

        }
    }

    @Override
    public void deviceDiscoveryFinished(List<Device> devices) {
        // This event can be safely ignored for a PAX/Telpo integration
    }

    public boolean pay() {
        return this.api.sale(new BigInteger("1000"), Currency.GBP);
        // Let´s start our first payment of 10 pounds
        // Use the currency of the country in which you will be deploying terminals
    }

    public boolean payWithOptions() {
        SaleOptions options = new SaleOptions();

        // Adding tipping
        TipConfiguration config = new TipConfiguration();
        //Optionally
        config.setHeaderName("HEADER");
        //Optionally
        config.setFooter("FOOTER");
        //Optionally
        config.setEnterAmountEnabled(true);
        //Optionally
        config.setSkipEnabled(true);
        //Optionally
        config.setTipPercentages(Arrays.asList(5, 10, 15, 20));
        options.setTipConfiguration(config);

        // Adding Multi MID / Custom merchant Authentication
        MerchantAuth auth = new MerchantAuth();
        Credential credential = new Credential();
        //Optionally
        credential.setAcquirer(Acquirer.SANDBOX);
        //Optionally
        credential.setMid("mid");
        //Optionally
        credential.setTid("tid");
        //Add as many credentials as Acquirers your merchant have agreements with
        auth.add(credential);
        options.setMerchantAuth(auth);

        //Add a customer reference
        options.setCustomerReference("Your customer reference");

        //Enable pin bypass
        options.setPinBypass(true);

        //Enable signature bypass
        options.setSignatureBypass(true);

        //Define a budget number
        options.setBudgetNumber("YOUR_BUDGET_NUMBER");

        return this.api.sale(new BigInteger("1000"),Currency.GBP, options);
    }

    @Override
    public void currentTransactionStatus(StatusInfo statusInfo, Device device) {
        if (statusInfo.getStatus() == StatusInfo.Status.InitialisationComplete) {
            // The StatusInfo object holds the different transaction statuses like reading card, pin entry, etc.
            // Let's launch a payment
            pay();
        }
    }

    @Override
    public void signatureRequired(SignatureRequest signatureRequest, Device device) {
        // This event can be safely ignored for a PAX/Telpo integration
        // The complete signature capture process is already handled in the sdk, a dialog will prompt the user for a signature if required.
        // If a signature was entered, it should be printed on the receipts.
    }

    @Override
    public void endOfTransaction(TransactionResult transactionResult, Device device) {
        // The TransactionResult object holds details about the transaction as well as the receipts
        // Useful information can be accessed through this object like the transaction ID, the amount, etc.
    }

    @Override
    public void transactionResultReady(TransactionResult transactionResult, Device device) {
        // Pending TransactionResult objects will be received through this event if the EndOfTransaction
        // event was not delivered during the transaction, for example because of a network issue
        // For this sample app we are not going to implement this event
    }

    public void disconnect(){
        this.api.disconnect();
        //This disconnects the connection
    }
}
                

We're done!

Sort of. With the above tutorial you've done a basic integration that can perform sale transactions.

Explore the rest of the documentation to see more transaction types supported and possibilities.

Bluetooth Integration

Introduction

Let's start programming!

1. Modify the AndroidManifest.xml

We strongly recommend you add the following to your main <activity>:

android:launchMode="singleTask"

2. In the gradle.build

android {
	defaultConfig {
		minSdkVersion 22 //change the SDK version to the one corresponding to the device you are using
		targetSdkVersion 29
		multiDexEnabled true
	}

    packagingOptions {
        pickFirst '**/*.so'
        exclude 'META-INF/*'
        exclude '**/anim/*.xml'
        exclude '**/layout/*.xml'
        exclude 'resources.arsc'
        exclude 'AndroidManifest.xml'
        exclude ‘**/animator/*.xml'
    }
}

3. Create a Java class

Create a new java class called HandpointDelegate.java and include com.handpoint.api.* as a dependency:

package com.yourpackage.name;

import android.content.Context;

import com.handpoint.api.HandpointCredentials;
import com.handpoint.api.Hapi;
import com.handpoint.api.HapiFactory;
import com.handpoint.api.shared.ConnectionMethod;
import com.handpoint.api.shared.ConnectionStatus;
import com.handpoint.api.shared.Currency;
import com.handpoint.api.shared.Device;
import com.handpoint.api.shared.Events;
import com.handpoint.api.shared.SignatureRequest;
import com.handpoint.api.shared.TransactionResult;

import java.math.BigInteger;
import java.util.List;

//Check all the events available in the Events interface.
//If you want to subscribe to more events, just add to the list of implemented interfaces.
public class HandpointDelegate implements Events.Required, Events.ConnectionStatusChanged {

    private Hapi api;


    public HandpointDelegate(Context context) {
        initApi(context);
    }

    public void initApi(Context context) {
        String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret);
        this.api = HapiFactory.getAsyncInterface(this, context, handpointCredentials);
        // The api is now initialized. Yay! we've even set a shared secret!
        // The shared secret is a unique string shared between the card reader and your mobile application
        // It prevents other people to connect to your card reader
        // You have to replace this default shared secret by the one sent by our support team
        // The shared secret is unique per merchant (not per terminal)

        //Now we need to find our device and connect to it
        discoverDevices();
    }

    // Now  we need to connect to a device to start taking payments.
    // Let's search for them:
    public void discoverDevices() {
        this.api.searchDevices(ConnectionMethod.BLUETOOTH);
        // This triggers the asynchronous search for all the devices around that haven't been paired.
        // You could, alternatively, search for the already paired devices
        // List<Device> devices = this.api.getPairedDevices(ConnectionMethod.BLUETOOTH);
        // Now:
        // selectDeviceAndConnect(devices);
        // You'll receive the devices found through deviceDiscoveryFinished method.
        // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished
    }

    @Override
    public void deviceDiscoveryFinished(List<Device> devices) {
        selectDeviceAndConnect(devices);
    }

    private void selectDeviceAndConnect(List<Device> devices) {
        for (Device device : devices) {
            if (device.getName() != null) {
                // All the devices here are datecs devices
                if (/* Fill your logic here */) {
                    this.api.connect(device);
                    // Now take a look at connectionStatusChanged method
                    break;
                }
            }
        }
    }

    //Potentially, if you know the MAC address of the device you want to connect to, you can skip the search and do it this way
    public void connect() {
        Device device = new Device("PP0513901435", "68:AA:D2:00:D5:27", "", ConnectionMethod.BLUETOOTH);
        //The Address always has to be written in UPPER CASE
        //new Device("name", "address", "port", ConnectionMethod.BLUETOOTH);
        this.api.connect(device);
    }

    @Override
    public void connectionStatusChanged(ConnectionStatus status, Device device) {
        if (status == ConnectionStatus.Connected) {
            // Let's launch a payment
            pay();
        }
    }

    public boolean pay() {
        return this.api.sale(new BigInteger("1000"), Currency.GBP);
        // Let´s start our first payment of 10 pounds
    }

    @Override
    public void signatureRequired(SignatureRequest signatureRequest, Device device) {
        // You'll be notified here if a sale process needs a signature verification
        // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
        // This method will not be invoked if a transaction is made with a Chip & PIN card
        // At this step, you are supposed to display the merchant receipt to the cardholder on the android device
        // The cardholder must have the possibility to accept or decline the transaction
        // If the cardholder clicks on decline, the transaction is VOID
        // If the cardholder clicks on accept he is then asked to sign electronically the receipt
        this.api.signatureResult(true);
        // This line means that the cardholder ALWAYS accepts to sign the receipt
        // For this sample app we are not going to implement the whole signature process
    }

    @Override
    public void endOfTransaction(TransactionResult transactionResult, Device device) {
        // The object TransactionResult stores the different receipts
        // Other information can be accessed through this object like the transaction ID, the amount...
    }

    @Override
    public void transactionResultReady(TransactionResult transactionResult, Device device) {
        // Pending TransactionResult objects will be received through this event if the EndOfTransaction
        // event was not delivered during the transaction, for example because of a network issue.
        // For this sample app we are not going to implement this event.
    }

    public void disconnect() {
        this.api.disconnect();
        //This disconnects the connection
    }
}
                

We're done!

Sort of. With the above tutorial you've done a basic integration that can perform sale transactions.

Explore the rest of the documentation to see more transaction types supported and possibilities.

Cloud Integration

Introduction

Let's start programming!

1. In the gradle.build

android {
  	defaultConfig {
  		minSdkVersion 22 //Required to support all PAX & Telpo models
  		targetSdkVersion 29
  		multiDexEnabled true
  	}

    packagingOptions {
      pickFirst '**/*.so'
      exclude 'META-INF/*'
      exclude '**/anim/*.xml'
      exclude '**/layout/*.xml'
      exclude 'resources.arsc'
      exclude 'AndroidManifest.xml'
      exclude ‘**/animator/*.xml'
  }
}

2. Create a Java class

Create a new java class called HandpointDelegate.java and include com.handpoint.api.* as a dependency:

package com.yourpackage.name;

import android.content.Context;

import com.handpoint.api.HandpointCredentials;
import com.handpoint.api.Hapi;
import com.handpoint.api.HapiFactory;
import com.handpoint.api.shared.ConnectionMethod;
import com.handpoint.api.shared.ConnectionStatus;
import com.handpoint.api.shared.Currency;
import com.handpoint.api.shared.Device;
import com.handpoint.api.shared.Events;
import com.handpoint.api.shared.SignatureRequest;
import com.handpoint.api.shared.StatusInfo;
import com.handpoint.api.shared.TipConfiguration;
import com.handpoint.api.shared.TransactionResult;
import com.handpoint.api.shared.agreements.Acquirer;
import com.handpoint.api.shared.agreements.Credential;
import com.handpoint.api.shared.agreements.MerchantAuth;
import com.handpoint.api.shared.options.SaleOptions;

import java.math.BigInteger;
import java.util.Arrays;
import java.util.List;

//Check all the events available in the Events interface.
//If you want to subscribe to more events, just add to the list of implemented interfaces.
public class HandpointDelegate implements Events.Required, Events.ConnectionStatusChanged, Events.CurrentTransactionStatus {

    private Hapi api;

    public HandpointDelegate(Context context) {
        initApi(context);
    }

    public void initApi(Context context) {
        String sharedSecret = "0102030405060708091011121314151617181920212223242526272829303132";
        String merchantApiKey = "This-is-my-api-key-provided-by-Handpoint";
        HandpointCredentials handpointCredentials = new HandpointCredentials(sharedSecret, merchantApiKey);
        this.api = HapiFactory.getAsyncInterface(this, context, handpointCredentials);
        // The api is now initialized. Yay! we've even set default credentials.
        // The shared secret is a unique string shared between the payment terminal and your application, it is a free field.
        // The Api key is a unique key per merchant used to authenticate the terminal against the Cloud.
        // You should replace the API key with the one sent by the Handpoint support team.
        // Now we need to find our device and connect to it.
        discoverDevices();
    }

    // Now  we need to connect to a device to start taking payments.
    // Let's search for them:
    public void discoverDevices(){
        this.api.searchDevices(ConnectionMethod.CLOUD);
        // This triggers the asynchronous search for all the devices around that haven't been paired.

        // You could, alternatively, search for the already paired devices
        // List<Device> devices = this.api.getPairedDevices(ConnectionMethod.CLOUD);
        // Now:
        // selectDeviceAndConnect(devices);
        // You'll receive the devices found through the deviceDiscoveryFinished method.
        // See: https://handpoint.com/docs/device/Android/#elem_eventsDeviceDiscoveryFinished
    }

    @Override
    public void deviceDiscoveryFinished(List<Device> devices) {
        selectDeviceAndConnect(devices);
    }

    private void selectDeviceAndConnect(List<Device> devices) {
        for (Device device : devices) {
            if (device.getName() != null){
                // All the devices here are all of the merchant's devices
                if (/* Fill your logic here */) {
                    this.api.connect(device);
                    // Now take a look at connectionStatusChanged method
                    break;
                }
            }
        }
    }

    //Potentially, if you know the Serial number and model of the device you want to connect to, you can skip the search and do it this way
    public void connect(){
        Device device = new Device("CloudDevice", "9822032398-PAXA920", "", ConnectionMethod.CLOUD);
        //new Device("name", "address", "port", ConnectionMethod.CLOUD);
        this.api.connect(device);
    }

    @Override
    public void connectionStatusChanged(ConnectionStatus status, Device device) {
        if (status == ConnectionStatus.Connected) {
            // Let's launch a payment
            pay();
        }
    }

    public boolean pay() {
        return this.api.sale(new BigInteger("1000"), Currency.GBP);
        // Let´s start our first payment of 10 pounds
    }

    public boolean payWithOptions() {
        SaleOptions options = new SaleOptions();

        // Adding tipping
        TipConfiguration config = new TipConfiguration();
        //Optionally
        config.setHeaderName("HEADER");
        //Optionally
        config.setFooter("FOOTER");
        //Optionally
        config.setEnterAmountEnabled(true);
        //Optionally
        config.setSkipEnabled(true);
        //Optionally
        config.setTipPercentages(Arrays.asList(5, 10, 15, 20));
        options.setTipConfiguration(config);

        // Adding Multi MID / Custom merchant Authentication
        MerchantAuth auth = new MerchantAuth();
        Credential credential = new Credential();
        //Optionally
        credential.setAcquirer(Acquirer.SANDBOX);
        //Optionally
        credential.setMid("mid");
        //Optionally
        credential.setTid("tid");
        //Add as many credentials as Acquirers your merchant have agreements with
        auth.add(credential);
        options.setMerchantAuth(auth);

        //Add a customer reference
        options.setCustomerReference("Your customer reference");

        //Enable pin bypass
        options.setPinBypass(true);

        //Enable signature bypass
        options.setSignatureBypass(true);

        //Define a budget number
        options.setBudgetNumber("YOUR_BUDGET_NUMBER");

        return this.api.sale(new BigInteger("1000"),Currency.GBP, options);
    }

    @Override
    public void currentTransactionStatus(StatusInfo statusInfo, Device device) {
        if (statusInfo.getStatus() == StatusInfo.Status.InitialisationComplete) {
            // The StatusInfo object holds the different transaction statuses like reading card, pin entry, etc.
        }
    }

    @Override
    public void signatureRequired(SignatureRequest signatureRequest, Device device) {
        // This event can be safely ignored for a PAX/Telpo integration. The complete signature capture process
        // is already handled in the sdk, a dialog will prompt the user for a signature if required.
        // If a signature was entered, it should be printed on the receipts.

        //For Datecs integrations:
        // You'll be notified here if a sale process needs a signature verification
        // A signature verification is needed if the cardholder uses an MSR or a chip & signature card
        // This method will not be invoked if a transaction is made with a Chip & PIN card
        // At this step, you are supposed to display the merchant receipt to the cardholder on the android device
        // The cardholder must have the possibility to accept or decline the transaction
        // If the cardholder clicks on decline, the transaction is VOID
        // If the cardholder clicks on accept he is then asked to sign electronically the receipt
        this.api.signatureResult(true);
        // This line means that the cardholder ALWAYS accepts to sign the receipt
        // For this sample app we are not going to implement the whole signature process
    }

    @Override
    public void endOfTransaction(TransactionResult transactionResult, Device device) {
        // The object TransactionResult stores the different receipts
        // Other information can be accessed through this object like the transaction ID, the amount...
    }

    @Override
    public void transactionResultReady(TransactionResult transactionResult, Device device) {
        // Pending TransactionResult objects will be received through this event if the EndOfTransaction
        // event was not delivered during the transaction, for example because of a network issue.
        // For this sample app we are not going to implement this event.
    }

    public void disconnect(){
        this.api.disconnect();
        //This disconnects the connection
    }

}
                

We're done!

Sort of. With the above tutorial you've done a basic integration that can perform sale transactions.

Explore the rest of the documentation to see more transaction types supported and possibilities.