Android Reader SDK

This documentation provides a step-by-step guide for SumUp’s native Android Reader SDK, which enables you to integrate SumUp’s proprietary card terminals and payment platform to accept credit and debit card payments (including VISA, MasterCard, American Express, and more). The SDK communicates with card terminals via Bluetooth (BLE 4.0).

During checkout, the SDK guides users through each payment step with appropriate screens. It also provides terminal setup and cardholder signature verification interfaces. The checkout result is returned with relevant transaction data for your records.

Sensitive card data is never passed to or stored on the merchant’s phone. All data is encrypted by the card terminal, which complies with top industry standards (PCI, EMV I & II, Visa, MasterCard, Amex).

Note

SumUp also provides the Android Tap to Pay SDK as a separate package for handling tap-to-pay payments via smartphone.

Prerequisites

• Registered for a merchant account via SumUp’s country websites (or created a test account)
• Received SumUp card terminal: Solo, Air, Air Lite or PIN+ Terminal
• Generated an Affiliate Key associated with your Application ID found in the build.gradle file.
• Downloaded the Android Reader SDK Repository
• The SDK requires minSdkVersion 26 or later
• The SDK ensures support for
  • targetSDK 31 or later
  • AGP 7.3.0 or later
  • Kotlin version 1.7.21 or later
  • Java 11 and later

Getting a Test Account

To test SumUp APIs without real money involved:

1. Log in to your SumUp account.

2. Open the drop-down menu between Support and your user panel.

3. Select Test Account. Your merchant account is now switched to test mode.

A screenshot of the account selection dropdown in the SumUp dashboard with the test account highlighted with red circle

Once you have your test account you can begin making API calls with real data. Our test accounts do not process transactions with real funds. Test account has a different ID, and shows a clear warning. Processing a request with the value of 11 (in any currency) will always fail deliberately, to enable testing failed transactions.

A screenshot of the dashboard with test account selected

When you’re done experimenting with the test account, switch back to a regular account for business purposes.

Compatibility

Starting with firmware version 1.0.1.84, Air card readers with serial numbers starting with 108, 109 or later require SDK version 4.0.0 and later. Please update to the latest SDK version if you need to support these readers.

Integrate the Android Reader SDK

You can use the sample app provided in the repository as a reference.

Adding Dependencies

1. Add the SumUp maven repository to your Gradle project dependencies build file:

   allprojects {
     repositories {
         maven { url 'https://maven.sumup.com/releases' }
     }
   }

2. Add the SDK dependency to your app module build file:

   implementation 'com.sumup:merchant-sdk:5.0.3'

3. Sync your project.

Initializing SumUp Components

Initialize the SumUp components in your app:

public class SampleApplication extends Application {

  @Override
  public void onCreate() {
    super.onCreate();
    SumUpState.init(this);
  }
}

Logging Merchant In and Out

Before calling any features of the Android Reader SDK, a registered SumUp merchant account needs to be logged in. Log in by supplying your Affiliate Key (create one if necessary):

SumUpLogin sumupLogin = SumUpLogin.builder(mAffiliateKey).build();
SumUpAPI.openLoginActivity(MainActivity.this, sumupLogin, 1);

Login screen

Note

It is also possible to login an account with a token, without the user entering their SumUp login credentials in the SDK. Please refer to section Transparent Authentication

To log Merchant out, call:

SumUpAPI.logout();

Making Payments

After logging in, start accepting card payments. If no account is logged in, an error ERROR_NOT_LOGGED_IN is returned.

Once logged in, you can start using the Android Reader SDK to accept card payments. If no account is logged in, SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN will be returned.

    SumUpPayment payment = SumUpPayment.builder()
            // mandatory parameters
            .total(new BigDecimal("1.12")) // minimum 1.00
            .currency(SumUpPayment.Currency.EUR)
            // optional: to be used only if the card reader supports the feature, what can be checked with `SumUpApi.isTipOnCardReaderAvailable()`
            .tipOnCardReader()
      // optional: include a tip amount in addition to the total, ignored if `tipOnCardReader()` is present
      .tip(new BigDecimal("0.10"))
            // optional: add details
            .title("Taxi Ride")
            .receiptEmail("customer@mail.com")
            .receiptSMS("+3531234567890")
            // optional: Add metadata
            .addAdditionalInfo("AccountId", "taxi0334")
            .addAdditionalInfo("From", "Paris")
            .addAdditionalInfo("To", "Berlin")
            // optional: foreign transaction ID, must be unique!
            .foreignTransactionId(UUID.randomUUID().toString())  // can not exceed 128 chars
      // optional: skip the success screen
      .skipSuccessScreen()
      // optional: skip the failed screen
            .skipFailedScreen()
            .build();

    SumUpAPI.checkout(MainActivity.this, payment, 2);

