PayPal Here IOS SDK

Using credit card data

As described in the PayPal Here SDK Overview section, your app can take credit card payments with card data from a card reader or with card data that is manually keyed in.

Fees for keyed-in data are higher than fees for swipes; see the PayPal Here FAQs for details.

To take credit cards using the SDK, the merchant must be approved for PayPal Here. After authenticating a merchant, but before taking a payment, use the status property of the PPHAccessAccount class to determine whether the logged-in merchant is approved for PayPal Here.

Handling keyed-in card data

If a merchant manually enters data from a credit card, instead of swiping it, the data is keyed-in data, also called card not present data.

When an app accepts keyed-in data, the app must fill in the appropriate fields of a PPHCardNotPresentData object and provide that object to a PPHTransactionManager object to capture the payment. In this case, the required properties of the PPHCardNotPresentData object are:

  • cardNumber
  • expirationDate
  • cvv2

It is recommended to also mask the card data for manual entry, where the previous number is masked (with for example *) after the next number is typed in. Similar to how passwords are entered in many apps.

Although it is not a required property, specifying a valid postalCode property greatly increases the likelihood that keyed-in data will be accepted. To support international cards, the postal code must allow alphanumeric values.

Validating the card data

Your app should validate the card number and date before providing the PPHCardNotPresentData object to the SDK. Note that the SDK handles the date format through the NSDate object, which requires a four-digit year. Your app should validate that the expiration month/year combination is the current month or a future month.

The card number should be between 13 and 19 digits long. Use the standard Luhn algorithm (also called the mod 10 algorithm or the modulus 10 algorithm) to sanity-check the card number.

Presenting the card number and date to the user

Your app user interface should automatically space the card number in groups of four digits as the user enters it. (Note that American Express cards, whose bank identification numbers (BINs) start with 34 or 37, have only 15 digits while most other credit card types have 16 digits. For these numbers, space the number in groups of 4, 6, and 5 digits.)

Present the expiration date to the user as it is printed on a typical card: a two-digit month followed by a two-digit year. Preferably, let the user enter the month and year from a pair of drop-down lists separated by a slash (/).

Accepting a Signature

After your app completes an invoice and receives a card-read notification, but before it pays the invoice, it can capture a signature image. Note that for some merchants and transaction-amounts, the PayPal Here SDK requires a signature before payment.

Use the PPHTransactionManager class finalizePaymentForTransaction method, which finalizes the payment. For additional information, see the SDK Readme file.

[[PayPalHereSDK sharedPaymentProcessor]
    beginCardPresentChargeAttempt: card
        forInvoice: invoice
        withSignature: signatureImage
        completionHandler: ^(PPHCardChargeResponse* response) {
          // if response.error is nil, the charge worked and you can store
          // the response.transactionId for correlation later (and refunds),
        }
];

Detailed Communication with a Credit Card Reader

The PayPalHereSDK allows more granular control over magstripe card readers. These options are not available for EMV readers. This section is an overview of how an app uses the SDK for detailed communication with a credit card reader. "Detailed communication" means that the app controls individual card reader operations, rather than simply asking the SDK to read a card.

Note: Your app can use the PPHTransactionManager class to take credit card payments, without this type of detailed communication. It is mandatory to use PPHTransactionManager for EMV payments.

Card Reader Manager

The PPHCardReaderManager class handles all interaction with all types of credit card readers, including audio readers, dock port readers, and Bluetooth readers. It handles readers for both mag stripe and EMV cards. You can access a singleton of this class through the PayPalHereSDK Class.

Reader Lifecycle

To begin searching for readers, use the beginMonitoring API and either provide a mask of the reader types that you want to support, or issue a request without parameters to search for all reader types.

Note: The SDK uses high-volume audio tones to communicate with audio readers. Therefore, your app should confirm that a user is not likely to have head phones plugged into the audio jack when your app starts monitoring for card readers.

After a monitored reader type is detected, it goes through four states during its lifecycle:

  • Available - A potential reader of one of the monitored types has been detected.
  • Connecting - We are in the process of acquiring more information about the reader.
  • Connected - The reader is fully identified.
  • Open - The reader is listening for card data.

Additionally PPHCardReaderManager has the concept of an activeReader, which is the reader currently enabled to take payments. The active reader is chosen automatically in situations where there is no ambiguity, but in multiple-reader scenarios, you may be required to set it yourself.

Note: Your app should have permission to access the user's GPS coordinates from Apple's location services before you activate a reader because activation requires access to the GPS coordinates of the device.

A device in the open state may use more of its battery than it would otherwise, so it is recommended that you only keep a device open for the duration you expect a user to interact with it.

Handling card reader notifications

After your app begins monitoring for card readers, the SDK will fire notification center events as it discovers readers.

Rather than monitor the notification center directly, you should make use of the protocol that translates untyped notification center calls into typed delegate calls. Simply store an instance of PPHCardReaderWatcher in your view controller class and make the class implement the PPHCardReaderDelegate protocol:

self.readerWatcher =  [[PPHCardReaderWatcher alloc] initWithDelegate: self];

Your app will be notified when the SDK starts monitoring for card readers, when a card reader is connected or removed, when card reader metadata is received, and when a card swipe (or EMV equivalent) is attempted, completed, and failed. See the description of PPHCardReaderWatcher for details.