The PanPad application is a legacy product and will no longer receive feature updates or enhancements. New integrations should use the CardPointe Integrated Terminal API and terminal devices supported by the CardPointe Integrated Terminal solution.

If you have already integrated the PanPad solution, you should consider migrating your application to the CardPointe Integrated Terminal solution.

Overview

The PanPad™ device is an Ingenico™ terminal loaded with a terminal application called the PanPad. The essential goal of the PanPad device and associated software implementation is to have as simple a terminal application as possible. Retail POS terminals have incorporated numerous features over time, thus leading to substantial applications on the terminals with significant integration requirements. Where relevant this is certainly warranted. If not, perhaps a simpler PanPad integration is sufficient.

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"
}

Sample Applications

We provide the following sample programs to aid in your integration. See below for a brief description of each, and a .zip folder containing the program files.

TokenDemo

A simple C# console program called TokenDemo is included in this distribution. The TokenDemoRun folder contains a prebuilt executable and working configuration file. The Visual Studio Project for TokenDemo is also provided.

Steps required to run the demo are listed below:

  1. Attach your terminal to a Microsoft Windows computer
  2. Determine the COM, or serial, port assigned to the terminal
  3. Edit the cs.ini file in the TokenDemoRun folder updating the serialport property
  4. Run the TokenDemo program in the TokenDemoRun folder
  5. Select option 1 to load the configuration
  6. Select option 2 to connect to the terminal
  7. Run other choices as desired

Desktop Tokenizer

The Desktop Tokenizer is built upon the CCPanPad.DLL and the configuration file (cs.ini). It can be useful as a testing aid in development.

TokenMux

Overview

TokenMux is a multiplexing socket server used to relay messages between the CCPanPad.DLL (& Desktop Tokenizer) and Ethernet connected Ingenico devices.

  • TokenMux consists of the socket server and an HTTP Status server.
  • Messages are prefixed with a client ID (TXXXXX) or a PanPad ID (PXXXXX). Messages with the same ID number are relayed between the client and PanPad pair.

TokenMux requires Java 7.

Terminal Device

Prior to Device Procurement

  • Client provides their TokenMux server settings (URL/IP and port).
  • Terminal device is pre-configured for TokenMux server configuration before shipment.

Security & Connectivity

  • Terminal device is encrypted with a TDES DUKPT key. Pan/Track data is securely decrypted via Hardware Security Modules (HSMs).
  • Terminal device relies on DHCP for internet connectivity. Once the device is connected to an Ethernet port, the device will establish connectivity to the TokenMux server.
  • When terminal initializes, it reaches out to the TokenMux sever to establish connectivity.
  • The terminal device continues to ping TokenMux every 30 seconds indefinitely in order to:
    • Ensure connectivity is reestablished in case of network connectivity loss to the TokenMux
    • Support an active/passive configuration of the TokenMux server in the client environment
  • If the TokenMux server goes offline, the terminal device continues to reach out to the TokenMux until connectivity is reestablished.

TokenMux Server & CCPanPad.dll

Server Configuration

  • TokenMux Server is configured to listen on a specific port.
  • All PAN/Track encrypted data flows via TokenMux Server established sockets.
  • TokenMux server maintains an in memory table of established PanPad device terminal ids (PXXXXX).
  • TokenMux socket connections are not encrypted but PAN/Track/EMV data traversing between terminal device, TokenMux and CCPanPad.DLL is encrypted

Device Pairing

  • TokenMux establishes connectivity to the device and registers its Panpad terminal id (PXXXXX) in a memory table within the TokenMux server.
  • TokenMux Server pairs PanPad terminal device ids (PXXXXX) with established client ids (TXXXXX). All pairing is maintained within the TokenMux app memory.
    • CCPanPad.dll connects to TokenMux and passes a device client terminal id (TXXXXX).
    • TokenMux server pairs up client terminal id (TXXXXX) supplied with the corresponding PanPad terminal id (PXXXXX) in the TokenMux device memory table.

