Android SDK - Mobile App Planning

Paydiant’s Android SDK is a bundled development project that allows our partners to integrate Paydiant’s unique enterprise architecture and managed service into a custom-branded mobile payments application. The SDK provides a simplified front-end of end points that invoke transactional functions through Paydiant’s mobile gateway.

SDK Structure

Paydiant’s mobile payments SDK for the Android operating system is constructed to provide optimum flexibility and simplified programming, while also maximizing performance, functional depth and security for both the underlying platform and the reference application itself.

Each functional module of the SDK is exposed in two option packages:

  • The UI Package is Paydiant’s pre-defined implementation for the Android and contains the underlying Android services and callback mechanisms to streamline development of the reference application.
  • The Core Package is strictly a Java API that does not include any Android-specific classes and is ideal for developers who wish to exhibit more control over the implementation of the SDK.

UI Package

The UI package utilizes the specific Android service protocols for thread management and callback mechanisms. This package provides a bridge between the pure Java methods of the SDK and the Android reference application to streamline development.

The UI package consists of the primary Service package, which is divided into sub-packages consistent with each functional module within the SDK.

Listeners and Adapters

UI package modules are exposed as Android services to allow the service operations to run asynchronously. Callbacks for these asynchronous service operations are defined in listener interfaces provided for each UI package module. All UI package service operations must set the relevant listener (or relevant ListenerAdapter) implementation prior to invoking the module.

Typically, a UI package service contains multiple service operations and the relevant listener defines the corresponding success/failure callbacks. App developers may only use a few of the UI package service operations for an activity, thereby only requiring the relevant callback methods, but since the listener is defined as an interface, app developers must provide implementations for all the callback definitions, regardless of how many are used. To overcome such inefficiency, Paydiant provides a ListenerAdapter alongside the listener.

The ListenerAdapter provides empty implementations for all the callbacks defined in a listener. App developers can override the required callbacks and use the extended ListenerAdapter wherever the listener is used. Refer to the use case examples for modules throughout this guide for code samples of ListenerAdapter implementations.

Note: Paydiant recommends using the ListenerAdapters to optimize SDK version upgrades and avoid compilation issues that could arise if an updated SDK introduces new callback methods that are not defined in the previous Listener interface. ListenerAdapter implementations automatically include all new callbacks upon upgrade.

Core Package

The core package implements a simple Java API that exposes the functionality of the SDK for developers who choose to have a finer level of control over the application’s consumption of each class.

The classes of the core package are divided among four functional package layers, each of which is defined in the following sections.

Facade Package

The facade is the application-facing abstraction layer of the SDK. This layer interfaces directly with the reference application and other outside actors, simplifying the application customization process. Table 1 defines the classes contained in the Façade package.

Facade package class definitions

Class Definition
SecurityManagerFacade This class exposes the functionality related to user and device authentication.
CustomerManagerFacade This class exposes the functionality related to retrieving customer profile information into the application following successful login.
PaymentAccountManagerFacade This class exposes the functionality related to retrieving a logged-in user’s registered payment accounts and corresponding information.
PreferenceManagerFacade This class exposes the functionality that allows a logged-in user to specify application preferences.
TransactionManagerFacade This class exposes the functionality related to processing payment and refund transactions.
ReceiptManagerFacade This class exposes the functionality related to retrieving and displaying a logged-in user’s transaction history.
ImageDownloadManagerFacade This class exposes the functionality that fetches and displays URL-based image bitmaps.
OfferManagerFacade This class exposes the functionality related to retrieving, activating, and removing offers.
UserRegistrationManagerFacade This class exposes the functionality related to registering, validating, and updating consumers.
ApplicationInformationManagerFacade This class exposes functionality related to displaying the terms of service and privacy policy text in the app.

Service Package

The service package classes facilitate communication between the RestTemplate and the mobile gateway for the purpose of transforming data into domain objects that provide the business logic for each use case implemented in the facade layer.

IMPORTANT: The core service package is referenced here to provide a comprehensive view of the SDK architecture, but contains classes that perform internal logic functions within the SDK and are not intended for app developer use. App developers utilizing core classes should ALWAYS use the facade classes.

Exception Package

The exception package contains all the classes that communicate different categories of behavioral exceptions. An exception is thrown by the Core package, but must be handled by the UI package or Application layer, per the developer’s discretion. Table 2 defines the classes contained in the Exception package.

Exception package class definitions

Class Definition
PaydiantException This class implements the abstract base class for Paydiant exceptions from which both PaydiantClientException and PaydiantServiceException classes inherit.
PaydiantClientException This class throws the exceptions specific to errors that occur within the SDK.
PaydiantServiceException This class throws all exceptions specific to errors returned by the mobile gateway.
PaydiantDecodeException This class throws all exceptions specific to errors returned during the checkout code decoding process.

Domain Package

The domain package holds all of the domain objects transformed from data retrieved by the core service package. The domain package runs across all layers and is utilized by both the core and UI components.

