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:
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.
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.
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.
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" />
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. }
}
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.
This method takes in the public key and sets it to be used with the encrypt method.
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.
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.
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.
Used to explain why the device can no longer accept a swipe.
Used to identify the type of device being used.
Returns true if the swipe device is connected.
Returns true if the swipe device is activated.
Returns true if the swipe device is ready.
Returns the current device type.
Sets the event listener.
Sets the timeout interval for the swipe device.
True by default, if this is set to false, a swipe must be requested once the device is ready.
True by default, if this is to false, the device must be activated before it can be used.
Notifies the reader to start waiting for a swipe. The device must be active before this can be called.
Cancels a swipe request.
Cancels the current swipe request, unregisters the swipe device, and frees resources. Will not receive any information from the device until it is resumed.
Registers the swipe device. Should only be called after calling stopSwipeController()
Returns the default message for the current device state.
This class handles communications with the iPS Encrypted Mobile Card Reader.
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.
This class handles communication with the IDTECH Unimag device.
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.
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.
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.
Sets the CVV for the credit card data.
Returns the CVV for the card.
Returns a query string consisting of the card data that can be passed to the Payment Gateway through the Direct Post API.
This class should be used when accepting credit card information from a keyboard.
The standard constructor for this class. It should be used most of the time.
This constructor accepts two more values that would be used for Maestro cards.
Sets the card number to be used for the current card.
Sets the expiration date to be used for the current card.
Sets the start date for the current card.
Sets the issue number for the current card.
Returns the current card number.
Returns the current expiration date.
Returns the current start date.
Returns the current issue number.
This class should only be used along with an unencrypted swipe device.
The constructor that sets the card data accordingly.
Sets track1 for the current card.
Sets track2 for the current card.
Sets track3 for the current card.
Sets the masked card number for the current card.
Sets the name on the current card.
Sets the expiration date for the current card.
Returns the track1 data.
Returns the track2 data.
Returns the track3 data.
Returns the masked card number. This should be used when trying to display card information to the user.
Returns the name on the card.
Returns the expiration date.
This class should be used for all encrypted swipe devices.
The constructor accepts all class variables.
Sets the KSN that is used to decrypt the card information at the gateway.
Returns the KSN.
The PGSwipeController class is used to maintain the swipe device.
This constructor sets the type of device to be used and initializes it.
Returns the device that is currently initialized. Only one should be initialized at a time.
Can be used instead of getDevice, will produce the same result as long as a UNIMAG device is being used.
Can be used instead of getDevice, will produce the same result as long as an IPS device is being used'.
This interface must be implemented in order to receive events from the card readers
Method called when a card is swiped. It accepts the card data and the device used.
Called when the device is ready to read a swipe.
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.
This method is called when the swipe device is connected.
This method is called when the swipe device is unplugged from the android device.
This method is called when a swipe can be requested.
This method is called when the device is stopped. Once this is called, the device has to be restarted to function again.
Apply for a Merchant Account
Signup for the Payment Gateway
An Internet Merchant Account is sometimes referred to as a "MOTO" (Mail Order & Telephone Order) Account because they all require the ability to process a credit card payment when there is no physical credit card present to be swiped. A standard retail "swipe" merchant account does not allow processing of these "card-not-present" transactions.
If the domestic banks are denying your merchant application because they believe your industry is considered high risk, CyoGate can help! We have an offshore network of merchant processing partners that enable us to provide low cost, high risk merchant solutions to a much wider range of businesses and industries.
The CyoGate Internet Payment Gateway offers one of the quickest and most cost effective ways to accept and process credit card and electronic check payments online. Our payment gateway works with most existing merchant accounts and supports hundreds of popular web shopping carts and eCommerce platforms.