Methodology

Overview

There are two parts to the Mobile APIs, the end-to-end encryption method and the swipe device library.

End-to-End Encryption

The end-to-end encryption library allows credit card data to be encrypted on a mobile device before sending it to the Merchant's back-end server. During the sale process, the Merchant's server can send the encrypted card data to the Payment Gateway, where it is decrypted and treated like a normal credit card. This gives the merchant more control of mobile transactions without having to increase compliancy costs.

The merchant's encryption key is an RSA public key that is unique to them. This means that the encrypted credit card data will only be able to be used to make a transaction in that merchant's payment gateway account. Only the Payment Gateway has access to the private key that corresponds to this public key.

Card data is encrypted using AES encryption with a new randomly generated key for every card. This key is then encrypted with the public key along with the card data. This packet(the encrypted card and AES key) is unreadable to anybody without the private key which is only known to the Payment Gateway.

Note: The public key can NOT be used to decrpt an encrypted card. Once encrypted, the card is unusable except by the Gateway when it processes the payment for the merchant. For this reason, there is no need to keep the public key a secret.

Swipe Device Library

This library supports the encrypted card readers supported by the payment gateway. This includes parsing the data and notifying you when a card reader is connected, disconnected, ready, etc...

Using the Library
Mobile API: Android

Creating a Project

The fastest way to get started is to check out the Client Encryption Example project that can be downloaded from the downloads section. Or if you prefer to create your own project, use these steps:

    These directions are specific for the eclipse ide.
  1. Download and extract the zip file from the integraton section of the Payment Gateway.
  2. In eclipse, select File->New->Project.
  3. Import the SDK
    1. Right click on the libs directory in the new project, and select Import.
    2. Select File System underneath General, and click next.
    3. For the directory, click browse and inside of the extracted folder from before, select Payment Gateway Mobile SDK.
    4. Select all three Jar files and click finish.
  4. Add SDK files to build path.
    1. Right click on the imported files and select Build Path->Add to Build Path.
    2. Right click on the project and select Build Path->Configure Build Path...
    3. In the Order and Export tab, select the SDK files.
    4. Click OK.

Network Usage Note

You may notice the library attempting to connect to IDTECH's website to download a file. Since the audio jack capabilities of different Android devices vary, the IDTECH Shuttle's library uses different communication settings for each supported device. IDTECH frequently updates a list of the supported devices and the communication settings for each which the library may attempt to download from IDTECH. Internet permission is required.

End-to-End Encryption
Mobile API: Android

Acquiring a Public Key

  1. After logging into the Payment Gateway, navigate to Settings->Security Keys->View Mobile SDK Key. You can click on the Java example button to get a version that can easily be copied and pasted into your project.

  2. Use the Query API. In order to get the public key, you will need to use 'report_type=sdk_key'. The key will be returned in the <sdk_key> tag.

Encrypting a Card

The following is an example of the entire encryption process:

import com.SafeWebServices.PaymentGateway.PGEncrypt;

PGEncrypt pg = new PGEncrypt();
Pg. setKey(
    "***999|MIIEEjCCA3ugAwIBAgIBADANBgkqhkiG9w0BAQQFADCBvTELMAkGA1UEBh"
    "MCVVMxETAPBgNVBAgTCElsbGlub2lzMRMwEQYDVQQHEwpTY2hhdW1idXJnMRgwFg"
                    [Several lines omitted]
    "cNAQEEBQADgYEAKY8xYc91ESNeXZYTVxEsFA9twZDpRjSKShDCcbutgPlC0XcHUt"
    "a2MfFPsdgQoq0I8y1nEn1qJiOuEG1t9Uwux4GAvAPzsWSsKyKQkZhqxrxkJUB39K"
    "Pg57pPytfJnlQTgYiSrycCEVHdDvhk92X7K2cab3aVV1+j0rKlR/Sy6b4=***");


PGKeyedCard cardData = new PGKeyedCard(cardNumber, expiration, cvv);
Boolean includeCVV = true;
String encryptedCardData = pg.encrypt(cardData, includeCVV);

In this example, 'encryptedCardData' would now contain a string that can be passed to the Payment Gateway in place of credit card information. The parameter name to use when passing this value is 'encrypted_payment'.