Classes in the domain package map directly to domain objects in the mobile gateway and are named accordingly, unless specifically stated otherwise, which is rare.

Mobile App Security Requirements

The Paydiant SDK is a hardened set of libraries designed for secure communication to the Paydiant Managed Service. The SDK leverages an independent module developed specifically by Paydiant for secure, orchestrated network-related operations between the network module and the Paydiant Managed Service.

Your mobile application is required to adhere to the following security requirements designed to maintain the security of the mobile application, consumer personal information, and the Paydiant Managed Service.

Data storage

The mobile application will interact with the consumer and the Paydiant Managed Service (through the SDK). As a cloud-based platform, the goal is store as little information as required on the mobile device and rely on the secure managed services for maintaining confidentiality and integrity of information. Information must be protected appropriately while being used by the mobile application. Data on the mobile device must be protected as outlined in the following table:

Mobile device data protection requirements

Data Types * Card Data (PAN, Expiry, CVV)
* Consumer Password/Passcode
* Consumer Address
* Tokenized Card Data
* Paydiant URI Strings (non-card referencing)
* Consumer Username
* Offer Data
* Loyalty Data
Approved Mobile Storage Locations No permanent mobile storage permitted No permanent mobile storage permitted Any
Storage protection required * Card Data wiped from memory after useful life.
* Login credentials masked on entry.
Purge on app in background Required Not Required Not Required
Purge on session termination Required Required Not Required
Purge on device unlink Required Required Required
Purge on app removal Required Required Required

Unintentional data storage

Data can be captured in a variety of artifacts - many unintended. If data is ever transmitted as query string parameters, as opposed to in the body of a POST request, then these are liable to be logged-in various places - for example, within the user's browser history.

You are required to validate that you have verified the types and protections of data stored in log/debug files, cookies, web history, web cache, property lists, files and SQLite databases.

Secure data entry

Card holder data must be masked upon entry into the mobile device, preferably per-digit. This includes:

  • Credit Card Number
  • Credit Card Expiration Date
  • Credit Card Security Code

If the mobile application enters the background directly from a card holder data entry screen, protections must be in place to ensure that automatic OS-level screenshots cannot capture any card holder data.

The default design should be to mask and/or provide partial (e.g. last 4) card holder data when presenting or storing.

Code Protections

Protecting your application from reverse engineering is a critical step in maintaining the integrity of a services platform. Code obfuscation protects the code base from decompiling and modification using obfuscation algorithms, overlapping checksums injections, flattened code paths, and embeds platform-specific anti-debug and anti-piracy code. Using checksums, digital signatures and other validation mechanisms on files used in the application can help detect whether data files have been tampered with in an attempt to manipulate the application, and can also ensure any data files are authentic by enforcing a signature embedded within the application.

If your application detects that tampering has occurred, it is recommended to notify the end user and log the event to the managed service. You may choose to take more direct action, such as wiping all stored data from memory and terminating any active authenticated sessions.

OWASP Top Mobile Controls

The Open Web Application Security project (OWASP) and the European Network and Information Security Agency (ENISA) collaborated to build a joint set of controls for protecting mobile applications. Mobile applications interacting with the Paydiant Managed Service through the Paydiant SDK must be designed and validated in-line with the current OWASP Top Mobile Controls. As of the writing of this document, those are:

  1. Identify and protect sensitive data on the mobile device.
  2. Handle password credentials securely on the device.
  3. Ensure sensitive data is protected in transit.
  4. Implement user authentication, authorization and session management correctly.
  5. Secure data integration with third party services and applications.
  6. Pay specific attention to the collection and storage of consent for the collection and use of the user's data.
  7. Implement controls to prevent unauthorized access to paid-for resources.
  8. Ensure secure distribution/provisioning of mobile applications.
  9. Carefully check any runtime interpretation of code for errors.

Security Validation

Prior to being certified for use on the Paydiant platform, your mobile application must undergo mobile application security testing from a mutually agreed upon, suitably qualified organization. Paydiant can provide reference contacts at a number of mobile application security testing firms if necessary. If you have an internal team that specializes in mobile security and penetration testing, you may use your own team.

The tested application version must be release candidate quality, with all major features implemented. All major releases and any release that significantly alters the authentication, payment flow, communications or data storage of the mobile application must be validated.

Paydiant will review the output of the testing and any material findings must be mitigated prior to certification and subsequent release to Google Play.

Rooted Devices

Rooted or jailbroken devices pose some additional security risks to user data, however, the negative impact of jailbreak restriction on valid users is much greater than the potential added security benefits against compromised devices.

The majority of financial apps in the market today do not restrict against jailbroken devices. Application developers should always employ best practices in security for sensitive data handling to minimize risk, but we do not recommend preventing users of rooted or jailbroken devices from installing or utilizing mobile wallet applications developed with the Paydiant mobile SDK.