TokenMux and CCPanPad.dll

  • The CCPanPad.dll relies on a configuration file (cs.ini).
    • The cs.ini configuration file defines TokenMux configuration connectivity between a POS application and TokenMux.
    • Customers may want to create a hash table to load the cs.ini configuration settings into memory.
  • The POS application makes calls to CCPanPad.dll to initialize, authenticate, and control device functionality.
  • The CCPanPad.dll continues to ping the paired PanPad terminal every 10 seconds. This ping request is done via the TokenMux established socket connection.
  • The POS application makes use of the CCPanPad.dll to .getTrack then .getToken to generate a token.
    • The encrypted PAN/Track/EMV data may also be sent to CardSecure for the generation of a token.
    • A token is used to submit an authorization request to the CardPointe Gateway via an SSL connection on port 8443
    • CardPointe Gateway provides an authorization response back to cloud based POS application.

Security Recommendations

  • We recommend allowing IP address connections to TokenMux on your firewall or network security policies.
  • We recommend a maximum of 2000 devices per TokenMux server.

CCPanPad.dll Integration Guide

The CCPanPad.dll can be used to interface with Ingenico PanPad devices (iSC250, iSC480, iPP320). It allows developers to easily integrate their .NET 4.0 applications with pre-provisioned Ingenico devices and CardSecure to tokenize credit and debit cards.

Some methods have been updated since Version 1.0. These are marked with DLL (representing the library) required version and / or PPA (PanPad Application) required version.

The methods in this guide have been given shorthand labels which are in pane on the left. The actual Windows functions are on the first line of each section. If present, the version requirements for the DLL and PanPad Application (PPA) are listed in each section.

.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:

    • IngenicoBase.getInput()

    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

    Configuration Settings

    CCPanPad.dll

    Option Description
    url First URL to CardSecure (https://fts-uat.cardconnect.com)
    proxy_host Web proxy host if in use
    proxy_port Web proxy port if in use
    ipaddress IP Address of TokenMux Server (if using Ethernet connection)
    port Port of TokenMux Server (if using Ethernet connection)
    id Unique DesktopTokenizer/PanPad ID (if using Ethernet connection)
    sendtimeout – TokenMux read/send timeout (in seconds) until a socket send request will timeout (default is 5)
    recvtimeout – TokenMux read/send timeout (in seconds) until a socket receive will timeout (default is 5)
    resources Resources file name (w/out the .resources extention) if using customized strings
    serialport Disables registry scanning for Ingenico device and forces use of the specified com port (eg: COM4 or COM6)
    debug Enables debug messages to debug.txt. Set to "on" to enable logging.
    serialtimeout Serial port read/send timeout in milliseconds. (Default is 500)
    readterm Read by line terminator - (Default is 9999)
    inputtimeout User input timeout in seconds. (Default is 60)
    emvamtprompt Boolean to toggle amount display on PanPad during EMV transactions. (default is true - Requires PPA 1050215+)

    Desktop Tokenizer (ccs.exe)

    Option Description
    url First URL to CardSecure (https://fts-uat.cardconnect.com)
    url2 Secondary URL to CardSecure (https://fts-uat.cardconnect.com)
    proxy_host Web proxy host if in use
    proxy_port Web proxy port if in use
    mode Set to 'ingenico' for use with Ingenico devices. Otherwise: keyboard (default), keypad (On-screen numeric keypad), usbkb (for USB/KB emulating swipers)
    credit If set to 'false' the credit button will not appear on the form debit
    debitIf set to 'false' the debit button will not appear on the form
    manual If set to 'false' the manual button will not appear on the form
    signature If set to 'true' prompts for signature for Credit Card and Manual entry
    alwaysontop If set to 'false' the Desktop Tokenizer will no longer stay on top of all other windows
    showconnect If set to 'false' the initial device connection prompt will be suppressed
    tokenlifetime How long the token will reside in the Clipboard in seconds (max 60 seconds)
    minimize If set to 'false' the Desktop Tokenizer will not be allowed to be minimized. Otherwise allowed.
    allowach When set to 'true' allows entry of ACH numbers into 'keyboard' form for tokenization.
    emvamtprompt Boolean to toggle amount display on PanPad during EMV transactions. (default is true - Requires PPA 1050215+)
    manualexpdateprompttrueBoolean to prompt for expiration date during manual card entry. (default is false - Requires PanPad 1050209+)