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.
- Download and extract the zip file from the integraton section of the Payment Gateway.
- In eclipse, select File->New->Project.
- Import the SDK
- Right click on the libs directory in the new project, and select Import.
- Select File System underneath General, and click next.
- For the directory, click browse and inside of the extracted folder from before, select Payment Gateway Mobile SDK.
- Select all three Jar files and click finish.
- Add SDK files to build path.
- Right click on the imported files and select Build Path->Add to Build Path.
- Right click on the project and select Build Path->Configure Build Path...
- In the Order and Export tab, select the SDK files.
- 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
-
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.
-
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.
- 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. Even though, any string can be passed, the Payment Gateway will only pull fields related to credit cards from the encrypted text.
- String encrypt(PGCard car, boolean includeCVV)
This is the prefered 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 communcations with the iPS Encrypted Mobile Card Reader.
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 a instance of PGSwipeUniMag to interact with the Shuttle device.
- void updateCompatableDeviceList()
The UNIMAG device uses an xml compatability 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.
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 cna 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.