Integration Overview
PanPad Communications
Ingenico devices most typically communicate via Serial Ports over a USB physical connection.
PanPad Dynamic Link Library for Windows
The PanPad Dynamic Link Library supports the Desktop Tokenizer, and allows client applications to integrate with the PanPad application. This library exposes methods that implement the functions above along with the serial communications layer. The DLL includes a number of other supporting functions, such as calls to the Hosted Tokenization service. Depending on the implementation this can have the effect of reducing or eliminating Payment Card Industry Data Security Standard scope for customer systems and applications.
See the CCPanPad.dll Integration Guide for details on the specific functions of this Dynamic Link Library.
Integration Options
PanPad supports integrators running Microsoft Windows (.NET 4.0) platforms via the client side Dynamic Link Library. Other integration options, such as cloud integrations, are available upon request.
Business Process Options
The recommended business process option is to utilize the DLL and the integrated “Token” methods to retrieve the CardSecure token that represents the cardholder data obtained from the terminal. Using the token in place of the PAN for the subsequent authorization and capture calls to the CardPointe Gateway will result in track, pin, signature and/or EMV data to be retrieved from CardSecure and provided in the authorization request to the payment networks.
See the CardPointe Gateway API documentation for more information on the web services supported by the CardPointe Gateway.
Authorization Request with Token
The example below shows how a token retrieved by .getToken would be used in an authorization request to the CardPointe Gateway.
{
"merchid": "000000927996",
"accttype": "VISA",
"orderid": "AB-11-9876",
"account": "9512179254050085",
"expiry": "1218",
"amount": "100",
"currency": "USD",
"name": "TOM JONES",
"address": "123 MAIN STREET",
"city": "anytown",
"region": "NY",
"country": "US",
"postal": "55555",
"ecomind": "E",
"cvv2": "123",
"track": null,
}
Authorization Request with Ingenico Track/EMV Data
The other option is for the business system to retrieve encrypted data elements from the terminal, then pass them to the CardPointe Gateway in the authorization request. The Gateway can return a token in this scenario if the tokenize property is set to “Y”.
The example below shows how EMV data retrieved by .getEMV would be used in an authorization request to the CardPointe Gateway. The track data retrieved from .getTrack can be used in the same fashion within the request if EMV data is not required.
{
"merchid": "496082673888",
"accttype": "VISA",
"orderid": "AB-11-9876",
"account": "",
"expiry": "1218",
"amount": "218",
"currency": "USD",
"name": "TOM Jones",
"address": "123 MAIN STREET",
"city": "anytown",
"region": "NY",
"country": "US",
"postal": "55555",
"track":"ingenico;st='OK';t1='';t2=';8697472433463611=34330261527203?';pan='3014425926918712';ed='';cvv='';ksn='CDCDCD0702D00BC000280114';hsn='15282SC80794493';isn='2215282SC011053';name='';emv='.82023900.8407A0000000041010.95050000008000.9A03160611.9C0100.5F2403180731.5F2A020840.5F340100.9F0206000000000100.9F0306000000000000.9F0607A0000000041010.9F09020002.9F10120110A04005220000000000000000000000FF.9F1A020840.9F260842C53932F462254B.9F270180.9F3303E028C8.9F34031E0300.9F350122.9F3602002B.9F37040471ED6E.9F390105.9F410400000015.9F1E083830373934343933';emvpos='05';term='9999';ppver='1050214';",
"ecomind": "E",
"cvv2": "123",
"tokenize": "Y"
}
.loadIniFile
Hashtable CCPanPad.loadIniFile(String iniFileName);
iniFileName - Full path (including filename) to the CCPanPad.dll configuration .ini file.
Initializes a Hashtable of properties for use within CCPanPad.dll. The returned Hashtable is the required properties parameter in the CCPanPad. connectIngenico() method.
.connectIngenico
IngenicoBase CCPanPad.connectIngenico(Hashtable properties);
properties - Hashtable (returned from PanPad.loadIniFile()) containing the loaded properties from the CCPanPad.dll configuration .ini file.
Connects to a USB or Ethernet connected Ingenico PanPad. It will first attempt to locate an Ingenico PanPad connected via USB. If not found it will connect to the TokenMux Server if using Ethernet to find the paired PanPad. Connecting to TokenMux requires the ip, port, and id (PanPad ID) parameters to be defined in the configuration .ini file. The returned IngenicoBase object can be used for the calling the remainder of the methods in this documentation.
.initialize
void IngenicoBase.initialize();
Initializes the Ingenico PanPad for use. The initialize call must be made after a connection has been established and before any additional calls are made using the IngenicoBase instance. The Ingenico PanPad will not be usable until it is initialized. Initialization must be completed for every IngenicoBase instance created via the Ingenico.connect() method.
.isDisabled
Boolean IngenicoBase.isDisabled();
Indicates if the Ingenico PanPad has been disabled. If the device has been disabled it cannot be used. Please contact support if your PanPad is disabled.
.ping
Boolean IngenicoBase.ping()
Sends a ping to the Ingenico terminal. Returns 'true' if ping command was successful and communication with the Ingenico terminal is working. Returns 'false' if ping fails and there is no connectivity to the Ingenico terminal.
.setStatusBarCallbacks
void IngenicoBase.setStatusBarCallbacks(Action<int> show, Action hide, Action update);
- show - Callback handler to display a progress bar
- hide - Callback handler to hide a progress bar update - Callback handler to update a progress bar
Allows registration of callback handlers for an initialization status progress bar. The initialization process may take several minutes. The status bar callback should be set prior to calling Ingenico.initialize(). Providing callbacks to show, hide, and update a status bar will allow your application to display the initialization progress. Examples of show, hide, and update callback handlers are:
public void ShowProgressBar(int max) { InitProgressBar.Invoke(new Action(() => { InitProgressBar.Visible = true; InitProgressBar.Minimum = 0; InitProgressBar.Maximum = max; InitProgressBar.Value = 0;
}));
}
public void HideProgressBar() { InitProgressBar.Invoke(new Action(() => { InitProgressBar.Visible = false;
}));
}
public void UpdateProgressBar() { InitProgressBar.Invoke(new Action(() => { InitProgressBar.Increment(1);
}));
}
These callback handlers are then registered with the IngenicoBase instance using the following method call:
ingenico.setStatusBarCallbacks(ShowProgressBar, HideProgressBar, UpdateProgressBar);
.setStatusTextCallbacks
void IngenicoBase.setStatusTextCallbacks(Action<String> show);
-
show - callback handler to update a label with a text string
Allows registration of a callback handler to provide text based updates to a form's label. This will allow the IngenicoBase instance to provide useful user prompts for display in your application. This should be setup prior to calling IngenicoBase.initialize(). An example callback handler for a label is:
public void SetText(String s) {
Label.Invoke(new Action(() => {
Label.Text=s;
Label.ForeColor = System.Drawing.Color.White;
Label.Refresh();
}));
}
The following code will register the callback handler with the IngenicoBase instance:
ingenico.setStatusTextCallbacks(SetText);
.getTrack
String IngenicoBase.getTrack(String message, int amount, aid aid);
Required: DLL r50+ & PPA 1050211+
-
message - text message to be displayed on the Ingenico PanPad screen
-
swipe - boolean flag indicating if the card data should be retrieved via swipe (true) or via manual type-in entry (false). Note that if swipe is true but the resulting swipe data does not contain track 2 data the card data will be tokenized as a manual card entry.
-
amount - If EMV card, an amount is required. Sending an amount > 0 will initiate an EMV transaction rather than a swipe transaction. Note that 2 decimal places are assumed. EG: 100 = $1.00. Maximum amount supported is 9999999.
- aid - An application ID (AID) type that specifies which AID will be sent to the terminal in a swipe or EMV transaction.
Possible values are:
- UNSPECIFIED - omits the AID from the request sent to the terminal.
- CREDT - Sends the credit AID to the terminal.
- DEBIT - Sends the debit AID to the terminal.
If not supplied, defaults to Aid.UNSPECIFIED.
Sends a request to the Ingenico PanPad to retrieve PAN data from the user. The application will block until the user swipes/inserts a card, enters card data manually, or presses the red cancel button. The return data will be encrypted PAN, track, and/or EMV data needed for tokenizing via .getToken
If a chip-enabled card is swiped through the mag-stripe reader, the application will force the user to insert chip into EMV slot.
If the user Cancels the swipe process via the red cancel button on the terminal, the method will return an empty string.
Alternatives:
String IngenicoBase.getTrack(String message, Boolean swipe);
String IngenicoBase.getTrack(String message, int amount);
Required: DLL r35+ & PPA 1050203+
.getEMV
String IngenicoBase.getEMV(String message, int amount);
Required: DLL r35+ & PPA 1050211+
Alias for .getTrack
If a chip-enabled card is swiped through the mag-stripe reader, the application will force the user to insert chip into EMV slot.
.getSignature
String IngenicoBase.getSignature(String message, String track);
Required: DLL r29+
-
track - track data returned from IngenicoBase.getTrack()
-
message - Custom signature entry message to be displayed on Ingenico
Sends a request to the Ingenico PanPad to prompt for signature input. Only to be called after a successful IngenicoBase.getTrack() or IngenicoBase.getEMV() invocation. The captured signature data will be appended to the provided track data and returned. This returned data can then be tokenized via IngenicoBase.getManualToken() or IngenicoBase.getSwipeToken(). Note that signature data itself may be upwards of 8K.
If the user Cancels the swipe process via the red cancel button on the Ingenico the method will return an empty string.
Alternative:
String IngenicoBase.getSignature(String track);
.getPin
String IngenicoBase.getPin(String message, String track);
Required: DLL r29+ & PPA v1040117+
-
track - track data returned from IngenicoBase.getTrack()
-
message - Custom PIN entry message to be displayed on Ingenico
Sends a request to the Ingenico PanPad to prompt for pin input. Must be called after a successful IngenicoBase.getTrack() invocation. The captured pin data will be encrypted and appended to the provided track data and returned. This returned data can then be tokenized via Ingenic oBase.getManualToken() or IngenicoBase.getSwipeToken().
If the user Cancels the swipe process via the red cancel button on the Ingenico the method will return an empty string.
Alternative:
String IngenicoBase.getPin(String track);
Required: PPA v1040117+
.getToken
String IngenicoBase.getToken(String track);
Required: CCPanPad r35+
Convenience method which internally determines which getToken method to call getSwipeToken() or getManualToken() based upon data present in track parameter.
.getSwipeToken
String IngenicoBase.getSwipeToken(String track);
-
track - track data returned from IngenicoBase.getTrack() (both variants) and optionally augmented via IngenicoBase.getSignature() or IngenicoBase.getPin().
This method must be used for track tokenization if the track/emv data was retrieved from the Ingenico PanPad via a credit card swipe (by passing swipe=true in the IngenicoBase.getTrack() method. The response will be a standard CardSecure response. For example, a successful tokenization response would be:
action=CZ&data=9444906784491111
.getManualToken
String IngenicoBase.getManualToken(String track)
-
track - track data returned from IngenicoBase.getTrack() and optionally augmented via IngenicoBase.getSignature().
This method must be used for track tokenization if the track data was retrieved from the Ingenico PanPad via manual entry (by passing swipe=fals e in the IngenicoBase.getTrack() method. The response will be a standard CardSecure response. For example, a successful tokenization response would be:
action=CZ&data=9444906784491111
.getConnectionID
String IngenicoBase.getConnectionID();
Returns the connection ID (either comm port or TokenMux ID) for this IngenicoBase instance.
.sendPrompt
void IngenicoBase.sendPrompt(String message);
-
message - String to be displayed on Ingenico PanPad screen
Sends a string to the Ingenico PanPad to be displayed on the PanPad screen.
.disconnect
void IngencoBase.disconnect();
Disconnects the application from the Ingenico PanPad.
.cancel
void IngenicoBase.cancel();
Required: DLL r29+ & PPA v1040122+
Sends a command to the Ingenico PanPad to cancel the current operation. NOTE: this request may take up to 15 seconds to process on the Ingenico device. Be patient as this is a blocking call.
- Commands which can be cancelled:
- IngenicoBase.getTrack()
- IngenicoBase.getSignature()
- IngenicoBase.getPin()
- Operations on the Ingenico which may have up to a 15 second cancellation delay:
- Manual card entry screen
- Signature entry screen
- Pin entry screen
.getPanPadVersion
int IngenicoBase.getPanPadVersion();
Required: DLL r29+
Returns the version number of the PanPad application installed on the Ingenico device.
.setDefaultPrompt
void IngenicoBase.setDefaultPrompt(String prompt);
Required: DLL r29+
Overrides the default prompt on the Ingenico device. The CCPanPad.dll will by default set the prompt to "Waiting For Agent" followed by the connection ID. This prompt will be automatically sent to the Ingenico during certain modes of operation. This default value may be overridden using this method.
.getConfirmation
Boolean IngenicoBase.getConfirmation(String prompt);
Required: DLL r35+ & PPA v1050203+
Sends a confirmation prompt to the PanPad for the user to either accept (green button) or decline (red button). User's choice is returned.
.getInput
String IngenicoBase.getInput(String prompt, String format);
Required: DLL R39+ & PPA v1050209+
Sends a prompt to the PanPad requesting user input in the format defined by the format parameter. User's entry is returned. Input entry times out after 60 seconds (or timeout specified by inputtimeout configuration option).
Throws CCPanPadException for errors.
Supported formats:
MMYY - Date Entry
command: IngenicoBase.prompt("Enter Expiration Date", "MMYY");
response: "0516"
Nx[,y] - Numeric Entry
x = minimum number of digits (if y not specified, user input length must match x)y = maximum number of digits (optional, max 32)
Example 1
command: IngenicoBase.prompt("Enter Zip Code", "N5");
response: "19406"
Example 2
command: IngenicoBase.prompt("Enter Zip Code", "N5,9");
response: "08081"or
"080819876"
ANx[,y] - Alpha Numeric Entry
- x = minimum number of characters (if y not specified,
user input length must match x)
- y = maximum number of characters (optional, max 32)
Example 1
command: IngenicoBase.prompt("Enter Invoice Id", "AN8");
response: "A1B2C3D4"
Example 2
command: IngenicoBase.prompt("Enter Invoice Id", "AN1,99");
response: "A"or"A123"
PHONE - Phone Number Entry
command: IngenicoBase.prompt("Enter Phone Number'", "PHONE");
response: "1-234-567-8901"
CCPanPadException Error Codes
The CCPanPad DLL is currently being migrated to throw Exceptions rather than null/empty string responses for failures. The following methods currently support throwing exceptions:
Error Code |
Reason |
| 0XX – Generic PanPad Exception |
|
001 |
PanPad not initialized |
002 |
PanPad not ready |
003 |
Null/Empty response from PanPad |
004 |
PanPad request cancelled |
005 |
PanPad request error/failure |
006 |
Method not supported by PanPad version |
| 1XX – Generic CCPanPad DLL Exceptions |
|
100 |
Generic CCPanPad DLL exception |
101 |
Missing required parameter |
| 2XX – Method Level CCPanPad DLL Exceptions |
|
201 |
IngenicoBase.getInput(): Invalid prompt format |