SeamlessPay Android

The Seamless Payments Android SDK makes it quick and easy to build an excellent payment experience in your Android app 🤖

Overview

SeamlessPay Android provides drop-in customizable UI elements that can be used to collect your users' payment details and process payments from within your app. We also expose the low-level APIs that power those UIs so that you can build fully custom experiences.

There are several components that comprise this SDK:

• Client provides the networking, communication and modeling layer
• CardForm provides a drop-in UI for collecting payment information in your app
• Singlefield provides an advanced drop-in UI that uses a single input

The individual components may be used for advanced integrations and are available as modules in maven.

Package	Description
api	Seamless Payments API Client for Android
card-form	UI component for card input using a traditional form layout
singlefield	UI component for card input using a single-field widget

Get started with our 📚 integration guide and example projects.

Installation

Your development environment must have minimum requirements configured:

Requirements

• Java 8 is installed and available in your PATH
• Android Studio
• Gradle 5.4.1+
• Android SDK >= 21 - If you do not have the Android SDK installed, run ./gradlew build 3 times to download the Android SDK and install all required tools as well as set your local.properties file (we use sdk-manager-plugin to do this automatically).

Note: If you do have the Android SDK installed, add a local.properties file to the top level directory with sdk.dir=/path/to/your/sdk/.android-sdk

Once your environment is configured, add the SeamlessPay Android SDK to your project using your preferred repository, for example:

Gradle

Add the required dependencies to your project's build.gradle:

dependencies {
  /* API Client */
  implementation 'com.seamlesspay.api:Client:[VERSION]'

  /* Card Form UI */
  implementation 'com.seamlesspay.sdk:CardForm:[VERSION]'

  /* Single Field UI */
  implementation 'com.seamlesspay.ui:Singlefield:[VERSION]'
}

Note: Be sure to replace [VERSION] with the correct semantic version of package.

Maven

Add the required dependencies to your project's pom.xml:

<!-- API Client -->
<dependency>
	<groupId>com.seamlesspay.api</groupId>
	<artifactId>Client</artifactId>
	<version>[VERSION]</version>
	<type>pom</type>
</dependency>

<!-- Card Form UI -->
<dependency>
	<groupId>com.seamlesspay.sdk</groupId>
	<artifactId>CardForm</artifactId>
	<version>[VERSION]</version>
	<type>pom</type>
</dependency>

<!-- Single Field UI -->
<dependency>
	<groupId>com.seamlesspay.ui</groupId>
	<artifactId>Singlefield</artifactId>
	<version>[VERSION]</version>
	<type>pom</type>
</dependency>

Note: Be sure to replace [VERSION] with the correct semantic version of package.

Apache Ivy

Add the required dependencies to your project's ivy.xml:

<!-- API Client -->
<dependency org="com.seamlesspay.api" name="Client" rev="[VERSION]">
	<artifact name="Client" ext="pom"></artifact>
</dependency>

<!-- Card Form UI -->
<dependency org="com.seamlesspay.sdk" name="CardForm" rev="[VERSION]">
	<artifact name="CardForm" ext="pom"></artifact>
</dependency>

<!-- Single Field UI -->
<dependency org="com.seamlesspay.ui" name="Singlefield" rev="[VERSION]">
	<artifact name="Singlefield" ext="pom"></artifact>
</dependency>

Note: Be sure to replace [VERSION] with the correct semantic version of package.

In most cases, you will only need to install the api and one of the UI packages, either card-form or singlefield.

UI Components

We provide several drop-in native UI components for easily collecting payment information in your Android Application:

CardForm Component

The CardForm Component is a drop-in UI layout that can be included in your app making it easy to accept credit and debit cards.

Usage & Example

CardForm is a LinearLayout widget that you can easily add to your app:

<com.seamlesspay.cardform.view.CardForm
  android:id="@+id/card_form"
  android:layout_width="match_parent"
  android:layout_height="match_parent" />

To initialize the view and change which fields are required for the user to enter, use the required field methods and CardForm#setup(AppCompatActivity activity):

CardForm cardForm = (CardForm) findViewById(R.id.card_form);
cardForm.cardRequired(true)
  .expirationRequired(true)
  .cvvRequired(true)
  .postalCodeRequired(true)
  .mobileNumberRequired(false)
  .actionLabel(getString(R.string.purchase))
  .setup(activity);

CardForm API

The CardForm instance exposes several helper methods:

• isValid(): Checks if CardForm input is valid
• validate(): Validates each required field, shows validation errors
• setCardNumberError(String): Sets a custom error messages on given field

Additionally CardForm has 4 available event listeners:

• setOnCardFormValidListener: CardForm validation has changed state
• setOnCardFormSubmitListener: Called when CardForm should be submitted
• setOnFormFieldFocusedListener: A field in the form was focused
• setOnCardTypeChangedListener: The CardType has changed

CardForm Demo

Start with the provided Demo App for an example of basic setup and usage of CardForm.

Single Field Input

The Singlefield Input is a drop-in UI layout that can be included in your app which uses a single input field to accept account information.

