Methodology
Mobile API
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 to receive a swipe, etc.
Using the Library
Mobile API: iOS
Creating a Project
The fastest way to get started is to check out the PaymentGatewayEncryptionExample and PaymentGatewaySwipeExample
projects that can be downloaded from the Payment Gateway's Integration section.
If you prefer to create your own project instead, use these steps (current as of Xcode 4.5):
- Download the PaymentGatewayMobileSDK.zip file from the Integration section on the Payment Gateway.
- Create a new Xcode Project.
- Copy the files in the .zip file (PGMobileSDK.a and the folder PGMobileSDK containing the headers)
into your project folder, and add them to your Xcode project.
- Add the following frameworks to your project:
- AudioToolbox.framework
- AVFoundation.framework
- ExternalAccessory.framework
- MediaPlayer.framework
- Security.framework
- (Optional - see note below) - In your Info.plist, add a row for "Supported external accessory protocols",
and add "com.gatewayprocessingservices.iprocess" as Item 0.
This enables connection to the iDynamo swipe reader.
Note: You may wish to skip step 5 if you do not need to support the iDynamo.
Apple requires manufacturers of accessories that use the dock connector to add your app
to their product plan before approving your app for the app store. You will need to contact
MagTek in order to have your app added to their product plan. See the MagTek iDynamo Software
Submission Request Form here:
http://www.magtek.com/documentation/public/99800121-1.01.pdf
Viewing documentation in Xcode
Adding the doc set to Xcode allows the most up-to-date, relevant documentation to appear in the IDE as you type.
To enable access to the SDK documentation from inside Xcode:
- Under the Xcode menu, click Preferences
- Navigate to the Downloads page
- On the Documentation tab, click Add.
- On the "Enter a doc set feed URL" window that pops up, enter:
https://secure.safewebservices.com/merchants/resources/integration/docset/iOSSDK.atom
- Click Add
- Click the newly-added install button
Important Info About the App Store
The Apple App Store's current policy is to require mobile apps to purchase digital goods (e.g. downloadable content, etc.)
through the App Store. For that reason, this SDK is intended only for use in apps selling real-world goods and services.
Please direct questions about Apple's App Store policies to Apple. Their policies are subject to change at their discretion.
End-to-End Encryption
Mobile API: iOS
Acquiring a Public Key
-
After logging into the Payment Gateway, navigate to Settings->Security Keys->View Mobile SDK Key.
You can click on the Objective-C example link 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
#import "PGEncrypt.h"
#import "PGCards.h"
PGEncrypt encryption = [[PGEncrypt alloc] init];
[encryption setKey:
@"***999|MIIEEjCCA3ugAwIBAgIBADANBgkqhkiG9w0BAQQFADCBvTELMAkGA1UEBh"
"MCVVMxETAPBgNVBAgTCElsbGlub2lzMRMwEQYDVQQHEwpTY2hhdW1idXJnMRgwFg"
[Several lines omitted]
"cNAQEEBQADgYEAKY8xYc91ESNeXZYTVxEsFA9twZDpRjSKShDCcbutgPlC0XcHUt"
"a2MfFPsdgQoq0I8y1nEn1qJiOuEG1t9Uwux4GAvAPzsWSsKyKQkZhqxrxkJUB39K"
"Pg57pPytfJnlQTgYiSrycCEVHdDvhk92X7K2cab3aVV1+j0rKlR/Sy6b4=***"];
PGCard *cardData = [[PGKeyedCard alloc] initWithCardNumber:cardNumberField.text
expirationDate:expirationField.text
cvv:cvvField.text];
NSString *encryptedCardData = [encryption encrypt:cardData includeCVV:NO];
encryptedCardData will 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 through DirectPost 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
For more information on how to communicate with the Payment Gateway, see the API documentation.
Swipe Devices
Mobile API: iOS
Creating the Controller
In the class that intends to handle swipe events, create a PGSwipeController object in your init method.
Initialize the object with this line to support Shuttle readers:
swipeController = [[PGSwipeController alloc] initWithDelegate:self audioReader:AudioJackReaderUnimag];
or for the IPS Encrypted Card Reader:
swipeController = [[PGSwipeController alloc] initWithDelegate:self audioReader:AudioJackReaderIps];
Only a single model of audio jack-connected reader can be enabled at a time. The audioReader parameter allows you to
choose which type, UniMag (Shuttle) or IPS Encrypted Card Reader, you want to allow.
See the PGSwipeController's initWithDelegate:audioReader: documentation for more details.
Your class will have to implement the PGSwipeDelegate 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 UITextField properties
(cardNumberField and expirationField) are set to show the masked card number and expiration date.
If a bad swipe occurs, didSwipeCard:device: may still be called, but "card" will be nil.
An error message is displayed in this example. Note: Not all card reader models give feedback when a bad swipe is received.
-(void)deviceConnected:(PGSwipeDevice *)sender
{
}
-(void)deviceDisconnected:(PGSwipeDevice *)sender
{
}
-(void)deviceActivationFinished:(PGSwipeDevice *)sender result:(SwipeActivationResult)result
{
}
-(void)deviceDeactivated:(PGSwipeDevice *)sender
{
}
-(void)deviceBecameReadyForSwipe:(PGSwipeDevice *)sender
{
}
-(void)deviceBecameUnreadyForSwipe:(PGSwipeDevice *)sender reason:(SwipeReasonUnreadyForSwipe)reason;
{
}
-(void)didSwipeCard:(PGSwipedCard *)card device:(PGSwipeDevice *)sender
{
if (card != nil) {
swipedCard = [card retain];
cardNumberField.text = card.maskedCardNumber;
expirationField.text = card.expirationDate;
} else {
//A nil card means that there was a swipe but it was unsuccessful.
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Swipe Error"
message:@"The reader was not able to read the card. Please Try Again."
delegate:nil
cancelButtonTitle:@"OK"
otherButtonTitles:nil];
[alert show];
[alert release];
}
}
Supported Devices
IPS Encrypted Card Reader
The IPS is an audio jack-connected card reader. Unlike the IDTECH Shuttle, the IPS is powered by an internal battery.
The IPS has a fast startup time and does not produce a constant tone through the audio jack.
Because the IPS connects through the audio port and there is no way to immediately detect the device type, you will
receive a deviceConnected: event even if the user has only plugged in headphones. Since there is no activation
with the IPS, a deviceActivated: and deviceBecameReadyForSwipe: will also be sent immediately. In order to
be sure that the device is an IPS reader, the PGSwipeIps provides a beginTestCommunication: method you can use to
attempt to communicate with the device. If it returns success, the device is an IPS reader. This is not done by
default to eliminate a delay before the device becomes active.
IDTECH Shuttle
The Shuttle (referred to in code as a UniMag device) is an audio jack-connected card reader. It is powered by a tone from the iPod / iPad / mobile phone.
Before the Shuttle can receive swipes, it must be powered up.
Because the Shuttle connects through the audio port and there is no way to detect the device type until the device is activated,
you will receive deviceConnected events whenever any device is attached to that port. For example, if the user attaches
headphones, you will receive a connection event from the Mobile SDK.
The Mobile SDK can be configured to automatically attempt to power on the swipe reader immediately (this is the default),
or you can disable the automatic activation and only activate the device when desired (e.g. on a payment screen,
or when the user clicks a button).
Important: When powering on the device, the audio volume must be at maximum (done automatically by default). The tone generated
through the audio port to activate the device can be very painful to a listener if they have connected speakers
or headphones. For this reason, swipeController.uniMagReader.messageOptions.activateReaderWithoutPromptingUser is set
to NO by default, causing the SDK to prompt the user for confirmation before activating the reader.
The Shuttle saves battery by only allowing swipes when a swipe has been requested, and a timeout occurs if a swipe is
not received quickly enough (20 seconds by default). For simplicity, the SDK defaults to automatically requesting a
swipe on activation and continuously renewing the swipe request. If you have issues with battery life, you can set
swipeController.uniMagReader.alwaysAcceptSwipe to NO and manually call [swipeController.uniMagReader requestSwipe] when
ready for a swipe.
iDynamo
The iDynamo connects to the mobile device via Apple's dock connector and is only compatible with iOS devices that
use the older 30-pin (non-Lightning) dock connector.
When physically attached, the iDynamo is almost immediately ready to receive swipe events. When connected,
the Swipe Delegate should expect a deviceConnected: message, immediately followed by a deviceActivationFinished:
message, then a deviceBecameReadyForSwipe: message.
When the device is physically detached, the delegate receives the events in reverse order, i.e.
deviceBecameUnreadyForSwipe:, deviceDeactivated:, deviceDisconnected:.
App Store: To support the iDynamo on an app distributed through the App Store, Apple may require you to contact
Magtech for information before they will process your submission. To disable iDynamo support, do not add it to
"Supported external accessory protocols" in your info.plist. You will still receive connect and disconnect
events, but activation will fail, so be sure to check if the sending device is the iDynamo object and ignore it if so.
Known Issue with the iDynamo: There is an issue with device disconnection with the iDynamo and iOS's
ExternalAccessory framework. Upon disconnection, the stream communicating with the device is closed, during which you may receive the warning:
[NSCondition dealloc]: condition (<NSCondition: 0x1d54ce90> '(null)') deallocated while still in use.
After reconnecting, a later disconnect may randomly cause the app to crash with an attempt to send a message to the
deallocated instance. This does not occur frequently, and is more likely to occur when rapidly opening and closing the
application (which sends a disconnect followed by a reconnect when the app re-opens). This issue is with Apple's accessory-handling
framework. Apple is aware of the issue and may fix it in a future iOS release.
Classes Overview
Mobile API: iOS
PGSwipeController
The PGSwipeController contains a set of swipe reader classes that control individual swipe readers.
This is the main Mobile Swipe SDK class required for using swipe devices, intended to be instantiated near the app's startup.
The delegate you set on the PGSwipeController is the object that will receive all of the SDK's swipe events.
Through this class, you can access the controller classes for individual swipe device types
(PGSwipeIps *ipsReader, PGSwipeIDynamo *iDynamoReader, and PGSwipeUniMag *uniMagReader).
You should be sure to call initWithDelegate rather than the parameterless init because during initialization
a check is made to see if any devices are already connected and sends a deviceConnected event if they are.
If the parameterless init is used, the initial connection message will be missed.
- -(id)initWithDelegate:(id<PGSwipeDelegate>)delegate audioReader:(AudioJackReaderType)readerType
Initializes the PGSwipeController and the individual swipe reader classes.
Init checks if any devices are connected and sends a deviceConnected event if they are,
so initWithDelegate: should always be used rather than init to ensure that a connection event
is received if the device is already connected.
The audioReader: parameter selects which type of audio jack-connected card reader to enable.
Only one type of audio jack-connected reader can be used at a time to prevent more than one device
library from attempting to access the audio system at the same time. AudioJackReaderUnimag enables the Shuttle
library, and AudioJackReaderIps enables the IPS Encrypted Card Reader library. You may also select AudioJackReaderNone
to disable both libraries, or AudioJackReaderAutodetectOnConnect to allow the SDK to attempt to determine
the type on connection. Autodetection has several drawbacks. See PGSwipeController beginAutodetectAudioJackCardReader
for more information.
- -(void)setAudioJackReaderType:(AudioJackReaderType)audioJackReaderType messageOptions:(PGSwipeUniMagMessageOptions *)messageOptions
Sets the enabled audioJackReaderType. This can be used to enable support for either the IPS Encrypted Card Reader or the UniMag (Shuttle) reader.
Since the underlying libraries may not always unload cleanly, you should avoid calling this repeatedly to change the supported device type.
Doing so could cause the reader to malfunction or be damaged. Setting this to AudioJackReaderAutodetectOnConnect will disable any currently
selected audioJackReaderType and autodetect upon device connection.
messageOptions will be used only when audioJackReaderType is AudioJackReaderUnimag to replace the default message options.
For any other AudioJackReaderType, or to use the default message options for AudioJackReaderUnimag, this should be nil.
- -(void)beginAutodetectAudioJackCardReader;
Asynchronously attempts to detect the card reader type currently attached to the audio jack.
A communication test is first attempted for an IPS reader. If that fails, an attempt is made to power up a UniMag (Shuttle) card reader.
If either test succeeds, the audioJackReaderType is set to the correct value, and the device will be made ready for use. The
result of the autodetect is reported to the delegate through deviceAutodetectComplete:.
Note: Both the IPS communication test and the UniMag power up produce very loud tones through the audio jack. If speakers or headphones
are attached, the tones would be unpleasant to the user. It is recommended that the user be warned and allowed to remove headphones
before calling this function. This library suppresses user notifications from the UniMag reader during autodetect.
Because the device is powered up in order to test it, you will not receive connection / activation / ready for swipe events during detection.
When your delegate receives its deviceAutodetectComplete message, check the isConnected, isActive, and isReadyForSwipe properties for
its current state and to complete any initialization.
In order to detect the devices, all of the underlying card reader libraries must be loaded. Under some circumstances, these libraries
may not unload cleanly, resulting in unreliable use of the card reader. Autodetect is also a very slow process. For these reasons,
you should not rely on autodetection for each use of the app.
Because communication through the audio jack is not always perfect, autodetect does not always return a correct result. The most common
failure type is returning CardReaderAutodetectResultFail even though a supported device is connected.
If it is known in advance which card reader type will be used, that type should be specified when initializing the PGSwipeController.
If multiple devices must be supported, it is strongly recommended that the result of the autodetect be saved (e.g. in NSUserDefaults)
and re-used on app startup.
PGSwipeDevice
The PGSwipeDevice class represents the functionality that is common to the swipe reader devices.
PGSwipeIDynamo and PGSwipeUniMag both use PGSwipeDevice as a base class.
A PGSwipeDevice object is passed along with every event generated by the swipe devices
to allow you to identify the device type and access device-specific features by casting
to the specific swipe type.
- bool isConnected
True when the reader is physically attached to the device.
- bool isActivated
True when the reader is powered up / initialized.
- bool isReadyForSwipe
True when the reader is able to accept card swipes from the user
- id<PGSwipeDelegate>delegate
Sets the delegate that will receive the device's events. You should not set the delegate directly.
Setting the delegate on the PGSwipeController sets the delegate for each of its members.
PGSwipeDelegate
The PGSwipeDelegate protocol must be implemented by the class that intends to receive swipe reader events.
The following event handlers will need to be implemented.
- -(void)didSwipeCard:(PGSwipedCard *)card device:(PGSwipeDevice *)sender
This event is sent whenever the user swipes a card. Normally "card" will be either a
PGEncryptedSwipedCard or PGMagnesafeSwipedCard (depending on the swipe reader) with track data,
masked card number, expiration date, and cardholder name. If the swiped card can not be read,
"card" will be nil.
- -(void)deviceBecameReadyForSwipe:(PGSwipeDevice *)sender
This event is sent when isReadyForSwipe becomes true. Between this event and the receipt of
deviceBecameUnreadyForSwipe, any swipe should produce a didSwipeCard event.
- -(void)deviceBecameUnreadyForSwipe:(PGSwipeDevice *)sender
reason:(SwipeReasonUnreadyForSwipe)reason
This event is sent when isReadyForSwipe becomes false. There are many reasons the reader
could become unready to receive swipe events, e.g. the swipe request times out,
the device is disconnected, etc. Check the value of "reason" to determine the cause.
On Shuttle readers, if you have set the device to alwaysAcceptSwipe,
the reason may be set to SwipeReasonUnreadyForSwipeRefreshing.
In that case, there is no need to request a new swipe. The "unready" state is momentary
while the device automatically renews after a timeout, swipe, or other event.
- -(void)deviceConnected:(PGSwipeDevice *)sender;
Occurs when the reader is physically connected to the device. With audio-port connected devices
like the Shuttle, this event can be sent when the user attaches headphones.
See the PGSwipeUniMag documentation for more information.
- -(void)deviceDisconnected:(PGSwipeDevice *)sender;
Occurs when the reader is physically disconnected from the device.
With audio-port connected devices like the Shuttle, this event can be sent when the user
detaches headphones. See the PGSwipeUniMag documentation for more information.
- -(void)deviceActivationFinished:(PGSwipeDevice *)sender
result:(SwipeActivationResult)result;
Occurs when the device has finished an attempt to power up/initialize.
This may occur at the same time as deviceConnected or later, depending on the device and settings.
See the individual device documentation for specifics.
Receiving this event does not mean the initialization succeeded. Be sure to check the value of
"result" to verify that it is SwipeActivationResultSuccess.
- -(void)deviceDeactivated:(PGSwipeDevice *)sender;
Occurs when the device has powered down. This may occur when the device is disconnected or,
for certain swipe readers, when you make a call to power down the device.
- -(void)deviceAutodetectStarted;
Occurs when an attempt to detect the type of an audio jack-connected card reader has started. This
can be triggered by a manual call to PGSwipeController beginAutodetectAudioJackCardReader or
automatically when the PGSwipeController is in AudioReaderAutodetectOnConnect mode and an object
is attached to the audio jack by the user.
- -(void)deviceAutodetectComplete:(CardReaderAutodetectResult)result;
Occurs when an attempt to detect the type of an audio jack-connected card reader has finished.
The result may be CardReaderAutodetectResultUniMag, CardReaderAutodetectResultIps,
or CardReaderAutodetectResultFail if the type could not be determined.
When this message is received, the PGSwipeController's audioJackReaderType will have been set
to the appropriate value and the card reader will be activated. Since the device
is powered up while autodetecting, no events for connection, activation, or readyForSwipe
will be received. Check the isConnected, isActivated, and isReadyForSwipe properties to
determine the device's state.
PGSwipeIDynamo
This class is the interface to the iDynamo reader. It is not intended to be instantiated directly.
Instantiate a PGSwipeController instead. The PGSwipeController will create a PGSwipeIDynamo
instance to interact with the iDynamo device.
The iDynamo has no configurable options. When the device is attached, it is active and ready for swipe.
The only property for the PGSwipeIDynamo class is a delegate to receive events, which should not be set directly.
When the delegate is set for the PGSwipeController, the same delegate is passed to the PGSwipeIDynamo instance
it contains.
PGSwipeUniMag
This class is the interface to the IDTECH Shuttle reader. It is not intended to be instantiated directly.
Instantiate a PGSwipeController instead. The PGSwipeController will create a PGSwipeUniMag instance to
interact with the Shuttle device.
There are several flags and methods available for the Shuttle. For an app that does not need much
specific control of the swipe device and is mostly interested in the swipe event,
the defaults can be kept and the device will power up and become ready for swipe when attached.
- id delegate;
Gets or sets the delegate that will receive events. You should not set this directly.
When the PGSwipeController's delegate is set, it will pass it through to this delegate.
- PGSwipeUniMagMessageOptions *messageOptions;
Contains a set of options for interactions with the user, e.g. whether to prompt
before powering up the Shuttle and the text of error messages.
See the PGSwipeUniMagMessageOptions section for specific settings.
- BOOL activateReaderOnAttach;
If this is true, the SDK will attempt to power-up the reader when attachment is detected.
There are 3 things to be aware of:
- If the user attaches headphones to the mobile device,
it will be treated as a swipe reader and an attempt to power it up will be made.
- Before the attempt to activate the reader,
if messageOptions.activateReaderWithoutPromptingUser is set to false (it is false by default),
the user will receive a prompt asking to confirm activation. If they decline,
no activation will be attempted.
- If you call powerDown to deactivate the device,
leaving activateReaderOnAttach will cause the device to immediately power back up.
- BOOL automaticallySetVolumeToMaxOnActivate;
If this is set to true, the device's volume will be set to maximum immediately before
any attempt to power on the reader. Since the reader requires full volume to activate,
this defaults to true and should normally remain true.
- BOOL alwaysAcceptSwipe;
The Shuttle does not accept swipes from the user unless a swipe has been requested.
If alwaysAcceptSwipe is true, the SDK will immediately request a swipe and renew the request
any time the old swipe request times out or ends. You will still receive periodic
didBecomeUnreadyForSwipe: messages, but the reason will be
SwipeReasonUnreadyForSwipeRefreshing to indicate that you should be receiving a
didBecomeReadyForSwipe: message immediately after without any interaction.
The mobile device's battery may deplete faster if the swipe reader is always awaiting a swipe.
If battery life is a concern, consider setting this to false and using requestSwipe when a
swipe is expected, or only setting alwaysAcceptSwipe to true when a swipe is expected.
If alwaysAcceptSwipe is true, you should not use requestSwipe or cancelSwipeRequest.
By default, alwaysAcceptSwipe is true.
- -(void)powerUpDevice:(BOOL)powerUp;
Powers up the reader if powerUp is true or cancels a power up if powerUp is false.
If activateReaderOnAttach is true, this is called automatically after connection to power up the device.
If you wish to only power up the device after user interaction, you should wait until a
deviceConnected: event is received, then call powerUpDevice:YES when they choose to power up.
This should only be used if activateReaderOnAttach is false.
- -(void)powerDown;
Powers down the reader. This may extend mobile device battery life.
A deviceConnected event will be received after shut-down,
which will trigger a power-up if activateReaderOnAttach is true,
so be sure to set activateReaderOnAttach to false before powering down.
It is not necessary to power down the reader before disconnecting it from the device.
- -(void)requestSwipe;
Starts listening for swipe events. You will never need to call this if you set alwaysAcceptSwipe to true
(it is true by default). After receipt of a didBecomeUnreadyForSwipe message,
you may request a new swipe (unless the reason is SwipeUnreadyForSwipeReasonRefreshing).
The request will timeout after 20 seconds, or the amount of time you set in setSwipeTimeoutDuration:
- -(void)cancelSwipeRequest;
Cancels a swipe request to stop listening for swipe events.
You should not use this if you did not manually start the swipe request with a call to requestSwipe.
- -(void)setSwipeTimeoutDuration:(int)seconds;
Sets the time between requestSwipe and when swipes will no longer be accepted.
Default and maximum are 20 seconds. The minimum is 3 seconds.
This still applies even is alwaysAcceptSwipe is true,
but the swipe request will be automatically renewed in that case.
PGSwipeUniMagMessageOptions
This class contains a set of user-interaction options for the Shuttle device.
- BOOL activateReaderWithoutPromptingUser;
If this is set to true (false by default), the reader is activated automatically immediately
after you receive a deviceConnected: event. If this is false, you will need to call
powerUpDevice: during or after the deviceConnected event to power the device or cancel powering up.
- BOOL showInitializingReaderMessage;
If true, an "Initializing Card Reader…" alert is shown while the reader powers up
and is dismissed once power-up completes.
- NSString *cardReaderActivationPrompt;
Gets or sets the prompt that will be displayed to confirm that the user would like to power up the reader.
If you change this prompt, you should also change cardReaderActivationAtMaxVolumePrompt.
Note: an activation prompt is only shown before activation if
messageOptions.activateReaderWithoutPromptingUser is false.
This message is meant to include a warning to indicate that the volume will be set to max.
If automaticallySetVolumeToMaxOnActivate is false, cardReaderActivationAtMaxVolumePrompt is
shown instead of this.
- NSString *cardReaderActivationAtMaxVolumePrompt;
Gets or sets the prompt that will be displayed to confirm that the user would like to power up the reader.
If you change this prompt, you should also change cardReaderActivationPrompt.
Note: an activation prompt is only shown before activation if
messageOptions.activateReaderWithoutPromptingUser is false.
If automaticallySetVolumeToMaxOnActivate is true and the volume is not at maximum,
cardReaderActivationPrompt is shown instead of this.
- NSString *cardReaderTimeoutMessage;
Gets or sets the alert that is shown if the reader times out while attempting to power up.
If you prefer to handle this differently, set this message to nil to prevent it from being shown,
then handle the activationDidComplete:result: message with a result of SwipeActivationResultTimeout.
- NSString *volumeTooLowMessage;
Gets or sets the alert that is shown if the reader can not power up because the volume is too low.
If you prefer to handle this differently, set this message to nil to prevent it from being shown,
then handle the activationDidComplete:result: message with a result of
SwipeActivationResultVolumeTooLow.
PGSwipeIps
This class is the interface to the IPS Encrypted Card Reader. It is not intended to be instantiated directly.
Instantiate a PGSwipeController instead. The PGSwipeController will create a PGSwipeIps instance to
interact with the IPS device.
- id delegate;
Gets or sets the delegate that will receive events. You should not set this directly.
When the PGSwipeController's delegate is set, it will pass it through to this delegate.
- -(void)shutdown;
Closes the card reader's connections and disables event handling to allow it to be deallocated. You should not call this
directly. It is called by the PGSwipeController when necessary.
- -(void)beginTestCommunication(id)communicationTestDelegate;
Asynchronously sends a communication test message to the card reader device and waits for a response.
This can be used to detect whether the connected device is an IPS Encrypted Card Reader. If no response
is received from the device within 5 seconds, the attached object is assumed not to be an IPS reader. Note that calling this
will produce a short, loud tone through the audio jack if headphones are attached.
The result is returned to the communcationTestDelegate by calling ipsCommunicationTestCompleteWithResult:(BOOL)success
with success set to YES or NO, depending on if a response was sent by the device.