Mobile API

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 to the Eclipse IDE.
1. Download and extract the zip file from the integration 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.

Collapse Using The Library

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.

Collapse End-to-End Encryption

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 ReaderswipeController = 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.    }
}

Collapse Swipe Devices

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.

• void setKey(String key)

  This method takes in the public key and sets it to be used with the encrypt method.

• String encrypt(String plaintext)

  This method accepts a string to be encrypted. Although any string can be passed, the Payment Gateway will only pull fields related to credit cards from the encrypted text.

• String encrypt(PGCard card, boolean includeCVV)

  This is the preferred way of getting the encrypted card data. It will format and encrypt the card data for you to pass on to the gateway.

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.

• enum ReasonUnreadyForSwipe {DISCONNECTED, TIMED_OUT, CANCELED, REFRESHING, SWIPE_DONE }

  Used to explain why the device can no longer accept a swipe.

• enum SwipeDevice { UNIMAG, IPS }

  Used to identify the type of device being used.

• boolean getIsConneced()

  Returns true if the swipe device is connected.

• boolean getIsActivated()

  Returns true if the swipe device is activated.

• boolean getIsReadyForSwipe()

  Returns true if the swipe device is ready.

• SwipeDevice getDeviceType()

  Returns the current device type.

• void setListener(SwipeListener value)

  Sets the event listener.

• boolean setSwipeTimeout(int seconds)

  Sets the timeout interval for the swipe device.

• void setAlwaysAcceptSwipe(boolean alwaysAcceptSwipe)

  True by default, if this is set to false, a swipe must be requested once the device is ready.

• void setActivateReaderOnConnect(boolean activateReaderOnConnect)

  True by default, if this is to false, the device must be activated before it can be used.

• boolean requestSwipe()

  Notifies the reader to start waiting for a swipe. The device must be active before this can be called.

• void cancelSwipeRequest()

  Cancels a swipe request.

• void stopSwipeController()

  Cancels the current swipe request, unregisters the swipe device, and frees resources. Will not receive any information from the device until it is resumed.

• void restartSwipeController()

  Registers the swipe device. Should only be called after calling stopSwipeController()

• String getDefaultMsg()

  Returns the default message for the current device state.

PGSwipeIPS extends PGSwipeDevice

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

• void InitializeReader(Context ctx)

  This class is not intended to be instantiated directly. Instantiate a PGSwipeController instead. The PGSwipeController will create a PGSwipeIPS instance to interact with the IPS device.

PGSwipeUniMag extends PGSwipeDevice

This class handles communication with the IDTECH Unimag device.

• void InitializeReader(Context ctw)

  This class is not intended to be instantiated directly. Instantiate a PGSwipeController instead. The PGSwipeController will create an instance of PGSwipeUniMag to interact with the Shuttle device.

• void updateCompatableDeviceList()

  The UNIMAG device uses an xml compatibility list that consists of specific device settings that are unique to every device. This function should be called to handle new devices.

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.

• void setCVV(String CVV)

  Sets the CVV for the credit card data.

• String getCVV()

  Returns the CVV for the card.

• String getDirectPostString(boolean includeCVV)

  Returns a query string consisting of the card data that can be passed to the Payment Gateway through the Direct Post API.

PGKeyedCard extends PGCard

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

• PGKeyedCard(String ccnumber, String expiration, String cvv)

  The standard constructor for this class. It should be used most of the time.

• PGKeyedCard(String ccnumber, String expiration, String cvv, String startDate, String issueNum)

  This constructor accepts two more values that would be used for Maestro cards.

• void setCardNumber(String value)

  Sets the card number to be used for the current card.

• void setExpirationDate(String value)

  Sets the expiration date to be used for the current card.

• void setCardStartDate(String value)

  Sets the start date for the current card.

• void setCardIssueNumber(String value)

  Sets the issue number for the current card.

• String getCardNumber()

  Returns the current card number.

• String getExpirationDate()

  Returns the current expiration date.

• String getCardStartDate()

  Returns the current start date.

• String getCardIssueNumber()

  Returns the current issue number.

PGSwipedCard extends PGCard

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

• PGSwipedCard(String track1, String track2, String track3, String cvv)

  The constructor that sets the card data accordingly.

• void setTrack1(String value)

  Sets track1 for the current card.

• void setTrack2(String value)

  Sets track2 for the current card.

• void setTrack3(String value)

  Sets track3 for the current card.

• void setMaskedCardNumber(String value)

  Sets the masked card number for the current card.

• void setCardholderName(String value)

  Sets the name on the current card.

• void setExpirationDate(String value)

  Sets the expiration date for the current card.

• String getTrack1()

  Returns the track1 data.

• String getTrack2()

  Returns the track2 data.

• String getTrack3()

  Returns the track3 data.

• String getMaskedCardNumber()

  Returns the masked card number. This should be used when trying to display card information to the user.

• String getCardholderName()

  Returns the name on the card.

• String getExpirationDate()

  Returns the expiration date.

PGEncryptedSwipedCard extends PGSwipedCard

This class should be used for all encrypted swipe devices.

• PGEncryptedSwipedCard(String track1, String track2, String track3, String ksn, String cvv)

  The constructor accepts all class variables.

• void setKsn(String value)

  Sets the KSN that is used to decrypt the card information at the gateway.

• String getKsn()

  Returns the KSN.

PGSwipeController

The PGSwipeController class is used to maintain the swipe device.

• PGSwipeController(Object source, PGSwipeDevice.SwipeDevice deviceType)

  This constructor sets the type of device to be used and initializes it.

• PGSwipeDevice getDevice()

  Returns the device that is currently initialized. Only one should be initialized at a time.

• PGSwipeUniMag getUnimag()

  Can be used instead of getDevice, will produce the same result as long as a UNIMAG device is being used.

• PGSwipeIPS getIPS()

  Can be used instead of getDevice, will produce the same result as long as an IPS device is being used'.

PGSwipeController.SwipeListener

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

• void onSwipedCard(PGSwipedCard card, PGSwipeDevice swipeDevice)

  Method called when a card is swiped. It accepts the card data and the device used.

• void onDeviceReadyForSwipe(PGSwipeDevice swipeDevice)

  Called when the device is ready to read a swipe.

• void onDeviceUnreadyForSwipe(PGSwipeDevice swipeDevice, PGSwipeDevice.ReasonUnreadyForSwipe reason)

  Is called when the device can no longer read a card. It is passed the device and the reason it can no longer accept a swipe.

• void onDeviceConnected(PGSwipeDevice swipeDevice)

  This method is called when the swipe device is connected.

• void onDeviceDisconnected(PGSwipeDevice swipeDevice)

  This method is called when the swipe device is unplugged from the android device.

• void onDeviceActivationFinished(PGSwipeDevice swipeDevice)

  This method is called when a swipe can be requested.

• void onDeviceDeactivated(PGSwipeDevice swipeDevice)

  This method is called when the device is stopped. Once this is called, the device has to be restarted to function again.

Collapse Classes Overview