The PayPal Here SDK for iOS provides access to a group of PayPal transaction services which contain 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 iOS

You must have a GitHub account to obtain the SDK files. A free account is sufficient. After you join, you can access the SDK distribution's repository. You must clone the repository before you begin development.

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

  • Object code and other resources for the SDK. (in ./SDK/Release/)
  • Reference (Appledoc) documentation for the SDK. (in ./SDK/html/)
  • Source code for the TakePayment sample app. (in ./TakePayment/)

The SDK's place in PayPal's family of products

The PayPal Here SDK for iOS is a collection of classes, protocols, and other resources for developing point-of-sale apps that run in iOS. 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 workflow

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

  • Initialize the SDK (each time the app starts).
  • Authenticate the merchant and pass the merchant's credentials to the SDK (the first time the merchant uses the app).
  • Set the active merchant, for whom the PayPal Here SDK executes transactions.
  • 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:

  1. It supports a fixed-amount transaction instead of starting an invoice and adding items to it.
  2. It supports a card not present (manual entry) transaction instead of taking and finalizing payment with a card reader.
  3. It supporst 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 later in the Using credit card data section of this document.

Important classes

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

  • PayPalHereSDK: The primary class for interacting with PayPal, and through the PPHCardReaderManager class, with hardware devices.
  • PPHPaymentProcessor: Captures payments. Supports card swipes and chip and PIN data for card present transactions, and keyed-in data for card not present transactions.
  • PPHTransactionManager: A stateful transaction processor class; takes payments and processes refunds on the current invoice (if any).
  • PPHCardReaderManager: Handles interaction with mag stripe and EMV credit card readers, including audio readers, dock port readers, and Bluetooth readers.
  • PPHCardReaderWatcher: Translates between row card reader events and a delegate interface, and supports multiple watchers.