Using credit card data

As described in the PayPal Here SDK Overview section, your app can take credit card payments with card data either from a card reader or 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 getAllowedPaymentTypes method of the Merchant class to determine whether the logged-in merchant is approved for PayPal Here.

Example Use Case: Credit Card Reader

After an app initializes the SDK, the app can enable a merchant to take a payment with a credit card reader. The app could use the following steps:

  1. Obtain an instance of TransactionManager and register a TransactionListener object to be notified of status messages related to the payment. The TransactionManager interface is stateful and thus saves data between calls.
  2. Access the CardReaderManager interface and register a CardReaderListener object to be notified of status messages related to the card reader device.
  3. Create a transaction, or "summary of charges", to present to the customer.
  4. Initiate a transaction by calling TransactionManager.beginPayment(). If you specify an amount, the payment is for a fixed amount. If you do not specify an amount, the transaction is based on an invoice.
  5. If necessary, prompt the user to connect a card reader. Use the CardReaderListener object to tell the user when a card can be swiped or inserted. Also notify the user when transaction processing begins, and if necessary, prompt for a signature.
  6. Notify the user when the transaction has been processed.

If your app uses a custom credit card reader, or if you want to otherwise customize the SDK, see Customizing the SDK with a Transaction Controller.

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 create a ManualCardEntry object by calling DomainFactory.newManualEntryCardData():

ManualCardEntry mManualCard =
  DomainFactory.newManualEntryCardData(cardNumber, expirationDate, cvv2);

Each of the parameters is a String.

Validating the card data

Your app should validate the card number, expiration date, and CVV2 before providing the ManualCardEntry object to the SDK.

  • The card number should be between 13 and 19 digits long. Use the Luhn algorithm (also called the mod 10 algorithm) to check the card number.
  • The expiration date must be in the form mmyyyy (for example, 072017 for July 2017), and should be the current or a future date.
  • The CVV2 must be a three-digit number.

Specifying a valid postalCode in the address greatly increases the likelihood that keyed-in data is accepted. To support international cards, the postal code must allow alphanumeric values.

Presenting the card number and date to the user

Your app user interface should automatically present the card number in groups of digits, as is customarily done for the account number printed on a card. American Express cards, whose bank identification numbers (BINs) start with 34 or 37, have 15 digits, should be present in groups of 4, 6, and 5 digits. Most other card numbers have 16 digits, and should be present in four groups of 4 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 with a slash (/) between them.

Detailed Communication with a Credit Card Reader

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 TransactionManager class to take credit card payments without performing this type of detailed communication.

Starting Communication with the Card Reader

The CardReaderManager class handles interactions 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.

Monitoring for card reader connections

To communicate with a card reader, your app must first start listening for a connection to a card reader. You do this by defining a class that extends CardReaderListener, and then registering the listener with the card reader manager:

public class CreditCardPeripheralActivity extends MyActivity implements
TransactionListener,CardReaderListener {
@Override
public void onResume() {
  super.onResume();
  PayPalHereSDK.getCardReaderManager.registerListener(this);
  . . .
}
@Override
public void onPause() {
  super.onResume();
  PayPalHereSDK.getCardReaderManager.unregisterListener(this);
  . . .

Handling card reader notifications

After your app begins monitoring for card readers, the SDK will notify the application as it discovers readers through CardReaderConnectionListener.

Register your application for card reader connection-related events as shown in the following sample:

PayPalHereSDK.getCardReaderManager.registerCardReaderConnectionListener(new CardReaderConnectionListener(){
  //implement all the methods of CardReaderConnectionListener interface..
});

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 Javadoc description of CardReaderConnectionListener & CardReaderListener for details.

Because audio jack readers have batteries in them, be careful about leaving a TransactionManager object open for too long. For information see the TransactionManager class.