Usage & Example

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
  xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  app:layout_behavior="@string/appbar_scrolling_view_behavior"
  tools:showIn="@layout/activity_checkout"
  tools:context=".CardActivity">

  <!--  ...  -->

  <com.seamlesspay.ui.view.CardInputWidget
    android:id="@+id/cardInputWidget"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginLeft="20dp"
    android:layout_marginRight="20dp"/>

  <Button
    android:text="Pay"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/payButton"
    android:layout_marginTop="20dp"
    app:layout_constraintTop_toBottomOf="@+id/cardInputWidget"
    app:layout_constraintStart_toStartOf="@+id/cardInputWidget"
    app:layout_constraintEnd_toEndOf="@+id/cardInputWidget"/>

  <!--  ...  -->

</androidx.constraintlayout.widget.ConstraintLayout>

To access the values in the form, use provided getters for each field:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  setContentView(R.layout.activity_main);

  Button payButton = findViewById(R.id.payButton);

  mCardInputWidget = (CardInputWidget) findViewById(R.id.cardInputWidget);
  mCardInputWidget.configureForUs();

  payButton.setOnClickListener(new View.OnClickListener() {
    public void onClick(View v) {
      // Executes on main thread after user presses button
      mCardInputWidget.clearFocus();

      CardBuilder cardBuilder = new CardBuilder()
        .accountNumber(mCardInputWidget.getCardNumber())
        .expirationMonth(mCardInputWidget.getExpirationMonth())
        .expirationYear(mCardInputWidget.getExpirationYear())
        .setTxnType(CardBuilder.Keys.CREDIT_CARD_TYPE)
        .billingZip(mCardInputWidget.getPostalCode())
        .cvv(mCardInputWidget.getCvv())
        .verification(true);

      PanVault.tokenize(mSeamlesspayFragment, cardBuilder);
    }
  });

  // ...

Singlefield Demo

Start with the provided demo DemoSinglefield App for a working example with basic setup and usage.

Authorization

To authenticate requests, use Authorization#fromKeys() with your environment and publishable_key to generate credentials.

Example & API

Example

import com.seamlesspay.api.SeamlesspayFragment;
import com.seamlesspay.api.Authorization;

public class CardActivity { // ...

  Authorization authorization = Authorization.fromKeys(
    "sandbox",                        // environment
    "pk_XXXXXXXXXXXXXXXXXXXXXXXXXX"   // publishable_key
  );

  mSeamlesspayFragment = SeamlesspayFragment.newInstance(this, authorization);

API

• fromKeys(environment, publishable_key): Creates authorization credentials

PAN Vault

The PAN Vault is a way to store payment instruments for future use while remaining outside the scope of PCI. Use PanVault to create a token with given payment data.

Example & API

Example

CardBuilder cardBuilder = new CardBuilder()
  .accountNumber(mCardForm.getCardNumber())
  .expirationMonth(mCardForm.getExpirationMonth())
  .expirationYear(mCardForm.getExpirationYear())
  .setTxnType(CardBuilder.Keys.CREDIT_CARD_TYPE)
  .billingZip(mCardForm.getPostalCode())
  .cvv(mCardForm.getCvv())
  .verification(true);

PanVault.tokenize(mSeamlesspayFragment, cardBuilder);

API

• PanVault.tokenize(mSeamlesspayFragment, cardBuilder): Creates a reusable token

Available listeners:

• PaymentMethodTokenCreatedListener: A PaymentMethodToken has been created

Charge

Create a Charge (payment transaction) using a token from PanVault:

Example & API

Example

CardChargeBulder chargeBulder = new CardChargeBulder()
  .setAmount("1")
  .setCurrency(CardChargeBulder.Keys.CURRENCY_USD)
  .setCapture(true)
  .setToken(token.getToken())
  .setDescription("Demo Android Client Charge")
  .setCvv(mCardForm.getCvv());

Charge.create(mSeamlesspayFragment, chargeBulder);

Charge API

• Charge.create(mSeamlesspayFragment, chargeBulder): Creates a charge using provided data

Available listeners:

• BaseChargeTokenCreatedListener: A chargeToken was successfully created

Card Scanning

The CardForm UI component is compatible with card.io, which allows users to input card information using their phone's camera. For more information, please refer to the github repository and docs for card.io-Android-SDK.

Usage & API

Usage

To use card.io, add the dependency to your build.gradle:

dependencies {
  api 'io.card:android-sdk:[5.5.0,6.0.0]'
}

CardForm API for card.io

• cardForm.isCardScanningAvailable(): Is card.io is available for use
• cardForm.scanCard(activity): Initiates a card scan on device

Example Apps

The SeamlessPay Android SDK comes bundled with the following demo apps:

• CardForm: Basic setup and usage of API Client & CardForm
• Singlefield: Setup and usage of Singlefield UI

Run ./gradlew :Demo:installDebug to install the Demo app on a device.

Feedback

The SeamlessPay Android SDK is in active development, we welcome your feedback!

Here are a few ways to get in touch:

• GitHub Issues - For generally applicable issues and feedback
• SeamlessPay Portal / support@seamlesspay.com - for personal support at any phase of integration

Help

• Read the docs 📚
• Find a bug? Open an issue 🐛
• Want to contribute? Check out contributing guidelines and submit a pull request.