Payment screen

Handling Payment Result

Override onActivityResult to handle payment results:

   @Override
   protected void onActivityResult(int requestCode, int resultCode, Intent data) {
      if (requestCode == 2 && data != null) {
         // Handle the response here
      }
   }

Connecting Reader

Additional Features

Response Fields

Several response fields are available when the callback activity is called:

Property	Type	Description / Possible Values
SumUpAPI.Response.RESULT_CODE	int	Possible Values: - SUCCESSFUL = 1 - ERROR_TRANSACTION_FAILED = 2 - ERROR_GEOLOCATION_REQUIRED = 3 - ERROR_INVALID_PARAM = 4 - ERROR_INVALID_TOKEN = 5 - ERROR_NO_CONNECTIVITY = 6 - ERROR_PERMISSION_DENIED = 7 - ERROR_NOT_LOGGED_IN = 8 - ERROR_DUPLICATE_FOREIGN_TX_ID = 9 - ERROR_INVALID_AFFILIATE_KEY = 10 - ERROR_ALREADY_LOGGED_IN = 11 - ERROR_INVALID_AMOUNT_DECIMALS = 12 - ERROR_API_LEVEL_TOO_LOW = 13 - ERROR_CARD_READER_SETTINGS_OFF = 14 - ERROR_UNKNOWN_TRANSACTION_STATUS = 15
SumUpAPI.Response.MESSAGE	String	A human readable message describing the result of the payment
SumUpAPI.Response.TX_CODE	String	The transaction code associated with the payment
SumUpAPI.Response.TX_INFO	Parcelable (com.sumup.merchant.Models.TransactionInfo)	Transaction info object containing information about the transaction: - Transaction Code - Merchant Code - Amount (including tip amount and VAT) - Tip amount - VAT - Currency (e.g. EUR) - Payment Status (PENDING | SUCCESSFUL | CANCELLED | FAILED) - Payment Type (CASH | POS | ECOM | UNKNOWN | RECURRING | BITCOIN | BALANCE) - Entry Mode (e.g. CHIP) - Number of Installments - Card Type (e.g. MASTERCARD) - Last four digits of the card - Product information
SumUpAPI.Response.RECEIPT_SENT	boolean	true if a receipt was issued to the customer, false otherwise

The response flags are provided within the Bundle that is passed back to the callback activity:

   int resultCode = getIntent().getExtras().getInt(SumUpAPI.Response.RESULT_CODE);

Card Reader Page

When a merchant is logged in, you can open this activity to access all the settings and options related to the card reader.

• Connect to new readers.
• View the reader attributes when previously connected i.e. Battery percentage, Serial number, Last three digits of serial number, Software version.
• Connect to the last saved reader if it is inactive.
• Update firmware of the reader if available.
• Visual illustration of the saved reader with its current connectivity status and name.

   SumUpAPI.openCardReaderPage(MainActivity.this, 4);

Card Reader Page

Preparing the SumUp Card Terminal for Checkout

prepareForCheckout() offers the possibility to connect the card reader ahead of initiating the checkout which speeds up the overall checkout time.

To call this method, user needs to be logged in with a SumUp account and their card reader should already be setup. Next, call prepareForCheckout() before initiating a checkout.

SumUpAPI.prepareForCheckout()

Note: Air and Solo card readers remain connected via BLE after each transaction while prepareForCheckout() is used when the card reader becomes disconnected (e.g. the reader is out of range, the host app looses focus, or the reader is turned off).

Additional Checkout Parameters

When setting up the SumUpPayment object, the following optional parameters can be included:

Tip Amount

A tip amount can be processed in addition to the total using the tip parameter. The tip amount will then be shown during the checkout process and be included in the response. Please note that a tip amount cannot be changed during/after the checkout.

Tip on Card Reader

This allows the customer to add a tip directly on the card reader, rather than prompting for a tip amount on the Android device.

A tip amount can be prompted directly in the card reader by using tipOnCardReader parameter, if the card reader supports tipping. See example here for the field tipOnCardReader.