For example, a simple DirectPost API string would look something like this:

(This example assumes your Merchant server is running a PHP script that has received the encrypted card data through a POST parameter called 'cardData'.)


//Business logic, validation, etc.  When ready to process the payment...

$cardData = $_POST['cardData'];
$postString = "username=demo&password=1234&type=sale&amount=1.00&encrypted_payment=$cardData";

//Post to Gateway
            

We suggest using POST instead of GET to reduce the possibility of the data being kept in a log file. For more information on how to communicate with the Payment Gateway, see the API documentation.

s

Swipe Devices
Mobile API: Android

Permissions

You will need to grant the application multiple permissions in order to use a swipe device. This can be done by modifying the manifest file by adding:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET" />

Creating the Controller

In the class that intends to handle swipe events, add a PGSwipeController property called swipeController, and then in your init function, initialize the object with this line:

//This example is for the iPS Encrypted Mobile Card Reader
swipeController = new PGSwipeController(this, PGSwipeDevice.SwipeDevice.IPS);

If you want to change the default settings, you can change them now. Here are some examples:

swipeController.getDevice().setSwipeTimeout(30);
swipeController.getDevice().setAlwaysAcceptSwipe(false);
swipeController.getDevice().setActivateReaderOnConnect(false);

Your class will have to implement the PGSwipeListener protocol. If you are only interested in knowing when a card is swiped, you can safely leave every other event handler empty, as shown here (or add your own code to, for example, display an image indicating that the swipe reader is ready for a swipe). In this example, when the swipe is received, the card data is saved in a property (swipedCard) for eventual transmission to the Gateway (not shown), and two TextView variables (cardNumberField and expirationField) are set to show the masked card number and expiration date. If a bad swipe occurs, onSwipedCard is still called, but "card" will be null.

@Override
public void onDeviceConnected(final PGSwipeDevice device)
{
}
@Override
Public void onDeviceDisconnected(final PGSwipeDevice device)
{
}

@Override
public void onDeviceActivationFinished(final PGSwipeDevice device)
{
}
@Override
public void onDeviceDeactivated(final PGSwipeDevice device)
{
}
@Override
public void onDeviceReadyForSwipe(final PGSwipeDevice device)
{
}
@Override
public void onDeviceUnreadyForSwipe(final PGSwipeDevice device,
    PGSwipeDevice.ReasonUnreadyForSwipe reason)
{
}
@Override
public void onSwipedCard(final PGSwipedCard card, final PGSwipeDevice device)
{
    if (card != null) {
      this.runOnUiThread(new Runnable() {
      public void run() {
          TextView cardNumberField = (TextView)findViewById(R.id.cardNumber);
        cardNumberField.setText((CharSequence)card.getMaskedCardNumber());
        }
      }
    } else {
        //A null card means that there was a swipe but it was unsuccessful.
    }
}

Classes Overview
Mobile API: Android

PGEncrypt

The PGEncrypt class contains all necessary to encrypt data to be sent to the payment gateway. Merchants wanting to send transaction data to their servers before processing the transaction will want to use this method in order to prevent their server from touching sensitive data.

PGSwipeDevice

This class represents the functionality that is common to the swipe reader devices. A PGSwipeDevice object is passed along with every even generated by the devices in order to identify the device type and access device_specific features by casting it to the specific swipe device.

PGSwipeIPS extends PGSwipeDevice

This class handles communcations with the iPS Encrypted Mobile Card Reader.

PGSwipeUniMag extends PGSwipeDevice

This class handles communication with the IDTECH Unimag device.

PGCard

This is a simple base class for the different types of cards that can be used. There is no reason to ever explicitly declare this.

PGKeyedCard extends PGCard

This class should be used when accepting credit card information from a keyboard.

PGSwipedCard extends PGCard

This class should only be used along with an unencrypted swipe device.

PGEncryptedSwipedCard extends PGSwipedCard

This class should be used for all encrypted swipe devices.

PGSwipeController

The PGSwipeController class is used to maintain the swipe device.

PGSwipeController.SwipeListener

This interface must be implemented in order to receive events from the card readers