The PayPal Here SDK for Android gives access to a group of PayPal transaction services. It provides an extensive set of point-of-sale functions for merchants. If you're a merchant, you can use it to develop point-of-sale apps for your own use. If you're a third-party solution provider, you can use it to develop point-of-sale software and services which you can offer to your customers.

What's in the PayPal Here SDK for Android

You must have a GitHub account to obtain the SDK files. A free account is sufficient. Once you have joined, you will have access to the SDK distribution's repository. Clone the repository before you begin development.

The GitHub repository for the PayPal Here SDK for Android contains:

  • Object code and other resources for the SDK (in ./SDK/Release/PayPalHereSDK_X.X.arr)
  • Reference (Javadoc) documentation for the SDK. (in ./SDK/docs/apidocs/)
  • The PayPal Here SDK for Android Developer Guide (this online document)
  • Source code for HereSDKSampleApp, which supports card present transactions with EMV cards, using swipers and using both types of readers (in ./samples/HereSDKSampleApp)
  • Source code for a sample mid-tier server that operates with the sample apps. (in ./sample-server/).

How the PayPal Here SDK Works

The PayPal Here SDK for Android is a collection of classes, protocols, and other resources for developing point-of-sale apps that run on Android. It communicates with the underlying PayPal APIs at the following URIs:

https://sandbox.paypal.com/webapps/hereapi/merchant/v1  // Sandbox environment
https://www.paypal.com/webapps/hereapi/merchant/v1      // Live environment

The PayPal Here SDK API is a RESTful interface with the following characteristics:

The workflow

An app must perform these setup operations to prepare to process transactions with the PayPal Here SDK:

  1. Initialize the SDK (each time the app starts).
  2. Authenticate the merchant and pass the merchant's credentials to the SDK (the first time the merchant uses the app).
  3. Set the active merchant, for whom the PayPal Here SDK will execute transactions.
  4. Start monitoring the card reader for events (for card present transactions).

Once the setup operations are complete, an app must perform these steps to process a basic card present transaction:

  1. Start an invoice.
  2. Add items to the invoice.
  3. Take a payment using a credit card reader.
  4. Capture the customer's signature (if required for this merchant and transaction amount).
  5. Send a receipt.

These steps are illustrated in the sample apps, and are described in more detail in Working with the SDK.

Alternative workflows and additional capabilities

The SDK supports several alternatives for the steps in the basic workflow:

  • A fixed-amount transaction instead of starting an invoice and adding items to it
  • A card not present transaction instead of taking and finalizing payment with a card reader
  • Authorization and capture (auth/cap for short), which enables you to authorize a transaction at one point in time and capture payment at a later point. Auth/cap is useful for businesses like restaurants, which must authorize a card payment before the customer determines the final amount by adding a gratuity.

The SDK also supports several additional capabilities:

  • Issuing a refund
  • Adding a referrer code to a transaction
  • Adding a cashier ID to a transaction

All of the alternatives and additions to the basic workflow are described in the Working with the SDK section of this document.

Important classes and interfaces

Understanding the functions and roles of the PayPal Here SDK's most important classes will help you understand the detailed descriptions of how to use the SDK that come later in this guide.

  • PayPalHereSDK: The primary class for interacting with PayPal, and through the CardReaderManager class, with hardware devices.
  • InvoiceItem: Interfaces that represent an invoice and an item in an invoice. Apps generally refer to these interfaces rather than the classes that implement them. The DomainFactory class has methods that construct objects of the appropriate class for an invoice and invoice item, in any given case.
  • DomainFactory: A factory class that creates objects representing invoices, invoice items, and other transaction elements.
  • TransactionManager: An interface that defines a stateful transaction manager, takes payments and processes refunds on the current invoice (if any).
  • CardReaderManager: An interface that defines a card reader manager. Handles interaction with mag stripe and EMV credit card readers, including audio readers, dock port readers, and Bluetooth readers.
  • CardReaderListener: Translates between row card reader events and a delegate interface, and supports multiple listeners.
  • DefaultResponseHandler: A generalized response handler for PayPal Here SDK methods that need one. When you call such a method, you can provide a response handler to it by constructing an instance of DefaultResponseHandlerparam,err, where param is an object to be passed to the handler onSuccess method, and err is an object (customarily an instance of PPError) to be passed to its onError method. You can customize the handler behavior by overriding onSuccess and onError.