Note

Not all card readers support this feature. To find out if the feature is supported for the last-saved card reader, you should always check SumUpApi.isTipOnCardReaderAvailable(). You must handle this case yourself in order to avoid no tip from being prompted. Please also note that if both tip and tipOnCardReader are called then only tipOnCardReader amount will be considered during checkout if available.

Retry Policy Configuration

The configureRetryPolicy() feature allows you to set custom retry parameters for transaction result retrieval, using pollingInterval, maxWaitingTime, and disableBackButton.

• Parameters: Both pollingInterval and maxWaitingTime should be provided in milliseconds, with default values of 2000 ms and 60000 ms, respectively. Setting disableBackButton to true disables the back button during retries.
• Timeout: If maxWaitingTime elapses with no result, the SDK returns SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS. Pressing the back button (if enabled) during retries will also trigger this error.
• Adjustments: If pollingInterval exceeds maxWaitingTime, maxWaitingTime will automatically be adjusted to match. Negative values for either parameter default to 0.
• Default: If configureRetryPolicy() is not used, the SDK defaults to returning SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED.

Querying the Transaction Status

When using the SumUp payment as shown below:

SumupPayment.builder()
...
.foreignTransactionId(UUID.randomUUID().toString())
.configureRetryPolicy(2000, 60000, true)
.build();

If there are connectivity issues and the transaction status can not be retrieved, the API will return ERROR_UNKNOWN_TRANSACTION_STATUS. In such cases, you can query the transaction status by calling SumUp transaction status API using the specified foreignTransactionId.

Transaction Identifier

The foreignTransactionID identifier will be associated with the transaction and can be used to retrieve details related to the transaction. See API documentation for details. Please make sure that this ID is unique within the scope of the SumUp merchant account and sub-accounts. It must not be longer than 128 characters. The foreignTransactionID is available when the callback activity is called: SumUpAPI.Param.FOREIGN_TRANSACTION_ID

Skip Success Screen

To skip the success screen shown at the end of a successful transaction, the skipSuccessScreen parameter can be used. When using this parameter, your application is responsible for displaying the transaction result to the customer. In combination with the Receipts API your application can also send your own receipts, see API documentation for details. Please note success screens will still be shown when using the SumUp Air Lite readers.

Skip Failed Screen

To skip the failed screen shown at the end of a failed transaction, the skipFailedScreen parameter can be used. When using this parameter, your application is responsible for displaying the transaction result to the customer. Please note failed screens will still be shown when using the SumUp Air Lite readers.

Transparent Authentication

To authenticate an account without the user typing in their SumUp credentials each time, you can generate an access token using OAuth2 Authorization Code Flow and use it to transparently log in to the Android Reader SDK.

SumUpLogin sumupLogin = SumUpLogin.builder(mAffiliateKey).accessToken("MY_ACCESS_TOKEN").build();
SumUpAPI.openLoginActivity(MainActivity.this, sumupLogin, 1);

For information about how to obtain a token, please see the Authorization Documentation.

If the token is invalid, SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN is returned.

Retrieve Data of the Active Merchant Account

If a merchant account is currently logged in, it is possible to retrieve the data for this account.

  if (!SumUpAPI.isLoggedIn()) {
    // no merchant account currently logged in
  } else {
    Merchant currentMerchant = SumUpAPI.getCurrentMerchant();
  }

Enable ProGuard

   buildTypes {
        release {
            // All ProGuard rules required by the SumUp SDK are packaged with the library
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt')
        }
    }

Use Google Location Services

The SDK supports Google Location Services, to improve location accuracy and reduce power consumption.

In order to use it you need to add the dependency in build.gradle file

implementation "com.google.android.gms:play-services-location:19.0.1"

If the GLS dependency is not added to the project or Google Play Services are not installed on the mobile device, the Android Reader SDK will determine the location with the default Location Service provided by Android.

Note

Using GLS version 19.0.1 is recommended.

Sample App

SumUp provides a sample app which implements main SDK components. You can find the app under App directory of the repository.

Out of Scope

The following functions are handled by the SumUp APIs:

• Refunds
• Transaction history
• Receipts
• Account management
• Online Payments

Community

• Questions? Get in contact with our integration team by sending an email to integration@sumup.com.
• Found a bug? Open an issue. Please provide as much information as possible.

Changelog

See the SumUp Changelog for updates.

License

See SumUp Android Reader SDK License.