Skipjack RetailAPI Integration GuidePage 2 of 73
Copyright Notice
.................................................................................................................................................
4 Publication History
.............................................................................................................................................
4 Documentation Conventions
...............................................................................................................................
5
Permitted Syntax
.............................................................................................................................................
5 Obtaining Additional Development Information and Documentation
...............................................................
6
Obtaining Reference Documents and Related Resources
...............................................................................
6 Contacting Skipjack Financial
Services..........................................................................................................
6
System Requirements for the Skipjack RetailAPI
..............................................................................................
6 What’s New in Skipjack RetailAPI Version 2.2
.....................................................................................................
7 Obtaining and Installing the Skipjack RetailAPI
....................................................................................................
8
Files, Applications, and Documents Installed by the MSI
............................................................................
10 Skipjack RetailAPI Functional Overview
.............................................................................................................
11 Skipjack RetailAPI High-Level Functional Diagram
...........................................................................................
12
Performance Specifications
..............................................................................................................................
14 Supported PINpad Devices
...........................................................................................................................
14 Supported PINpad Connectivity
...................................................................................................................
14 Supported Swipe Devices
.............................................................................................................................
14 Supported Printers
.........................................................................................................................................
14
Key Transaction Processing Features Supported
..............................................................................................
15 Application Development Lifecycle Using the Skipjack RetailAPI
.....................................................................
16 Class Model and Data Flow Used in the Skipjack RetailAPI
...............................................................................
20
Major Classes within the Skipjack RetailAPI
...................................................................................................
20 Minor Classes within the Skipjack RetailAPI
..................................................................................................
20 Nested classes within the Skipjack RetailAPI
..................................................................................................
21 Supplementary Classes within the Skipjack RetailAPI
....................................................................................
21
Initialization and Financial Transaction Processing using the
Skipjack RetailAPI ..............................................
22 Optional Transaction Methods
..............................................................................................................................
25 Reversals, Reversal Records, Reversal Files, and Exception
Handling
............................................................... 26
Frequently Asked Questions
.................................................................................................................................
27
PINpad Questions
.............................................................................................................................................
27 Test Card Questions
..........................................................................................................................................
27 Key Exchange Questions (Debit Transactions Only)
.......................................................................................
28 Reversals and Reversal File Questions
.............................................................................................................
30 Sequence Number File Questions (Debit Only)
...............................................................................................
33 Receipt Questions
.............................................................................................................................................
33 Certification Questions
.....................................................................................................................................
34 Serial Number Questions
..................................................................................................................................
34 Unique Order Number Questions
.....................................................................................................................
36 Payment Processor Questions
...........................................................................................................................
37 Miscellaneous Questions
..................................................................................................................................
37 Merchant Register Questions
............................................................................................................................
41 Example Application Questions
.......................................................................................................................
42
Sample Receipts
....................................................................................................................................................
43 Sample Receipts for Approved Transaction – Debit
....................................................................................
43 Sample Receipts for Approved Transaction – Debit – Service
Charge and Cash Back (Correct Implementation)
............................................................................................................................................
44
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 3 of 73
Sample Receipts for Approved Transaction – Debit – Service Charge
and Cash Back (Incorrect Implementation)
............................................................................................................................................
45 Sample Merchant Receipt for Declined Transaction – Debit –
(Duplicate Transaction) ............................ 46 Sample
Merchant Receipt for Declined Transaction – Debit (Non-Sufficient
Funds) ................................. 46 Sample Merchant Receipt
for Failed Transaction – Debit (PINpad timeout)
.............................................. 47 Sample Merchant
Receipt for Failed Transaction – Credit Card (Network Connectively
Problem) ........... 47 Sample Merchant Receipt for Approved
Transaction – Credit Card
............................................................ 48
Sample Merchant Receipt for Declined Transaction – Credit Card
(Problem with Account) ..................... 48 Sample Merchant
Receipt for Failed Transaction – Credit Card (Network Connectivity
Problems) .......... 49 Sample Receipts for French Language
Transaction – Debit (Approved)
..................................................... 50
Example Applications
...........................................................................................................................................
51 Purpose of the Example Application
............................................................................................................
51
Example Application Usage Prerequisites
........................................................................................................
51 Example Applications Included in the Skipjack RetailAPI
..............................................................................
52 Starting the Example Applications
...................................................................................................................
53 Using the Basic Payment (No Hardware) Example Application
......................................................................
54 Using the Basic Payment (Hardware) Example Application
............................................................................
56
Basic Payment (No Hardware) – Code Snippet
............................................................................................
58 Basic Payment (Hardware) – Code Snippet
..................................................................................................
59 Perform Key Exchange Button – Code Snippet
...........................................................................................
59 Close Hardware Button – Code Snippet
.......................................................................................................
60 Get Status – Code Snippet
............................................................................................................................
60 Change Status – Code Snippet
......................................................................................................................
60 Get Status – Transactions by Order Number - Code Snippet
.......................................................................
61
Using the Advanced Payment Example Application
........................................................................................
62 Using the Get/Change Status Example Application
.........................................................................................
67 Using the Reversals Example Application
.......................................................................................................
70 Preparing for the Global Payment Systems User Acceptance Test
..................................................................
72
Skipjack_RetailAPl_Integration_Guide_RevJ4.docx
Page 4 of 73
About this Document The information contained in this document is
intended for use by experienced application developers who are
integrating their Point of Sale (POS) applications with the
Skipjack Transaction Network using the Skipjack RetailAPI Software
Development Kit (SDK). Any POS applications which use the Skipjack
RetailAPI can process credit card and Interac (PIN-based) debit
card transactions using the Skipjack Transaction Network. This
document is available in two formats:
• Help file version (HTML Help): Installed with the Skipjack
RetailAPI. Contains links to all Help topics. Available, by default
at Start > Programs > Skipjack Retail API >
Documentation.
• PDF version (Adobe Portable Document Format): Available for
download from the Skipjack Web site. Links to Help topics are not
available in this format. See “Obtaining Reference Documents and
Related Resources” for details about obtaining the latest version
of this document.
Copyright Notice © 2008 Skipjack Financial Services. All rights
reserved. The information contained herein is for information
purposes only. Skipjack makes no warranty, expressed or implied, in
this document. No part of this information may be reproduced in any
form or by any means or transferred to any third party without the
prior written consent of Skipjack Financial Services.
Publication History
September 2006 Version 0.9 (Draft) Issued for internal Skipjack
Financial Services review only.
November 2006 Version 1.0 Released First release of the document to
support Skipjack Retail API general availability.
April 2007 Version 1.0_RevJ1 Minor editorial changes.
August 2007 Version 1.0_RevJ2 Updated to support the newest version
of the API (Version 2.2) with enhanced functionality as described
in the “What’s New in Skipjack RetailAPI Version 2.2” section.
Other minor editorial updates.
August 2007 Version 1.0_RevJ3 Updated document to reflect changes
to the User Interface and minor editorial changes.
September 2007 Version 1.0_RevJ4 Minor editorial updates.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 5 of 73
Documentation Conventions The information presented in this guide
uses the following text conventions throughout.
Convention Usage Example
Blue courier text
<form name="Button" action="https://vpos.skipjack.com/ezPay/or
der.asp" method="post">
Bold text Browser Elements, Fields Names, and Menu Items, Emphasis
Notes
…click on a Swipe Card item …. …make sure you enter your HTML
Serial Number... NOTE: You must consider the following when… Never
delete Settled transactions.
Hyperlinks to external locations on the Web or into the bundled
Help file (PC version only). NOTE: The links to Help File topics in
this document will only function from the Help (CHM-based)
documentation and not from with the PDF version of this
document.
Blue Underline Visit https://www.skipjack.com to learn more about
Skipjack Financial Services.
Italics Titles of documents Skipjack Integration Guide
“Quoted text” Cross-references (clickable hotlink in the PDF
version) to a location within this document
See the “About this Document” section for details.
Permitted Syntax The permitted syntax for variables and other
fields used by the Skipjack Retail API are defined below. When
specified, please ensure you follow these conventions when entering
data into each field or request variable.
Formatting Type Description of Permitted Characters Usage
Notes
Numeric All number characters only. Includes all integers.
Alphabetic (Alpha) Only
All letters of the alphabet only. All letters of the alphabet
excluding special characters &,%,#,*,+,-,@.
Alpha-Numeric All numeric characters and alphabetic characters but
excluding restricted characters.
All numeric and alphabetic characters excluding special characters
&,%,#,*,+,-,@.
All Characters All numeric characters, all letters of the alphabet,
and most symbols but excluding restricted characters.
All characters, including alpha-numeric characters but excluding
restricted characters &,%,*.
Restricted Characters
Characters that are reserved for special uses by internal system
use and cannot be included in variable names or field values.
Restricted for special (system) uses: &,%.*
Page 6 of 73
Obtaining Additional Development Information and Documentation This
section contains information about obtaining additional information
about this product and how to contact Skipjack Financial
Services.
Obtaining Reference Documents and Related Resources A complete
listing of Developer resources including User Guides, Developer and
Merchant Resources, support links and resources is available from
the Skipjack Financial Services Web site at
http://www.skipjack.com/developers.aspx. You can obtain a complete
version (PDF format) this document as well as other documents that
are referenced by this document at this site. Consult each document
as required.
• Skipjack Integration Guide • Skipjack Merchant Reporting Guide •
Skipjack Merchant Services Guide
Contacting Skipjack Financial Services If you have problems using
the Skipjack RetailAPI or have questions about its use that are not
covered in this documentation, please contact Skipjack Financial
Services.
• On the Web: http://www.skipjack.com • Toll-Free Telephone Support
Line: 1-888-368-8507 • By E-mail:
[email protected]
System Requirements for the Skipjack RetailAPI
• The Skipjack RetailAPI has been tested for use with Microsoft
Windows 2000, Windows 2003 Server, Windows XP, and Vista operating
systems.
• The Skipjack RetailAPI requires the .NET Framework 1.1 or 2.0 be
installed on the client machine. The .NET Framework may be
downloaded from the Microsoft .NET Framework Development
Center.
• Programming languages supported include C# and other .NET
languages. Languages other than .NET such as Visual Basic 6.0
(VB6), Delphi 6, and PowerBuilder will be supported by Skipjack
Payment Panel API, currently under development and available soon.
Contact Skipjack Financial Services for more details if this is
required by your implementation.
Page 7 of 73
What’s New in Skipjack RetailAPI Version 2.2 The following changes
and new features are supported in Version 2.2 of the Skipjack
RetailAPI.
• When installed, the location of all RetailAPI files has been
changed from C:\ to the following location on your PC due to Vista
compatibility issues: C:\Documents and
Settings\<USERNAME>\Local Settings\Application
Data\<company name>\<application name>. All the
RetailAPI configuration files are now not shared between different
users and different applications using RetailAPI.
• Level 2 & 3 Data support has been added using the following
additional classes: a. CAuthorize.FIELDS_LEVEL23;
AddField(CAuthorize.FIELDS_LEVEL23, value) added b. CItem level 3
fields, CAuthorize.AddLevel3Item() added
• Paymentech support added
a. CPOSConfiguration.LoadSerialNumbers(s,s,s,s,b,b,b) added
• FREEZE and SPLITSETTLE functionality has been added to the API.
a. CTransactions.Freeze() b. CTransactions.SplitSettle()
• LoadSerialNumbers(void), SaveSerialNumbers(void) and
ShowSerialNumbers classes were added
to save Serial Numbers in an encrypted file.
• CReversals.DeleteReversalsFile() has been added. Use this with
caution.
• AddItem method behavior changed so that it now checks for the
item with the same itemnumber, description, itemcost and is taxable
exists and if so it adds the additional quantity to existing item.
This also may affect AddCashBack(), AddServiceCharge() and
AddShipping() methods.
NOTE: The Skipjack Transaction Network currently ignores multiple
entries with the same itemnumber. If selling the same item at
different itemcost, descriptions, or istaxable please provide
unique itemnumbers.
• The user defined fields are now sorted before they sent to
Skipjack Financial Services so they will appear in alphabetical
order in the Skipjack Register and Skipjack Reports.
• On formatted receipts the size of item description field has been
extended to 22 characters (all characters
except restricted characters) from 15 in the previous
version.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 8 of 73
Obtaining and Installing the Skipjack RetailAPI The Skipjack
RetailAPI is intended for use by POS application developers and is
distributed as an MSI file within a Zip archive
(SkipjackRetailAPISetupX.zip where X represents the version number
of the setup file). The Skipjack RetailAPI includes the following:
API DLL, C# Test Project, Documentation (Help Files), Example
Application, License Agreement, and Readme File. See the “Files,
Applications, and Documents Installed by the MSI” section for
complete details.
1. Obtain a copy of the SkipjackRetailAPISetupXXX.zip file from the
Skipjack Financial Services at
http://www.skipjack.com/developers.aspx?cmsphid=85844789|7785657|2088223.
Scroll to the bottom of the page and select the Download the
RetailAPI Installation File link to display the download dialog
box. Select a convenient download location and click the Save
button.
2. Double-click on the SkipjackRetailAPISetupXXX.zip archive
(Requires WinZip to extract the MSI installer file) you will see
the following WinZip window, or similar.
3. Double-click on the SkipjackRetailAPISetup.msi file to launch
the MSI installer program.
4. The Skipjack Retail API installation window is displayed on your
screen. Select the Next> button to proceed with the installation
or Cancel to abort the installation.
Page 9 of 73
5. A series of windows are displayed. Read the instructions
carefully and select the appropriate buttons to proceed with the
installation. When the installation process is completed the
Skipjack RetailAPI Installation Complete window is displayed
confirming that the installation was successful. Select the Close
button to close this window.
6. You do not need to restart your computer. You can immediately
use the Skipjack RetailAPI by clicking on the
Start>Programs>Skipjack>Skipjack Retail API.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 10 of 73
Files, Applications, and Documents Installed by the MSI The
following files and directories are installed during the Skipjack
RetailAPI MSI installation process.
Installed Item Description
<installdir>\bin Contains the Skipjack RetailAPI.DLL, the XML
InteliSence Help File, an executable file containing the Example
Applications, and the Type Library (TLB) for integrating with VB6
or Delphi 6.
<installdir>\doc Contains the following documents and files:
ReadMe file (ReadMe.rtf), License File (License.rtf), Documentation
in Windows Help format (SkipjackRetail.chm), and the XML Schema for
Authorize objects serialization
(SkipjackRetailAPI_CAuthorize.xsd).
<installdir>\examples\c# Files for C# project and all related
source files for the Example Applications using the DLL. The
Example Applications include a number of fully-functional Example
Applications that can be run to perform actual transactions (debit
and credit card) and used to understand how the Skipjack RetailAPI
functions. The Example Applications are also important for
hardware, software, and network (connectivity) debugging
purposes.
Start Menu Objects The Skipjack RetailAPI adds the (default) menu
path on your computer: Start > Programs > Skipjack >
Skipjack RetailAPI. Menu items are added for each of the relevant
applications and files.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 11 of 73
Skipjack RetailAPI Functional Overview
The Skipjack RetailAPI simplifies application development and
integration by handling all key internal communications, hardware
initialization, receipt generation and formatting required for
processing debit and credit card transactions. The Skipjack
RetailAPI transmission to the Skipjack Financial Network is via a
Secure Sockets Layer (SSL) HTTPS connection ensuring data security.
Skipjack Financial Services, in turn, has secure, dedicated
connection to each Payment Processor as depicted in the
illustration below.
The Skipjack RetailAPI also manages and controls the automatic
Reversal of transactions in the event of hardware or network
failures. This ensures exception handling is automatic for normal
transaction processing. The Skipjack RetailAPI provides a Reversals
class to handle exception handling of Reversals that cannot be
automatically completed.
For a complete list of the capabilities and supported hardware and
feature of the Skipjack RetailAPI, see the “Performance
Specifications” section for more details.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 12 of 73
Skipjack RetailAPI High-Level Functional Diagram The illustration
below shows the main components used by the Skipjack RetailAPI to
perform financial transaction processing. A brief description of
the transaction processing and communications between each
component is described for a typical transaction.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 13 of 73
1. The Skipjack RetailAPI communicates with the attached hardware
(PINpad, swipe devices and printers)
to initiate the hardware and prepare it for use by the POS
application. Once initiated, these configuration settings may be
saved in a local Configuration File for later use or for network
distribution.
2. The Merchant begins a financial transaction using the POS
application that interfaces with the Skipjack RetailAPI.
Transaction data is entered using the POS application which uses
the Skipjack RetailAPI. This action triggers the Skipjack RetailAPI
to begin the transaction processing.
3. For debit and credit card transactions, the Skipjack RetailAPI
temporarily stores transaction data locally in an encrypted
Reversals File as a Reversals Record. The Reversals File allows the
API to reverse transactions automatically whenever network
connectivity, power failures, or POS hardware failures occur during
transaction processing. The Reversals Record is removed for
transactions that are successfully completed. For more information
about Reversals, see the “Reversals, Reversal Records, Reversal
Files, and Exception Handling” section for more information. Also,
debit transactions only, the API populates the local Sequence
Number File and transmits this Sequence Number used by the debit
Processor (Global Payments Systems) which is used as part of their
process to maintain a unique record of each transaction they
processes.
4. The Skipjack RetailAPI sends the transaction data to the
Skipjack Transaction Network using a Secure Socket Layer (SSL)
HTTPS connection across the Internet. When the Skipjack Transaction
Network transaction server receives the transaction data it
performs a check to validate the card number and verifies that
other transaction data fields are complete and properly formatted.
The Skipjack Financial Services network then forwards the
transaction data to the Processor. The Processor, through direct
connection to other networks (Banks/Financial Institutions)
processes the card account information and returns transaction
details to the Skipjack Transaction Network.
5. The Skipjack RetailAPI receives transaction messaging from the
Skipjack Transaction Network and interprets and displays the
results of transaction on the PINpad (if a PINpad was used in the
transaction), removes the transaction record from local Reversals
File, and increments the Sequence Number File. The Approval,
Decline, or Failure response messages returned from the Skipjack
Transaction Network to the application typically take 5 seconds or
less. The Skipjack Transaction Network stores all the transaction
data in an encrypted format for later use by the Reports Manager,
Merchant Register or for subsequent (Supplementary Methods)
transaction processing.
6. The application instructs the Skipjack RetailAPI to format and
print a receipt (Customer and Merchant copies) for each transaction
on supported printers. A copy of receipt is saved to a local file
(Last Receipt File) which can later be recalled if a printing error
occurs before the receipt printing is completed.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 14 of 73
7. Debit transactions are marked within Skipjack Financial Services
as Settle upon Approval by the Processor. For credit card
transactions the Settlement process is more segmented. Depending on
the settings on the Skipjack Merchant Account, the credit card
transaction will be added to a Settlement Batch which is then
settled when the Settlement Batch is submitted for processing by
the Processor. This normally occurs on a once-daily basis in order
to minimize transaction processing fees. Funds are then transferred
to the Merchant’s Bank Account. For more information about Credit
Card Processing, see the Skipjack Integration Guide for more
information.
8. You may use the Skipjack Merchant Register and/or Report
Manager, web-based GUIs available though the Web, to view
transaction details and generate reports on transactions previously
submitted using the Skipjack RetailAPI (and other methods). For
more information about the use of the Merchant Register and the
Reports Manager, see the Skipjack Merchant Services Guide and the
Skipjack Merchant Reporting Guide, respectively for more
information.
Performance Specifications
Supported PINpad Devices The following PINpad devices must be
obtained through Global Payment Systems to be supported:
• VeriFone SC 5000 v1.0g and v1.0h • VeriFone SC550 1.0b
Supported PINpad Connectivity
• Serial (COM) • USB via Belkin F5U109 USB-to-COM adapter (SC 5000
supported in 8-bits/No Parity mode only)
Supported Swipe Devices • VeriFone SC 5000 v1.0g and SC 5000 v1.0h
• VeriFone SC550 1.0b • MagTek Mini MICR USB check/card swipe combo
• Most PS/2 or USB swipe keyboards and devices supporting Keyboard
Emulation mode (Tested with the
MagTek Mini Swipe, Preh PCPOS and MC128 keyboards)
Supported Printers • All Windows-enabled printers • EPSON
TM-T88IIIP (or similar) for high-speed direct (not using Windows
drivers) printing
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 15 of 73
Express, Discover, JCB, and Diners Club). • Bilingual PINpad
communication and receipt printing (English and French). The
language used may
be selected manually or read directly from the swiped card for
debit transactions. • Auto-swipe mode allows auto-detection of card
type (debit or credit card) used in the transaction. • Supports all
Required, Optional, and User-Defined fields for all Skipjack
Financial Services
transaction methods. • Reversal File supports automatic transaction
Reversals in event of network, hardware, or power
failures. Incomplete transactions are stored on the client-side in
a Reversals File. The encryption method used provides excellent
security and uses unique keys based on the Developer Serial
Number.
• Last Receipt File supports the storage, retrieval, and reprinting
of the last receipt for protection against power failure or printer
failure during receipt printing.
• Automatic detection and configuration of connected POS hardware
(Port Number, Baud Rate, Parity Check mode, and related parameters)
is fully supported, simplifying configuration and hardware
initialization.
• Configuration File supports distributed, network-based hardware
configuration when multiple POS devices use the same configuration.
This helps to ease deployment for large POS enterprises.
• Preformatted bilingual (English or French) Customer and Merchant
receipts generated by using an included receipt formatting options
(Certified by Global Payment Systems for Canadian PIN-less debit)
or via your own customized XSLT files (optional).
• Tip Option supports a tip amount to be added to a debit
transaction or the tip amount to be printed on the receipts.
• Service Charge Option supported by API to indicate any service
charge amount to be printed on receipt and in the Skipjack Merchant
Register.
• Cash Back Option supported by API to indicate any cash back
amount to be printed on receipt and in the Skipjack Merchant
Register.
• Shipping Charge Option supported by API to indicate any shipping
charge amount to be printed on receipt and in the Skipjack Merchant
Register.
• Purchased Items List supports a detailed, printed, itemized list
included on receipts for each transaction.
• Swipe Additional Cards option supports a Merchant’s POS
application accepting loyalty (Reward/Points cards) cards for each
transaction. The Payment card is automatically detected after
swiping these additional cards.
• Skipjack RetailAPI is Certified by Global Payments System. •
Skipjack Financial Services is Certified for credit card
transaction processing using a variety of
Processors. See the Skipjack Integration Guide for a list of
supported Payment Processors. • Skipjack RetailAPI is bundled with
additional classes to perform other transaction methods and
functions including: Get Transaction Status (by date or order
number), Change Transaction Status (Authorize, Authorize
Additional, Credit, Settle or Delete), Client-side Card Validation,
and Unique Order Number generation.
• Example Applications included providing Developers with .Net (C#
only) examples to aid in Application Development and Integration.
Example Applications also serve as tools for troubleshooting
hardware and network connectivity issues during application
development.
• Full Developer support provided by Skipjack Financial Services
including full phone support using the toll-free numbers listed in
the front of this guide.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 16 of 73
Application Development Lifecycle Using the Skipjack RetailAPI This
section describes the development, integration, and deployment
lifecycle of your POS application when it is using the Skipjack
RetailAPI component. Please read and understand the development
process prior to starting your application development. All steps
listed below apply if your POS application will be processing both
credit card and Interac debit cards (PIN-based debit cards). If
your application will be processing debit card transactions only or
credit card transactions only, applicable steps are identified in
the first sentence of the step. Some steps have a waiting period
associated with them to process the paperwork required. The length
of time for this processing is outside of the control of Skipjack
Financial Services. The timelines indicated below should be
considered rough guidelines only and reflect the typical time for
each of these steps to be completed. NOTE: To obtain the
application forms required by Global Payment Systems to complete
your POS application development go to
http://www.skipjack.com/developers and download the ZIP archive
named GPSRequiredDocs.zip. This file also contains a PDF to assist
you in completing your integration and prepare for Global Payment
Systems Acceptance Testing.
1. Obtain a Skipjack Development Account by calling Skipjack
Financial Services (toll-free) at 1-(866) 438-8767. A Skipjack
Customer Support Representative will gather information from you
about your requirements and provide you with an appropriate
Skipjack Development Account. Upon completion of this call, you
will receive e-mail from Skipjack Financial Services containing all
information required to access and use the Skipjack Transaction
Network, including: • HTML Serial Number(s) and Developer Serial
Number(s): Required to submit transactions to the
Skipjack Transaction Network. • Vendor Login Serial Number,
Username, and Password: Required for Secure Login using Web
interface at https://secure.skipjack.com (For Reports Manager and
Merchant Register access). • Link to the Web API download site.
(Required to download the Skipjack RetailAPI MSI installation
Zip file if the Zip file was not included in the e-mail or if you
require additional copies.) • Access to the toll-free Skipjack
RetailAPI Development Support telephone support (866)
438-8767
2. Obtain and read the documentation about the Skipjack RetailAPI
and install the Skipjack RetailAPI
MSI. See the “Obtaining and Installing the Skipjack RetailAPI”
section for details about the installation process. See the”
section for details about obtaining additional documentation and
accessing development resources related to the Skipjack Retail
API.
Page 17 of 73
3. For credit card transaction processing only, you need a Merchant
Account to process credit card transactions. Obtain a Merchant
Account from the financial institution of your choice for each
credit card type to be accepted (Visa, MasterCard, American
Express, JCB, Diners Club, Discover). Using (virtual) test credit
cards supplied by Skipjack Financial Services for test transactions
may be supported by your Acquirer/Payment Processor before your
Merchant Account setup is finalized. Contact your Acquirer and/or
Payment Processor for their specific details and requirements they
may have regarding test credit card usage. See the “Test Card
Questions” section for details about virtual test credit cards. You
can contact Skipjack Financial Services if you require help
choosing an appropriate credit card Acquirer and Merchant Account.
NOTE: You must provide detailed business information to compete
this step. Processing time after submitting applicable paperwork
may take up to four weeks. Please allow sufficient time in your
development and integration scheduling to accommodate this
processing period.
4. For debit card transaction processing only, you must obtain a
PIN-based debit Merchant Account, PINpad, and test debit cards from
Global Payment Systems (GPS). These are required to accept, swipe,
and process PIN-based (Interac) debit cards. However you can start
coding your POS application without processing test debit
transactions. Contact Skipjack Financial Services for assistance in
ordering your PINpad and test cards from Global Payment Systems.
Skipjack Financial Services will provide information about
applicable fees, timelines, and provide Application Forms and
associated paperwork required for you to complete this step. NOTE:
You will be required to provide detailed business information to
both Skipjack Financial Services and Global Payments Systems to
complete this step. This step may take up to four weeks to complete
after the all properly competed paperwork is received by Global
Payment Systems. Please allow for this processing time in you your
development scheduling. You cannot process PIN-based debit cards
using your POS application during this time period.
5. Develop and integrate your POS application using the Skipjack
RetailAPI. Follow the instructions and guidelines contained within
this document and the associated Help file included with the
Skipjack RetailAPI.
6. For credit card transaction processing, test your POS
application as described in the Skipjack Integration
Guide. When testing trackdata (swipe) functionality, you must
ensure that Skipjack Merchant Account is set to Retail in the
Market Type section of the Edit Accounts window to test that
trackdata is being read from the card successfully. Confirm this
using the Skipjack Merchant Register.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 18 of 73
7. For debit transaction processing only, once your application
development is complete, perform you own (informal) User Acceptance
Testing to verify that your POS application is fully-functional and
ready for the Global Payment Systems User Acceptance Test. See the
Preparing for the Global Payment Systems User Acceptance Test” for
more information about the specific test cases your application
must be able to accommodate. NOTE: The Global Payment Systems
document Certification Script (Version 2006.03, Revised 2006.03.29)
is provided to you to assist you in your Global Payment Systems
User Acceptance Testing. Global Payment Systems reserves the right
to change this document at any time.
8. For credit card transaction processing, test your POS
application in accordance with the testing guidelines described in
the Skipjack Integration Guide.
9. For debit transaction processing only, contact Skipjack
Financial Services when your POS application
development is completed. Skipjack Financial Services will verify
that your POS application is ready for testing and assist you in
obtaining and submitting the necessary paperwork required for the
Global Payment Systems User Acceptance Test. A testing fee must be
remitted with your paperwork. See also the “Preparing for the
Global Payment Systems User Acceptance Test” section for related
information.
NOTE: User Acceptance Testing is normally scheduled within 4 weeks
of the time Global Payment Systems has received all properly
completed paperwork and the application testing fee. Incomplete or
incorrect paperwork as well as failure to remit the testing fee
with your will delay the scheduling of your test.
10. For debit transaction processing only, complete the Global
Payment Systems User Acceptance Test. As
part of this testing you will be required to submit to Global
Payment Systems copies of Merchant and Customer receipts generated
by your POS application for selected test cases. The actual test
cases will be similar to those contained in the Certification
Script document. See the “Preparing for the Global Payment Systems
User Acceptance Test” section for details as to how to obtain this
document. NOTE: It may take up to 4 weeks after completion of your
Global Payment Systems User Acceptance Test and submission of
sample receipts to receive your Acceptance Letter from Global
Payment Systems. This Acceptance Letter will confirm that your POS
application has passed Global Payment Systems User Acceptance
Test.
11. For debit transaction processing only, you must send a copy of
your Acceptance Letter from Global
Payment Systems to Skipjack Financial Services to confirm
successful completion and compliance with the Global Payment
Systems User Acceptance Test.
12. Upon receipt of a copy of your Acceptance Letter, Skipjack
Financial Services will provide you with a Skipjack Production
Account. Skipjack Financial Services will send an e-mail
confirmation of your Skipjack Production Account containing all the
required Production credentials including: HTML Serial Number(s),
Developer Serial Number(s) and other relevant details. NOTE:
Production credentials must be used in your POS application for
processing Live transactions in the Production environment.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 19 of 73
13. For debit transaction processing only, you must obtain
Production PINpad(s) from Global Payment Systems in order to submit
and process debit transactions in the Production (Live)
environment. A fee applies for each PINpad ordered. PINpads will be
sent by Global Payment Systems to the Vendor. NOTE: It may take up
to three weeks after the receipt of all correct paperwork and fees
Global Payment Systems to obtain your Production PINpads. Please
ensure that you plan for this waiting period in your deployment
scheduling.
14. For debit transaction processing only, the Vendor will
configure the POS application and deploy the Production PINpads to
each Merchant location. Once deployed and configured your POS
application is ready to process Live transactions by
Merchants.
15. Certify your application as Skipjack Certified. This will help
reinforce and communicate the message to
your users of your commitment to security, reliability, and
dependability. Registration also ensures you are eligible for other
programs offered by Skipjack Financial Services that are
exclusively offered Certified Partners. Find out more about being
Skipjack Certified online by going to
http://www.skipjack.com/developers.aspx?cmsphid=85844789|7785657|4559040.
16. Register your application online with Skipjack’s Solution
Finder to maximize your business
opportunities. Registration in Solution Finder is free and provides
Skipjack’s sales partners with a link from their customers to your
Web site. For more information about registering online, go to
https://secure.skipjack.com/partners/search.aspx or email
[email protected].
See Also • See “Preparing for the Global Payment Systems User
Acceptance Test” for related information about
Global Payment Systems User Acceptance Test.
Page 20 of 73
Class Model and Data Flow Used in the Skipjack RetailAPI A number
of classes are used by the Skipjack RetailAPI and are described
briefly below. For more detailed information about each class in
the Skipjack RetailAPI see the Help file included with the Skipjack
RetailAPI. NOTE: Links to Help topics in the compiled Help file
(CHM) from within this document will not function in the PDF
version of this document. See the Help file version (located by
default at Start > Programs > Skipjack > Skipjack
RetailAPI > Documentation
Major Classes within the Skipjack RetailAPI
) to view the Help file topic information.
The Skipjack RetailAPI is represented by two major public
classes:
• CAuthorize: This major class is used for processing transactions
for credit card and debit transactions.
• CPOSConfiguration: This major class is used for communicating
with hardware and storing and maintaining the API settings in the
Configuration File. CAuthorize uses CPOSConfiguration class and
CAuthorize.FinancialRequest method complete all major transaction
functions. The CAuthorize.FinancialRequest method requires an
object of CPOSConfiguration type as a parameter.
Minor Classes within the Skipjack RetailAPI
The remaining (minor) classes are:
• CReversals – This class is used for reversing financial
transactions using the locally stored and encrypted transaction
data maintained in the Reversals File. This class also used by
CAuthorize.FinancialRequest to add Reversal records to the
Reversals File and to attempt to reverse failed transactions.
• CTransactions – This class is for obtaining the transaction
status from the Merchant Register and performing Authorize,
Authorize Additional, Credit, Settle, and Delete operations on
existing transactions. This class is also used by the
CReversals.Reverse method to obtain transaction status and perform
Reversals (along with the CAuthorize class).
• CPOSReceipt – This class is used to create and format the
Merchant and Customer copies of receipts prior to completing each
transaction submitted. The object constructor takes CAuthorize
object as a parameter. The internal formatting of receipts can be
used (Debit receipts are Certified by Global Payment Systems), or
user-defined formatting via XSLT files can be used. A formatted
receipt can be printed using CPOSReceipt.PrintReceipt method of the
CPOSConfiguration class object.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 21 of 73
Nested classes within the Skipjack RetailAPI
• CAuthorize.CRequestData and CAuthorize.CItem: These classes hold
transaction information that is submitted for Approval. Despite the
properties of objects of those classes are left public in
CAuthorize for serialization purposes, it is highly recommended to
use various Add* methods to populate each with data.
• CAuthorize.CResponseData: This class holds the corresponding
transaction results obtained from the Skipjack Transaction Network
if the transaction was submitted and a response has been
received.
• CReversals.CRecord: Used for storing the original transaction
information that is required to reverse the transaction in the
event of hardware, network, or power failure of the host PC or
connected hardware during transaction processing. The CAuthorize
object adds a CReversals.CRecord object to the Reversals File for
each CAuthorize.FinancialRequest call before sending the Approval
request to the Skipjack Transaction Network. The CAuthorize object
removes the Reversal record from the Reversals File for each
successfully processed transaction.
• CTransactions.CRecord: is used by the Skipjack RetailAPI for
storing information about a transaction obtained by the
CTransactions.GetByDate and CTransactions.GetByOrderNumber
methods.
Supplementary Classes within the Skipjack RetailAPI
These classes may be used by your application to control the
verbosity of the API in your application. Use of each is
optional.
• SJLogger: This class is used by other non-Supplementary API
classes for logging and troubleshooting. You can select the level
of logging desired using this class.
• SJCursor: This class is used other non-Supplementary API classes
for changing the cursor appearance which is used to indicate that a
transaction processing stages (transaction processing in progress
indication).
• SJSplashWindow: This class is used by other non-Supplementary API
classes to display initialization, error, and prompt messages to
the end user using a splash screen.
Changing SJLogger.LogLevel (static),
CPOSConfiguration.CSettings.EnableChangeCursor, and
CPOSConfiguration.CSettings.EnableSplashWindowLevel respectively
controls the verbosity of the Skipjack RetailAPI. You can use each
class as required.
This class is used to generate unique order numbers:
• RetailLib: This class contains static methods for card
validation, parsing, and similar functions that are used by various
method of API, but also available for public use. The use of
RetailLib.GenerateUniqueOrderNumber method for generating unique
Order Number is optional but is highly recommended by Skipjack
Financial Services.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 22 of 73
Initialization and Financial Transaction Processing using the
Skipjack RetailAPI The illustration and text in the section below
describes the interactions between the POS application and the
Skipjack Retain API for transactions processing. The illustration
shows the Skipjack RetailAPI classes, methods, and objects called
by the POS Application that must be handled by your
application.
• Item 1 applies to hardware initialization functions only which
are performed during POS application startup, or when new hardware
devices are added.
• Items 2 to 5 are functions that must be performed for each
financial transaction. • Item 6 is completed at the end of
transaction processing when the POS application shuts down.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 23 of 73
1. The POS application is started and calls the CPOSConfiguration
Constructor to create a CPOSConfiguration class object.
• The POS application:
o Loads previously saved Configuration File by calling the
CPOSConfiguration.Load method (Assuming that the hardware
configuration information was saved to the Configuration File by
calling the CPOSConfiguration.Save method), OR
o Does Nothing (default settings will be used).
• The POS application calls the CPOSConfiguration.Init method to
initialize hardware using hardware settings previously set (or
defaults).
• The POS application may call the CPOSConfiguration.Save method to
save the configuration settings into the Configuration File as
required. (This is an optional method).
• The POS application loads all Serial Numbers to be used for
transaction processing into the CPOSConfiguration object by calling
the CPOSConfiguration.LoadSerialNumbers method.
• For debit transactions, when a Key Exchange is required, the POS
application performs a Key Exchange by calling the
CAuthorize.KeyExchange method to initiate a Key Exchange between
the PINpad, Skipjack Transaction Network, and Global Payment
Systems.
2. The POS application creates a unique Order Number for each
transaction submitted for processing by calling the
RetailLib.GenerateUniqueOrderNumber method. (This is an optional
method, but strongly recommended by Skipjack Financial Services.)
Developers may use their own methods to generate unique Order
Numbers but should do so very cautiously. Not using unique Order
Numbers, or using spaces and non-alpha-numeric characters in Order
Numbers creates problems with automatic Reversals when the
non-alphanumeric characters are removed by the Skipjack Transaction
Network during processing.
3. The POS application creates new object of CAuthorize
class.
• Application populates the object with all the Required, Optional,
Level 2/3 transaction data by calling various Add* methods.
• Application initiates a transaction by calling
CAuthorize.FinancialRequest method, which (depending on the type of
transaction and hardware used) may include swiping debit or credit
cards, swiping reward cards, using PINpad (selecting account,
entering PIN number, entering tip amount), requesting authorization
from Skipjack, displaying transaction result on the PINpad and
performing automatic (transparent) Reversal in case of
exception.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 24 of 73
• CAuthorize.CResponseData.IsApproved to determine whether the
transaction was Approved.
• Other CAuthorize.CResponseData.* to get more details about the
transaction results, such as the reasons for Decline or the AVS
results (for example) for Approved transactions. See the Skipjack
Integration Guide for more details.
• CAuthorize.* to collect other info about transaction such as card
type, language, ordered items and other such data.
5. The POS application calls the CPOSConfiguration.PrintReceipt
method to print copies Merchant and Customer receipts for each
transaction submitted for processing and to save a copy of each
receipt into the Last Receipts File. The POS application may also
call the CPOSReceipt.Save method (this is an optional method) to
save the last printed receipt to the local Last Receipts File, as
required. NOTE: Steps 2 to 5 must be repeated for each financial
transaction processed by the POS application. For transactions that
require additional transaction operations (Such as Authorize
Additional amounts, Credits, etc), see the “Optional Transaction
Methods” section for details.
6. When the POS application closes, the application must call the
CPOSConfiguration.Dispose method to release all resources in use by
the Skipjack RetailAPI.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 25 of 73
Optional Transaction Methods These optional methods belong to the
CTransactions class and may be called by your POS application to
obtain transaction details and perform advanced transaction
processing functions on existing transaction records in the
Skipjack Merchant Register. NOTE: You can also use the Skipjack
Merchant Register to process those additional operations using a
web browser. See also the “Merchant Register Questions” section for
more information.
Get Transaction Status Methods The following methods may be called
by the POS application to obtain information about previously
submitted transactions in the Skipjack Merchant Register.
• CTransactions.GetByDate Method is called to obtain transaction
details for records specified by Order Date submitted.
• CTransactions.GetByOrderNumber Method is called to obtain
transaction details for records specified by Order Number.
Change Transaction Status Methods These methods may be called by
the POS application to perform advanced transaction processing
functions on previously submitted transactions in the Skipjack
Merchant Register.
• CTransactions.Authorize - Method is called to Authorize a
previously Declined transaction. •
CTransactions.AuthorizeAdditional - Method called to Authorize an
additional amount (Re-Bill) for
existing Approved transactions. • CTransactions.Credit - Method is
called to Credit (Refund) a previously Authorized transaction. •
CTransactions.Delete - Method is called to Delete (Void) a
previously Authorized transaction. • CTransactions.Settle - Method
is called to Settle a previously Authorized transaction. •
CTransactions.Freeze - Method is called to Freeze a previously
Authorized transaction. • CTransactions.SplitSettle - Method is
called to SplitSettle a previously Authorized transaction.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 26 of 73
Reversals, Reversal Records, Reversal Files, and Exception Handling
There are three types of Reversals used to handle exceptions by the
Skipjack RetailAPI as described below.
1. Automatic Reversals: These Reversals are normally handled
transparently (automatically) by the Skipjack RetailAPI with no
additional POS application intervention required. Automatic
Reversals comprise the majority of Reversals performed by the
Skipjack RetailAPI.
2. POS application-initiated Reversals: Intermittently, your POS
application may be required to perform
POS application-initiated Reversals. Skipjack Financial Services
recommends that the POS application call the CReversals.Load method
(this is a Required method whenever this class is used) and one or
more of the following methods (optional methods in this
class):
• CReversals.Remove may be called by the POS application to remove
the Reversal Record from
the Reversals File. • CReversals.Save may be called by the POS
application to save the Reversal Records held in the
Reversals File. • CReversals.Show may be called by the POS
application to display all the Reversal Records held
in the Reversals File. • CReversals.Reverse may be called by the
POS application to attempt to reverse Reversal
Records whose attempt counts are below the set threshold or to
attempt to reverse a record with a given order number.
• CReversals.DeleteReversalsFile may be called by the POS
application to delete the Reversal Records in the Reversals
File.
Having your POS application use these methods, as required, will
help ensure that Reversals are properly completed.
3. Manual Reversals: Manual Reversals involve manually inspecting
and interpreting each Reversal Record, determining the cause of the
Reversal failure, and taking the appropriate steps to perform the
Reversal. In some cases this might involve calling the Payment
Processor (for example Global Payment Systems) to have the
transaction reversed by them.
See Also
• “How do I determine the cause of a Reversals failure for records
that are not automatically reversed?” • “Reversals and Reversal
File Questions”
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 27 of 73
Frequently Asked Questions This section contains questions and
answers related to the Skipjack RetailAPI. Please read this section
carefully along with all other supporting documentation (Help file
and readme.txt file included with the application) before
contacting Skipjack Financial Services with any support
questions.
PINpad Questions
There are several PINpad timeouts. Are the timeout values
configurable by us though the API or are they hard-coded into the
DLL? The timeouts are hard-coded into the PINpad and the
manufacture doesn't provide any way to change them. The timeouts in
SC5000 1.0h is double of those in SC5000 1.0g and SC550
(FYI).
Why is my PINpad not being detected? The default setting is to
autodetect PINpad port number and settings on ports COM 1 to 9.
Usually it cannot autodetect the PINpad when the PINpad port is
already in use by some other applications, or is misconfigured by a
device driver. Check background processes for any applications
which might be not responding, improperly installed drivers, and
similar issues. (For example a misconfigured driver for serial
printer may create such problems). Also, use the Advanced Example
Application and select the PINpad port number and settings
explicitly.
How do I obtain my PINpad? The process for obtaining PINpads is
directly related to obtaining test cards. See the “How do I obtain
my test cards?” section for more information.
Test Card Questions
How do I obtain my test cards? For PIN-based debit transaction
processing, debit test cards are provided by Global Payment Systems
along with the Development (Test) PINpad(s). Debit test cards,
PINpad(s), and usage documentation are provided as part of a
Welcome Kit approximately four weeks after the Global Payment
Systems receives your properly completed Test Card Application
Form, Purchase Order, and Cheque for the cost of the PINpad(s).
Contact Skipjack Financial Services for assistance in preparing
your request for your test debit cards and PINpads. NOTE: You must
request the Production PINpad(s), separately from but using the
same procedures as for a Test PINpad (as described in “Application
Development Lifecycle Using the Skipjack RetailAPI”. You would
normally obtain your production PINpad when your POS application is
ready for the Global Payment Systems User Acceptance Test. For
credit card processing, your credit card Acquirer will provide you
with test credit cards. Contact your credit card Acquirer for
information about how to apply for and obtain test credit
cards.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 28 of 73
See Also • See “Application Development Lifecycle Using the
Skipjack RetailAPI” for related details.
Some test transactions are being Declined. Is there are maximum
amount for transactions used with the test cards? Yes, there is a
maximum amount of $10.99 per transaction for credit card
transactions when using the test credit card. Transactions with
amounts greater than $10.99 will be Declined.
The debit test card does not seem to work anymore and I know that
it is a valid test card. What could be wrong? If you enter an
incorrect PIN three times in a row the test card will be locked and
unusable for 24 hours. Skipjack Financial Services has no way to
reset this. Please ensure you correctly enter the PIN for each test
transaction.
Is there a (virtual) test credit card that I can use while I am
waiting for my real test credit cards to arrive? Yes, Skipjack
Financial Services has (virtual) test cards that can be used to
process test transaction in the Development (Demo) environment.
These test cards can be used to submit test credit card
transactions using your POS application. For more information see
the Skipjack Integration Guide. NOTE that these virtual test cards
cannot be used to submit transactions in the Live (Production)
environment. Doing so will cause the settlement batch to be
corrupted during processing.
Key Exchange Questions (Debit Transactions Only)
Could you please explain what the "Key Exchange" process is and
when I should use it? A Key Exchange applies to debit transactions
only. The PIN entered by a Customer is encoded and encrypted inside
the PINpad with a set of MAC keys before it is transmitted via a
serial connection and over the Internet. The PINpad keys are
received from Global Payments Systems (relayed through the Skipjack
Transaction Network servers) and loaded into PINpad memory for use
with the next transaction. If the key loaded into the PINpad is
different from what the Processor sent for a specific transaction,
the transaction will be fail. (Keys are not synchronized). However
when this occurs only a single transaction will fail, because the
keys are automatically synchronized for the next transaction by the
inclusion of an updated key in the failure response. The next debit
transaction will succeed because a new key (which is synchronized)
is applied to the next debit transaction.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 29 of 73
I understand that Key Synchronization is automatic but what events
cause the Key Synchronization to fail? Key synchronization will
fail in the following cases:
• When a Reversal is performed on a transaction(s) using the
CReversals.Reverse method. • A new (not previously used) PINpad is
attached to the Point of Sale (POS) terminal for the first-time. •
The PINpad becomes disconnected during a transaction or during a
manual Key Exchange. (When the
plug is disconnected from the back of PINpad) after the request has
already been sent to Skipjack Transaction Network. (This should be
a rare event and need not necessarily be addressed in your
application.)
• The network becomes disconnected during the transaction or a Key
Exchange after the request has been sent to Skipjack Transaction
Network. (This should be a rare event and need not be necessarily
be addressed in your application.)
NOTE: Skipjack Financial Services has been told that keys may
expire if no activity is detected for few days, however Skipjack
Financial Services has not witnessed this happening in practice. If
keys are out of synchronization, the transaction will fail and the
(ISO Code/Bank Code) or 889/88 “MAC Synch Error” 898/63 “Bad MAC
value” error codes are received from Global Payment Systems.
However a new key is returned from the Processor in the response
data and this new key is applied to the next transaction and
therefore this Key Exchange and transaction should be successful.
NOTE: There is no need to perform a Key Exchange upon receiving
these ISO/bank codes errors.
What are some suggested guidelines for handling Key Exchanges in my
application? To prevent the first transaction from failing because
the keys may be out of synchronization, Skipjack Financial Services
strongly recommends that your application contains the logic
to:
• Perform a Key Exchange after using the CReversals.Reverse method
before attempting to process a new transaction.
• Perform a Key Exchange upon application start-up immediately
after initializing hardware. Whenever a new PINpad is connected the
user is required to restart the application which in turn
synchronizes the keys for use in the next transaction. NOTE: It is
a good idea to perform a Key Exchange upon startup of the POS
application. This will verify that the application, connected
hardware, and all transaction network components are functioning
properly and ready to process debit transactions. This ensures that
no issues, such as network connectivity problems, exist.
Is there any advantage to performing a Key Exchange before for each
transaction? No, in fact it would be a bad idea to perform Key
Exchange before every debit transaction. This is because not only
would it at least double the transaction processing time, it would
also increase the probability of the keys getting out of
synchronization should network or communications problem occur
during transaction processing.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 30 of 73
What is a MAC key and how is it used? The MAC (Message
Authentication Code) is an encryption algorithm which operates in
Cipher Block Chaining (CBC) Mode and is used in the encryption
between the PINpad and the Processor, for each transaction
submitted to the Processor. The MAC key is the key received from
the Processor during the KeyExchange method described previously or
as part of a previous transaction in a response to
FinancialRequest. The PINpad uses the MAC key it has for encrypting
the sensitive transaction data (including customer PIN number) to
be sent to the Processor. Upon receipt of the transaction data, the
Processor attempts to decrypt the transaction data using the MAC
key it holds. If decryption succeeds (the keys are synchronized)
further transaction processing is permitted. If decryption fails,
no further processing is done and an error message is returned to
the application for this transaction. With this error response a
new MAC key is returned for use in the next transaction,
effectively synchronizing the keys. If the MAC key does not match,
the error code 889/88 or 898/63 (ISO/Bank Code) “MAC key synch
error” is returned and this error printed on the receipt and the
PINpad message “CANNOT PROCESS PLEASE RETRY” is displayed.
Reversals and Reversal File Questions See also the “Reversals,
Reversal Records, Reversal Files, and Exception Handling” for more
details.
What is the Reversals File and how is it used? The Reversals File
contains the Reversal Records that are used as part of the process
to reverse transactions that cannot be completed because of
problems (exceptions) that occur during transaction processing. The
Reversals File is found by default at C:\SkipjackRetailAPI.bin and
cannot be edited directly, but must be updated using the Reversals
class methods. Normally, a Reversal Record is added to the
Reversals File when the POS application calls the
CAuthorize.FinancialRequest Method and is removed when a
transaction response is returned from the Skipjack Transaction
Network, is parsed, and successfully communicated to the PINpad (if
a PINpad was used in the transaction). This is done for each
financial transaction submitted. The Reversals process is performed
automatically by the Skipjack RetailAPI when called by
FinancialRequest method and is transparent to your POS application
and users in normal operation. When an exception is encountered
during financial transaction processing a Reversal must be
performed, as described below.
What is a “Reversal”? A Reversal is the process of reversing the
last action prior to an exception being detected by the Skipjack
RetailAPI. There are three types of Reversals and these are
explained in the “Reversals, Reversal Records, Reversal Files, and
Exception Handling” section. What causes automatic (transparent)
Reversals to fail? As mentioned in the previous questions the
CReversals class normally handles Reversals automatically and
therefore sophisticated Reversal handling mechanisms are not
required by your POS application. However in some cases automatic
Reversals can fail and additional Reversals attempts must be
initiated by your POS application.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 31 of 73
Causes of Automatic Reversal failures:
• When network communication failure occurs between the times a
financial transaction was submitted for processing and before a
response is received from the Skipjack Transaction Network.
Persistent network failures will mean Reversals cannot be
completed.
• When a transaction record in the Reversals File uses a non-unique
Order Number (a duplicate Order Number). In this case there is no
way for the Skipjack RetailAPI to determine which transaction
record to reverse and therefore automatic Reversal fails.
• Reversal has been Declined by Skipjack Financial Services or the
Payment Processor.
• A special type of failure occurs when the POS application uses an
Order Number which contains spaces
or non-alpha-numeric characters. Spaces and non-alpha-numeric
characters are removed from the Order Number when the transaction
is processed by the Skipjack Transaction Network. This will result
in a mismatch between the Order Number in the Reversals File and in
the Skipjack Merchant Register and the Reversals may be successful
but reverse an incorrect transaction, or none at all.
See the “Reversals, Reversal Records, Reversal Files, and Exception
Handling” section for more information about Reversals and the
methods used during Reversals.
How do I determine the cause of a Reversals failure for records
that are not automatically reversed? For a listing of the possible
Reversal Error Codes see CReversals.CRecord.REVERSAL_ERROR_CODES
for details. You should consider the following when interpreting
these Reversal Error Codes.
• Those records which return an Error Code below NONE may be
intermittent and it may be worthwhile to keep trying to reverse
these using the Reverse method.
• Those records above NONE are likely fatal and will require user
intervention.
What are some recommended implementation guidelines for handling
Reversals in my POS application? Skipjack Financial Services
suggests the following guidelines when handling Reversals in your
POS application.
• Allow automatic Reversals initiated by
CAuthorize.FinancialRequest to complete.
• Have an interface to which uses the
CReversals.Reverse(reallybignumber) to serve as the final attempt
to reverse those Reversal Records which can be reversed
automatically to minimize the number of transactions that must be
manually handled by POS application-initiated and Manual Reversal
attempts.
• Design your POS application to display, using the CReversals.Show
method, Reversals in the Reversal
File on a regular basis, such as application startup and shutdown.
This approach will help prevent Reversals Records from being
forgotten by the POS application and users.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 32 of 73
• You may want to include an interface in your POS application to
export transaction records that are not automatically Reversed from
the Reversal File to another file and remove each exported record
from the Reversal File. Upon removal from the Reversal File the
user should inspect each transaction to determine the reason for
the reversal failure and perform the appropriate actions. Manual
Reversals require the Merchant to call the Processor for each
Reversal Record that could not be reversed either automatically or
through the actions described above. The POS application uses the
CReversals.Show method to display the Reversal File records in the
POS application for such cases.
The Example Applications included with the API uses an attempt
threshold of 100 for CReversals.Reverse(). Is this a good starting
point value for us to use in our application? Does the setting of
this value depend on how many times we call CReversals, or is the
DLL retrying the Reversal in the background all the time? The
current Skipjack RetailAPI DLL logic is that if transaction fails
due to network or PINpad problems, the DLL calls Reverse(1)
internally before returning from FinancialRequest. This means it
will attempt to Reverse all transactions from the Reversal File
that have not yet been attempted to be reversed, including the most
recently failed transaction. The rationale for just a single (1)
attempt is that if something can't be fixed easily, it should be
better addressed offline (and this is what the Reversals class is
for). Overall, the Reverse() method is a very primitive high-level
approach. You may choose in your software to go through Reversal
records one-by-one and look at their ReversalErrorCode field.
ReversalErrorCodes with values above NONE are fatal, meaning that
the transaction is likely never going to be reversed no matter how
many times you attempt to reverse the transaction. You may want to
have your application export those with values above NONE to a file
or display them on-screen to allow user to check them
manually.
For testing purposes, is there a foolproof way to generate entries
in the Reversals File? The only ways we know presently involve
complicated timing. The Skipjack RetailAPI adds a transaction to
the Reversals File just before it sends the transaction data to the
Skipjack Transaction Network. The API removes the entry in the
Reversal File immediately after receiving and parsing the response
received from the Skipjack Transaction Network and successfully
communicating response this to the PINpad (if a PINpad was used) .
Anything that causes a disruption of this process will result in a
Reversal failure. You can disconnect the network to disrupt the
communication between the API (assuming a PINpad is used in the
transaction) and the Skipjack Transaction Network during
transaction processing just after the transaction is sent to the
Skipjack Transaction Network to cause Automatic Reversal failures.
For testing purposes, you may keep the network disconnected all the
time if you don't care whether the transaction is received by
Skipjack Financial Services and you wish to test the Reversals
handling mechanisms of your POS application. Alternatively, you may
try to copy the Reversals File (located by default at
C:\SkipjackRetailAPI.bin) into a separate thread shortly after you
call CAuthorizeFinancialRequest() method and then restore it after
the FinancialRequest() is returned to create Reversal Records in
the Reversals File.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 33 of 73
Sequence Number File Questions (Debit Only)
What is the Sequence Number File and how is it used by my
application? The Sequence Number File
(SkipjackRetailAPISequence.txt) is a local file that resides on
your PC and contains the Sequence Number which is required by the
Processor (Global Payment Systems) to uniquely identify each debit
transaction submitted to it for processing. No user intervention is
required because the Skipjack RetailAPI handles all aspects of the
Sequence Number and the Sequence Number File maintenance. The
Sequence Number is not used for credit card transactions. The
Sequence Number ranges from 001 to 999 and increments by one (1)
each time a financial transaction (Purchase/Return) is completed
successfully. Once the Sequence Number reaches 999 it resets to
001, ad infinitum. If an incorrect Sequence Number is sent in a
transaction request, Global Payment Systems will respond with a
Response Code of (ISO/Global Code) of 899/84 (Incorrect sequence
number), as well as the correct sequence number for use with the
next transaction, effectively synchronizing the Sequence Number.
Any Sequence Error code is printed on the Customer and Merchant
receipts.
Receipt Questions
What information is required on the Customer and Merchant receipt?
The Skipjack RetailAPI contains a class to handle the formatting,
printing, and saving of Merchant and Customer copies of receipts
for each debit and credit card transaction. See also the “Receipt
Questions” section for more details. For debit card transactions
only, the debit Processor (Global Payment Systems) strictly defines
the minimum requirements of the information that must be displayed
on each printed Customer and Merchant receipt for English and
French versions of each receipt. When your application is sent to
Global Payment Systems for Acceptance Testing, the receipt
formatting is scrutinized. Receipts created for credit card
transactions are produced in accordance with recommendations and
guidelines provided by the Credit Card Associations (using PCI
Certification Standards) and your credit card Acquirer. For
information about these the recommendations and requirements for
receipt formatting contact your Acquirer. A copy of the PCI
Certification standards is available in PDF format at from Skipjack
Financial Services. See the “Obtaining Additional Development
Information and Documentation” for details about obtaining this
document.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 34 of 73
Do I have to submit my receipts to Global Payment Systems as part
of the User Acceptance Testing process? Yes, you must submit sample
receipts generated by a select number of test cases to Global
Payment Systems as part of their User Acceptance Testing. These
must be submitted after the test cases are completed. Global
Payment Systems states that it may take up to 4 weeks to review the
receipts and results of the User Acceptance Test for your
application prior to issuing your Acceptance Letter for your POS
application. For more information about the User Acceptance Test
process, see “Application Development Lifecycle Using the Skipjack
RetailAPI” and the “Certification Questions” sections for more
details about User Acceptance Test.
Certification Questions
Do I need to Certify my POS application with Global Payment Systems
before I can actually process Live debit transactions? No. The
Skipjack RetailAPI has already been Certified by Global Payment
Systems (GPS) so further certification is not required by your
organization. However, you still must complete GPS Acceptance
Testing for your application before you can process Live
transactions (Production environment). Acceptance testing is less
stringent than Certification Testing but it is used to ensure that
your application is fully compliant with the requirements of Global
Payment Systems for processing transactions. For details about GPS
Acceptance Testing process see the “Preparing for the Global
Payment Systems User Acceptance Test” section for details..
Serial Number Questions
When are the HTML Serial Number and Developer Serial Numbers used?
The Developer and HTML Serial Numbers are loaded into the
CPOSConfiguration class using the
CPOSConfiguration.LoadSerialNumbers method and the Serial Numbers
are later used as part of the CPOSConfiguration object to process
transactions (using CAuthorize.FinancialRequest method), perform
Key Exchange (CAuthorize.KeyExchange method) and for transaction
Reversals. The HTML and Developer Serial Numbers are also used to
perform Get and Change Status (see CTransactions class) methods.
The Developer Serial Numbers are also used for encrypting Reversal
File records. There are a total of four Serial Numbers used by the
application for each environment (Development (Test) and Production
(Live): HTML Credit Serial Number, HTML Debit Serial Number,
Developer Credit Serial Number, and Developer Debit Serial Number.
Please check to be sure that you are using the correct Serial
Numbers, as assigned by Skipjack Financial Services, appropriately
used for the environment you are working in, either Development or
Production.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 35 of 73
I’ve recently changed my Serial Numbers (HTML and Developer Serial
Numbers) that I am using. Now I am now receiving a new error
message, a REVERSAL_FILE_ERROR message. What is going on here and
how do I fix this problem? This error occurs any time you change
the Developer Serial Number(s) that you use with Skipjack
RetailAPI. The Developer Serial Number(s) are used as part of
encryption/decryption process and therefore this error occurs
because the Reversal File is encrypted with a different Development
Serial Number(s). If you do not care about the Reversal records in
the Reversal File, you can remedy this problem by manually deleting
the Reversal File, SkipjackRetailAPIReversals.bin, from your
computer (by default at C:\SkipjackRetailAPIReversals.bin).
Normally this is not an issue in the test environment. However if
you do need to keep the Reversal File records you must rename the
SkipjackRetailAPIReversals.bin file, and later return the
SkipjackRetailAPIReversals.bin file the original name and provide
the original Serial Numbers used with this file in order to access
the Reversals records. When the FinancialRequest method is called a
new Reversals File is created to replace the deleted or renamed
file. In this new file the new Developer Serial Number(s) will be
used for the Encryption/Decryption and the error will not be
displayed.
I am getting the error “Error length serial number” (-39) What is
causing this? Double-check your credentials (Serial Numbers) and
resubmit the transaction using the most current credentials. This
error also occurs when you are trying to use a HTML Serial Number
intended for a Development Account on a Production system or vice
versa.
Is it OK to send empty strings for the Serial Numbers for
transaction types we do not intend to use in our application? Yes,
you send empty Serial Numbers to the Skipjack Transaction Network.
The Skipjack RetailAPI allows you to choose to support either one
or both transaction types (credit card and/or debit card). You need
only send the applicable Serial Numbers associated with the
transaction type your POS application supports.
How do I obtain an HTML and Developer Serial Number from Skipjack
Financial Services so that I can begin testing? To obtain a free
Skipjack Development Account from Skipjack Financial Services visit
http://www.skipjack.com/developer_account or call the toll free
Skipjack Financial Services support number 1-888-368-8507.
Remember, in order to submit Live (Production) debit transactions
for processing to the Skipjack Transaction Network using the
Skipjack RetailAPI, you must have a Merchant Account with Global
Payment Systems for accepting Interact debit cards (Canadian
PIN-based debit cards). For more information, see the “How do I
obtain my test cards?” and “Application Development Lifecycle Using
the Skipjack RetailAPI” sections for details.
Page 36 of 73
OK, I have my Skipjack Financial Services Test Account. Can I use
the Skipjack RetailAPI and begin my development and submit
transactions for processing? You will not be able to submit debit
transactions to Global Payment Systems without a PINpad and debit
test cards. You must obtain these directly from Global Payment
Systems. See also “How do I obtain my test cards?”. In the interim,
you may begin your development process using test credit card
numbers either entered manually into your application or swiped by
a supported swipe device to submit credit card transactions using
the Skipjack RetailAPI. You can obtain test credit card numbers
from Skipjack Financial Services.
Unique Order Number Questions
Why should I use a unique Order Number? A unique Order Number is
intended to serve as a unique identifier for the transaction which
allows the Skipjack RetailAPI to identify the transaction without
ambiguity. Not using a unique Order Number means that:
• Skipjack RetailAPI Reversals will fail if an exception occurs
because the API will not know which transaction to reverse and may
reverse the wrong record or fail to automatically to reverse any
records which increases the workload required to handle Reversals.
See also “Reversals and Reversal File Questions”.
• You will have to perform additional steps to identify the
transaction record for advanced transaction (optional) processing
methods.
• The incorrect transaction may be reversed in certain
circumstances. The Skipjack RetailAPI includes a method to generate
a unique Order Number and it is highly recommended that this is
used with your POS application. For more information on the use of
the unique Order Number, see the
RetailLib.GenerateUniqueOrderNumber method.
If I do decide to generate my own Order Number are there any other
additional restrictions? In cases when you do decide to use your
own order number generation the following additional constraint
applies:
• Order Number must use alpha-numeric characters ONLY. Spaces,
special characters or restricted characters (!@#$%, etc) are
automatically removed during transaction processing by the Skipjack
Transaction Network and will result in the automatic Reversals
working incorrectly and Reversal Records to be removed from the
Reversal File without the actual Reversal being performed. See also
“Reversals and Reversal File Questions”.
© 2008 Skipjack Financial Services Skipjack Retail API Integration
Guide
Page 37 of 73
I am attempting to process test Interac transactions, and I keep
getting the error message stating that I am not using a unique
Order Number. I'm using the "GenerateUniqueOrderNumber" call in the
RetailLib. Is there something wrong with the Interac testbed? If
you receive NOT_UNIQUE_ORDER_NUMBER from the FinancialRequest
method this likely means that the Order Number provided for
transaction is null, zero length, or the record with such Order
Number already exist in the Reversal File. You must use a unique
order number for each transaction request. This error can also
occur, for example, if you call FinancialRequest twice on the same
Authorize object. You should never reuse the Authorize object, even
when the first FinancialRequest call was Declined.
Payment Processor Questions
What Payment Processors are currently supported by the Skipjack
RetailAPI. Are there any plans to add others? Currently for debit,
the Skipjack RetailAPI is supported by Global Payment Systems in
Canada only for processing Canadian, PIN-based, debit card
transactions. Skipjack Financial Services will soon be adding other
debit payment