skipjack retailapi integration guide - cyberauthorize.com · © 2008 skipjack financial services...

Skipjack RetailAPI Integration Guide

2008 Skipjack Financial Services Skipjack Retail API Integration Guide

Page 2 of 73

Table of Contents About this Document .............................................................................................................................................. 4

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 Whats 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


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

Date Version Comments

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


Page 5 of 73

Documentation Conventions The information presented in this guide uses the following text conventions throughout.

Convention Usage Example

Blue courier text

Code Snippets, HTML Code, Skipjack Transaction Network Request Response

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: &,%.*

https://www.skipjack.com/


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.

http://www.skipjack.com/developers.aspx?cmsphid=85844789|7785657|2088223http://imgserver.skipjack.com/imgServer/5293710/skipjack_integration_guide.pdfhttp://imgserver.skipjack.com/imgServer/5293710/Skipjack%20Merchant%20Reporting%20Guide.pdfhttp://imgserver.skipjack.com/imgServer/5293710/merchant_user_guide_v2.5.pdfhttp://www.skipjack.com/http://msdn2.microsoft.com/en-us/netframework/aa731542.aspx


Page 7 of 73

Whats 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\\Local Settings\Application Data\\. 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.


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.

http://www.skipjack.com/developers.aspx?cmsphid=85844789|7785657|2088223


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.


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

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

\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).

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


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.


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.


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.


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 Merchants 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


Page 15 of 73

Key Transaction Processing Features Supported Supports Interac Canadian PIN-based debit cards and all credit cards (Visa, MasterCard, American

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


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.

http://www.skipjack.com/developers.aspx?id=14118964|5168739|2088223&menu=15611712|1362762|2094448https://secure.skipjack.com/


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.


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.


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 Skipjacks Solution Finder to maximize your business

opportunities. Registration in Solution Finder is free and provides Skipjacks 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.

http://www.skipjack.com/developers.aspx?cmsphid=85844789|7785657|4559040https://secure.skipjack.com/partners/search.aspxmailto:[email protected]


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.


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.


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.


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 Modifies the hardware initialization settings by calling the CPOSConfiguration.Settings fields, OR

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.


Page 24 of 73

4. The POS application analyzes the transaction responses from the CAuthorizeFinancialRequest method. When the FinancialRequest Method is SUCCESSFUL, the POS application may check the following properties and fields:

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.


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.


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


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.


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.


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.


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.


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.


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.


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.


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.


Page 35 of 73

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

http://www.skipjack.com/developers.aspx?id=14118964|5168739|853507&menu=15611712|1362762|2094448


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 orde