Skipjack Integration Guide

Transcription

Skipjack Integration Guide
Skipjack
Integration
Guide
 2009 Skipjack Financial Services
Skipjack Integration Guide
Table of Contents
About this Document ............................................................................................................................. 9
Copyright Notice ................................................................................................................................................................. 9
Trademark Notice ............................................................................................................................................................... 9
Interchange Qualifications and Transaction Rates ............................................................................................................. 9
Publication History ............................................................................................................................................................ 10
Documentation Conventions............................................................................................................................................. 12
Definitions of Variable Types ........................................................................................................................................ 13
Permitted Syntax for Variable Fields ............................................................................................................................ 13
Obtaining Additional Information....................................................................................................................................... 13
Obtaining Referenced Documents ............................................................................................................................... 14
Contacting Skipjack Financial Services ............................................................................................................................ 14
Obtaining a Developer Account with Skipjack Financial Services.................................................................................... 14
Obtaining a Merchant Account from a Financial Institution .............................................................................................. 14
Getting Started: Application Development Lifecycle ........................................................................... 15
Overview: Recommended Development Process ............................................................................................................ 15
Payment Processors Supported by Skipjack Financial Services ..................................................................................... 16
Payment Processor Information for Canadian Merchant Accounts and Payment Processors ........................................ 17
Connection Types ............................................................................................................................... 18
Direct Skipjack API Posts ................................................................................................................................................. 18
Installed API Posts ............................................................................................................................................................ 18
Batch Posts ....................................................................................................................................................................... 18
Level I, II, III Card Data Transaction Overview.................................................................................... 19
Level I Transactions .......................................................................................................................................................... 19
Level II Transactions ......................................................................................................................................................... 19
Example of Level II Data Request String ..................................................................................................................... 20
Level III Transactions ........................................................................................................................................................ 20
Example of Level III Data Request String .................................................................................................................... 21
Core & Supplementary Transaction Methods ..................................................................................... 22
Core Methods ................................................................................................................................................................... 22
Supplementary Methods ................................................................................................................................................... 22
Authorize and AuthorizeAPI Methods ................................................................................................. 23
Authorize ........................................................................................................................................................................... 23
Post-Back Locations for Authorize Method .................................................................................................................. 23
AuthorizeAPI ..................................................................................................................................................................... 23
Transaction Requests for Authorize and AuthorizeAPI .................................................................................................... 23
Details for Submitting Transaction Requests for Authorize and AuthorizeAPI ............................................................ 23
Request Variables for Authorize and AuthorizeAPI Methods....................................................................................... 24
Transaction Examples for Authorize and Authorize API Methods.................................................................................... 38
Request Example 1: Authorize ..................................................................................................................................... 38
Response Example 1: Authorize .................................................................................................................................. 39
Request Example 2: AuthorizeAPI ............................................................................................................................... 39
Response Example 2: AuthorizeAPI ............................................................................................................................ 39
Request Example 3: TSYS Credit Card Balance Inquiry ............................................................................................. 40
Response Example 3: TSYS Credit Card Balance Inquiry .......................................................................................... 40
Response Variables for Authorize and AuthorizeAPI Methods ........................................................................................ 41
Response Variables for Authorize and AuthorizeAPI Methods .................................................................................... 41
Response Variables Returned when ResponseFlags Variable Sent in Transaction Request..................................... 48
szPOSEntryMode Return Variable Values by Position ................................................................................................ 53
Example Using ResponseFlags Request Variables ......................................................................................................... 54
Example 1 ..................................................................................................................................................................... 54
Example 2 ..................................................................................................................................................................... 54
Development Notes for AuthorizeAPI Response Handling .............................................................................................. 55
Page 2
 2009 Skipjack Financial Services
Skipjack Integration Guide
Annotated Examples for Authorize and AuthorizeAPI ......................................................................... 56
Assumptions ..................................................................................................................................................................... 56
Example 1: Authorization Successful for a Basic Credit Card Transaction ...................................................................... 56
Interpretation ..................................................................................................................................................................... 56
Example 2: Authorization Decline for a Basic Transaction ............................................................................................... 58
Interpretation ..................................................................................................................................................................... 58
Example 3: Authorization Failure for a Basic Transaction ................................................................................................ 59
Interpretation ..................................................................................................................................................................... 59
Example 4: Authorization Successful with AVS Filtering Off ............................................................................................ 60
Interpretation ..................................................................................................................................................................... 60
Example 5: Authorization Successful with AVS Filtering On ............................................................................................ 61
Interpretation ..................................................................................................................................................................... 61
Example 6: Authorization Failed with AVS Filtering On.................................................................................................... 62
Interpretation ..................................................................................................................................................................... 62
Example 7: Authorization Successful with CVV matching for Visa and MasterCard ....................................................... 63
Interpretation ..................................................................................................................................................................... 63
Example 8: Authorization Failure with CVV not matching for Visa and MasterCard ........................................................ 64
Interpretation ..................................................................................................................................................................... 64
Example 9: Authorization Success with CVV matching for Amex or Discover ................................................................. 65
Interpretation ..................................................................................................................................................................... 65
Example 10: Authorization Failure because of CVV not matching for Amex or Discover ................................................ 66
Interpretation ..................................................................................................................................................................... 66
Get Transaction Status Method .......................................................................................................... 67
Description.................................................................................................................................................................... 67
When Used ................................................................................................................................................................... 67
See Also ....................................................................................................................................................................... 67
Transaction Variables for the Get Transaction Status Method ......................................................................................... 67
Details for Submitting Get Transaction Status Method Requests ................................................................................ 67
Request Variables for Get Transaction Status ................................................................................................................. 68
Response Variables for Get Transaction Status .............................................................................................................. 69
Interpreting the Get Transaction Status Response Messages .................................................................................... 69
Examples for Get Transaction Status Method .................................................................................................................. 72
Request Example 1: Get Transaction Status Method specifying szDate..................................................................... 72
Response Example 1: Get Transaction Status specifying szDate ............................................................................... 72
Request Example 2: Get Transaction Status Method specifying szOrderNumber ...................................................... 73
Response Example 2: Get Transaction Status specifying szOrderNumber ................................................................ 73
Change Transaction Status Method.................................................................................................... 74
Description.................................................................................................................................................................... 74
When Used ................................................................................................................................................................... 74
Change Status Functionality Matrix.............................................................................................................................. 75
See Also ....................................................................................................................................................................... 76
Details for Submitting Change Transaction Status Method Requests ......................................................................... 76
Transaction Requests for Change Transaction Status Method........................................................................................ 77
Development Notes for Change Transaction Status Method ....................................................................................... 97
Response Variables for the Change Transaction Status Method .................................................................................... 98
Interpreting the Change Transaction Status Response Records ................................................................................. 98
Examples for Change Transaction Status Method ......................................................................................................... 102
Request Example 1: Change Transaction Status: Credit – Specifying szOrderNumber (Error)................................ 102
Response Example 1: No Records Found for Order Number (Error) ........................................................................ 102
Request Example 2: Change Transaction Status (Error - Incorrect Amount for Credit) ............................................ 102
Response Example 2: Change Transaction Status (Error- Incorrect Amount for Credit) .......................................... 103
Request Example 3: Change Transaction Status – SplitSettle specifying szOrderNumber ...................................... 103
Response Example 3: Change Transaction Status – SplitSettle ............................................................................... 103
Request Example 4: Change Transaction Status – Credit specifying szOrderNumber ............................................. 103
Response Example 4: Change Transaction Status Credit – Error: Status Mismatch ................................................ 103
Page 3
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 5: Change Transaction Status – Split Settle specifying szOrderNumber ..................................... 104
Response Example 5: Change Transaction Status – Successful: Split Settle........................................................... 104
Request Example 6a and 6b: Change Transaction Status: Authorize ....................................................................... 104
Request Example 7: ChangeStatus:CreditEx ............................................................................................................ 105
Response Example 7: ChangeStatus:CreditEx ......................................................................................................... 105
Request Example 8: Change Transaction Status: AuthorizeAdditionalEx ................................................................. 105
Response Example 8: ChangeStatus: AuthorizeAdditionalEx ................................................................................... 105
Supplemental Transaction Methods.................................................................................................. 106
Recurring Payments Overview.......................................................................................................... 107
Description .................................................................................................................................................................. 107
Development Notes about Recurring Payments Transactions .................................................................................. 107
Recurring Payment Methods; ..................................................................................................................................... 108
See Also: .................................................................................................................................................................... 108
Add Recurring Payment Method ....................................................................................................... 109
When Used ................................................................................................................................................................. 109
Submitting Requests for Add Recurring Payments .................................................................................................... 109
See Also ..................................................................................................................................................................... 109
Transaction Requests for the Add Recurring Payments Method ................................................................................... 109
Transaction Responses for Add Recurring Payments Method ...................................................................................... 114
Interpreting the Response Records for Add Recurring Payments Method ................................................................ 114
Response Records Variables for Add Recurring Payments Method ......................................................................... 114
Examples for Add Recurring Payments Method............................................................................................................. 115
Request Example 1: Add Recurring Payments Request ........................................................................................... 115
Response Example 1: Add Recurring Payments Records – Successful ................................................................... 115
Request Example 2: Add Recurring Payments Request ........................................................................................... 116
Response Example 2: Add Recurring Payments Records – Error: Starting Date ..................................................... 116
Edit Recurring Payments Method ..................................................................................................... 117
When Used ................................................................................................................................................................. 117
Submitting Requests for Edit Recurring Payments .................................................................................................... 117
See Also ..................................................................................................................................................................... 117
Transaction Requests for Edit Recurring Payments Method ......................................................................................... 117
Transaction Responses for Edit Recurring Payments Method ....................................................................................... 121
Interpreting the Response Records for Edit Recurring Payments Method ................................................................ 121
Response Records (Header Record) Variables for Edit Recurring Payments Method ............................................. 121
Examples for Edit Recurring Payments Method ............................................................................................................. 122
Request Example 1: Edit Recurring Payments Request............................................................................................ 122
Response Example 1: Edit Recurring Payments – Success...................................................................................... 122
Request Example 2: Edit Recurring Payments .......................................................................................................... 123
Response Example 2: Edit Recurring Payments – Error: Missing szPaymentId ....................................................... 123
Delete Recurring Payment Method ................................................................................................... 124
Submitting Requests for Delete Recurring Payment Method..................................................................................... 124
See Also ..................................................................................................................................................................... 124
Transaction Requests for Delete Recurring Payment Method ....................................................................................... 124
Transaction Responses for Delete Recurring Payments Method .................................................................................. 125
Interpreting the Response Records for Delete Recurring Payments Method ............................................................ 125
Response Records (Header Record) Variables for Delete Recurring Payments ...................................................... 126
Examples for Delete Recurring Payment Method .......................................................................................................... 126
Request Example 1: Delete Recurring Payments Request specifying szPaymentId ................................................ 126
Response Example 1: Delete Recurring Payment specifying szPaymentId – Successful ........................................ 126
Request Example 2: Delete Recurring Payments Request specifying szTransactionDate ....................................... 127
Response Example 2: Delete Recurring Payment specifying szTransactionDate – ................................................. 127
Successful .................................................................................................................................................................. 127
Request Example 3: Delete Recurring Payments Request specifying szTransactionDate ....................................... 127
Response Example 3: Delete a Recurring Payment – Error: Failed Deleting............................................................ 127
Page 4
 2009 Skipjack Financial Services
Skipjack Integration Guide
Get Recurring Payment Information Method ..................................................................................... 128
Description.................................................................................................................................................................. 128
When Used ................................................................................................................................................................. 128
See Also ..................................................................................................................................................................... 128
Transaction Requests for Get Recurring Payment Information ...................................................................................... 128
Submitting Requests for Get Recurring Payment Information ................................................................................... 128
Transaction Requests for Get Recurring Payments Method .......................................................................................... 128
Transaction Response for Get Recurring Payment Information ..................................................................................... 129
Interpreting the Response Records for Get Recurring Payment Information Method ............................................... 129
Status Records (Header Record) Variables for Get Recurring Payment Information Method................................... 130
Interpreting the Response Records (Data Records) for Get Recurring Payment Information Method ...................... 131
Response Records (Data Records) returned for Get Recurring Payment Method Information Method ................... 131
Examples for Get Recurring Payment Information Method ............................................................................................ 134
Request Example 1: Get Recurring Payments Request specifying szTransactionDate............................................ 134
Response Example 1: Get Recurring Payment Information specifying szTransactionDate ...................................... 134
Request Example 2: Get Recurring Payments Request specifying szPaymentId ..................................................... 135
Response Example 2: Get Recurring Payment Information specifying szPaymentId – Success.............................. 135
Request Example 3: Get Recurring Payments Request specifying szPaymentId ..................................................... 135
Response Example 3: Get Recurring Payment Information – Error: No Records Found .......................................... 135
Transaction Settlement Methods ...................................................................................................... 136
Available Only Though Merchant Services ................................................................................................................ 136
Performed using Batch Settlement API Methods ....................................................................................................... 136
Close Current Open Batch Method ................................................................................................... 137
Description.................................................................................................................................................................. 137
When Used ................................................................................................................................................................. 137
See Also ..................................................................................................................................................................... 137
Submitting Requests for the Close Current Open Batch Method .............................................................................. 137
Transaction Request Variables for Close Current Open Batch Method .................................................................... 138
Interpreting the Transaction Responses for the Close Current Open Batch Method ................................................ 138
Request Example 1: Close Current Open Batch Method........................................................................................... 139
Response Example 1: Close Current Open Batch Method – Success ...................................................................... 139
Request Example 2: Close Current Open Batch Method........................................................................................... 139
Response Example 2: Close Current Open Batch Method – Error (Parameter Missing) .......................................... 140
Get Batch Settlement Status Method ................................................................................................ 141
Description.................................................................................................................................................................. 141
When Used ................................................................................................................................................................. 141
Submitting Requests for the Get Batch Settlement Status Method ........................................................................... 141
Transaction Request Variables for the Get Batch Settlement Status Method ............................................................... 142
Transaction Responses for the Get Batch Settlement Status Method ........................................................................... 143
Transaction Responses for the Get Batch Settlement Status Method ....................................................................... 143
Request Example 1: Get Batch Settlement Status Method ....................................................................................... 146
Response Example 1 : Get Batch Settlement Status Method – Success .................................................................. 146
Request Example 2: Get Batch Settlement Status Method ....................................................................................... 146
Response Example 2: Get Batch Settlement Status Method – Failure ..................................................................... 146
Batch File Methods for Transaction Processing ................................................................................ 147
When Used ................................................................................................................................................................. 147
Mechanisms Supported for Batch File Uploads ......................................................................................................... 147
How Batch Upload Files are Processed and Queued ................................................................................................ 147
Enabling Batch File Processing Privileges on a Merchant Account........................................................................... 148
Development and Usage Notes for Batch Uploading Methods .................................................................................. 148
Workflow for Processing Batch Upload Files ............................................................................................................. 148
Transaction Requests for Batch File Uploads ................................................................................................................ 149
Formatting Requirements of Name-Value Pairs by Batch Method Type........................................................................ 150
Formatting Examples by Method Types ......................................................................................................................... 150
Formatting for Batch Authorization Method Request ................................................................................................. 150
Page 5
 2009 Skipjack Financial Services
Skipjack Integration Guide
Formatting for Get Transaction Status Method Request............................................................................................ 151
Formatting for Change Transaction Status Request .................................................................................................. 151
Formatting for Add Recurring Payments Request ..................................................................................................... 151
Formatting for Edit Recurring Payments .................................................................................................................... 152
Formatting for Delete Recurring Payments ................................................................................................................ 152
Transaction Responses for Batch Upload Methods ....................................................................................................... 152
Check Batch File Status Method ....................................................................................................... 153
Description.................................................................................................................................................................. 153
When Used ................................................................................................................................................................. 153
See Also ..................................................................................................................................................................... 153
Details for Submitting Transaction Requests for Check Batch File Status Method ................................................... 153
Transaction Requests for Check Batch File Status Method ........................................................................................... 153
Transaction Response for Check Batch File Status Method .......................................................................................... 155
Request Example 1: Check Batch File Status Specifying Date Range ..................................................................... 157
Response Example 1: Check Batch File Status ......................................................................................................... 157
Modify Batch File Status Method ...................................................................................................... 158
Description.................................................................................................................................................................. 158
When Used ................................................................................................................................................................. 158
Transaction Requests for Modify Batch File Status Method .......................................................................................... 158
Request Variables for Modify Batch File Status Method ............................................................................................ 158
Transaction Response for Modify Batch File Status Method ......................................................................................... 159
Request Example 1: Modify Batch File Status ........................................................................................................... 160
Response Example 1: Modify Batch File Status – Success....................................................................................... 160
Request Example 2: Modify Batch File Status ........................................................................................................... 160
Response Example 2 Modify Batch File Status – Error ............................................................................................. 160
Get Batch File Response Method ..................................................................................................... 161
Description.................................................................................................................................................................. 161
Request Variables for Get Batch File Response Method ............................................................................................... 161
Transaction Responses for Get Batch File Response – Batch Authorize Transactions ................................................ 162
Get Batch File Transaction Response for Batch Authorize Transactions ...................................................................... 162
Response Example 1: Get Batch File Response for Batch Authorization – No Errors .............................................. 162
Example 2: Batch Authorization Response String – Error ......................................................................................... 162
Echo Utility ........................................................................................................................................ 163
When Used ................................................................................................................................................................. 163
Details for Submitting an Echo Utility Request ........................................................................................................... 163
Transaction Requests for the Echo Utility ...................................................................................................................... 163
Transaction Responses for the Echo Utility .................................................................................................................... 164
Response Example: Authorize using the Debugging Utility ....................................................................................... 164
Debugging Utility ............................................................................................................................... 165
When Used ................................................................................................................................................................. 165
Details for Submitting a Debugging Utility Request ................................................................................................... 165
Transaction Requests for Debugging Utility ................................................................................................................... 165
Transaction Responses for Debugging Utility ................................................................................................................ 165
Response Example: Authorize using the Debugging Utility ....................................................................................... 165
Authorization Logic and Appropriate Failsafe Mechanisms .............................................................. 166
See Also ..................................................................................................................................................................... 168
Scenarios .......................................................................................................................................... 169
Scenario 1: Split Authorization Scenario ........................................................................................................................ 169
Scenario 2: Refunds and Voids Scenario ....................................................................................................................... 174
Scenario 3: Recurring Payments Scenario ..................................................................................................................... 176
Scenario 4: Batch Settlement Scenario .......................................................................................................................... 179
Scenario 5: Batch File Upload Scenario ......................................................................................................................... 180
Re-Authorization Scenarios ............................................................................................................................................ 182
Usage Notes Regarding the Following Scenarios:..................................................................................................... 182
Page 6
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 6A – Authorize Original Amount, Settle Different Amount............................................................................... 183
Advantages ................................................................................................................................................................. 183
Disadvantages ............................................................................................................................................................ 183
Scenario 6B – Authorize Original Amount, Change Status Authorize Additional ........................................................... 185
Advantages ................................................................................................................................................................. 185
Disadvantages ............................................................................................................................................................ 185
Scenario 6C – Authorize Original Amount, Change Status: Authorize........................................................................... 188
Advantages ................................................................................................................................................................. 188
Disadvantages ............................................................................................................................................................ 188
Appendix A: Permitted Country Code Values ................................................................................... 190
Appendix B: Address Verification System (AVS) Checking............................................................... 198
AVS Filtering within the Skipjack Transaction Network .................................................................................................. 198
Development Notes for AVS and AVS Filtering.............................................................................................................. 199
AVS Codes by Card Type............................................................................................................................................... 200
AVS Response Codes for International and Domestic Credit Cards ............................................................................. 201
AVS Code Handling for International and Domestic Transactions ................................................................................. 201
Use of Canadian Postal Codes in AVS Checks ............................................................................................................. 201
Appendix C: CVV and Interpreting CVV Return Codes ..................................................................... 202
How CVV Code Checking is Used in Transactions ........................................................................................................ 202
CVV Code Locations by Card Type ................................................................................................................................ 203
CVV Response Codes for Visa and MasterCard/Eurocard ............................................................................................ 203
Appendix D: Avoiding Duplicate Transactions .................................................................................. 204
Development Notes on Avoiding Duplicate Transactions............................................................................................... 204
Appendix E: Configuring Level II Transaction Data........................................................................... 205
Development Notes for Level II Data .............................................................................................................................. 205
Appendix F: TSYS PIN-based Debit Transactions Information ......................................................... 206
Example Code Snippets ................................................................................................................................................. 207
Request Variables ...................................................................................................................................................... 207
Example Response String .......................................................................................................................................... 208
Response Example: Authorize ................................................................................................................................... 208
Development Notes for the TSYS PIN-based Debit Service .......................................................................................... 208
Appendix G: Blind Credits ................................................................................................................. 209
Prerequisites and Requirements for Performing Blind Credits ....................................................................................... 209
szReturnCode Error Messages Associated with Blind Credits ....................................................................................... 210
Blind Credits versus Change Status: Credit ................................................................................................................... 210
Configuring the Skipjack Merchant Account to Permit Blind Credits .............................................................................. 211
Appendix H: Using Trackdata Details in Transactions ...................................................................... 212
Recommended Trackdata Hardware .............................................................................................................................. 212
Trackdata Information and Examples ............................................................................................................................. 212
Trackdata Capture, Formatting and Usage Notes .......................................................................................................... 213
Appendix I: Unique Order Numbers .................................................................................................. 214
How to Identify Transactions When Duplicate Order Numbers Exist ............................................................................. 214
Other Transaction Methods Using Order Number as a Required Variable................................................................ 215
Configuring the Reject Duplicate Order Numbers Option for a Merchant Account .................................................... 215
Appendix J: Using Soft Indicators with Paymentech and TSYS ........................................................ 217
Soft Indicator Implementation Guidelines ....................................................................................................................... 217
Setting Merchant Services Vendor Preferences to Support Soft Indicators ................................................................... 217
Appendix K: Orderstring Variables .................................................................................................... 219
Example: OrderString Variable Formatting ................................................................................................................ 220
OrderString and lvl3orderstring variable Developer Notes......................................................................................... 220
Appendix L: Naming Conventions for “Dummy Values” in Required Variables ................................. 221
Suggested Values for “Dummy Values” for Required Variables ................................................................................ 221
Methods Using the Dummy Variables ........................................................................................................................ 221
Page 7
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix M: Transaction IDs, Audit IDs and the Transaction Lifecycle ............................................ 222
Development Notes on Audit IDs and Transaction IDs .................................................................................................. 222
Appendix N: Test Cards Used with Development Accounts ............................................................. 223
Test Cards for TSYS and Global as Payment Processor .......................................................................................... 223
Test Cards for Fifth Third Processing Solutions (FTPS) as Payment Processor....................................................... 224
Appendix O: Notes for Processing Level II and Level III Data........................................................... 225
Appendix P: Usage Notes for the Enhanced TSYS Credit Card Processing Features ..................... 226
Setting Skipjack Merchant Account Settings .................................................................................................................. 226
Changing the Merchant Account Setup Options to Use TYSY Enhanced Functions .................................................... 227
Developer Notes about the TSYS Platform Enhanced Features ................................................................................... 228
Appendix Q: Usage Guidelines for Using Paymentech as Payment Processor ................................ 229
Setting the Batch Settlement Preferences for Paymentech Salem ................................................................................ 230
Appendix R: Skipjack Variable Mapping ........................................................................................... 231
Selectable Variables ....................................................................................................................................................... 231
Variables Generated During Transaction Processing .................................................................................................... 232
Appendix S: Master Error Code Table .............................................................................................. 234
Skipjack_Integration_Guide_Version1.0_RevM8.docx
Page 8
 2009 Skipjack Financial Services
Skipjack Integration Guide
About this Document
This guide contains information about all Skipjack Financial Services transaction methods except the
reporting methods and is intended for experienced application developers. The information includes
specific integration and application development details for each method. A companion guide, the
Skipjack Reporting API Integration Guide contains all details for using Reporting APIs.
This documentation does not attempt to describe language-specific programming details. Instead, the
purpose of this guide is to provide details about the various API methods, variables, values,
parameters, usage notes, examples, and sample scenarios to aid you in your application
development and integration.
Although many of the operations can be performed using the Web-based Merchant Services
interface, the information in this guide concentrates on the direct post and API-based transaction
methods.
The Merchant Services interface, however, must be used in some instances to configure the Skipjack
Merchant Account for the API request to work. These details are included whenever relevant. For a
detailed description about the Merchant Services User Interface and other online Skipjack
applications, see the “Obtaining Additional Information” section for details.
NOTE: This guide has been restructured. See the “Obtaining Referenced Documents” section
for details about the new guides created as part of this content reorganization.
Copyright Notice
© 2009 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.
Trademark Notice
All trademarks, registered trademarks, and service marks mentioned or used within this document are
owned wholly by their respective owners.
Interchange Qualifications and Transaction Rates
As your Payment Solution Skipjack Financial Services cannot guarantee interchange qualification for
any specific transaction. It is the responsibility of each Merchant to confirm that their transactions
qualify for the correct interchange rates in consultation with their Merchant Account Provider and
Payment Processor.
If you experience issues with interchange qualification, please contact the Skipjack Financial Services
Support Group so that we can work with your Payment Processor to identify and correct any issues.
Your Payment Processor must provide the necessary information to direct you and/or Skipjack in the
resolution process.
Page 9
 2009 Skipjack Financial Services
Skipjack Integration Guide
Publication History
Date
Version
Comments
May 2006
Version 0.9 (Draft)
Issued for internal review and limited circulation only.
August 2006
Version 1.0_RevA
Released for distribution and publication on Website.
September 2006
Version 1.0_RevD
Added information about support for Soft Indicators using
Paymentech Salem and assorted editorial changes
September 2006
Version 1.0_RevE
Added “Appendix A: Permitted Country Code Values” section and
additional information about the use of rtCountry variables for Add
and Edit recurring Payment methods to support Paymentech Soft
Indicator Functionality
September 2006
Version 1.0_RevG
Minor changes to e-mail variable descriptions.
Minor changes to Response Code descriptions for all non
Authorize/AuthorizeAPI methods. Added new (virtual) test credit card
number for Global Payment Systems
November 2006
Version 1.0_RevK
Editorial changes to reflect inputs from users. Enhancements made to
the Soft Indicator details.
April 2007
Version 1.0_RevL
Minor editorial changes and corrections.
Removed erroneous Soft Indicator information regarding support for 3
digit and 3 letter Country codes.
April 2007
Version 1.0_RevL1
Added changes to reflect support for ApprovalCode variable in
Authorize/AuthorizeAPI method. Added details for Ignore AVS
settings in Orderstring variables plus minor editorial updates.
June 2007
Version 1.0_RevL2
Updated Payment Processors tables and info, changed some details
in Change Transaction Status and Get Transaction Status sections,
added 3 new Reauthorization Scenarios, and assorted editorial
updates.
August 2007
Version 1.0_RevL3
Added new details about usage of optional ResponseFlags variable,
added Advanced Processor information and URLs, and minor
editorial updates.
September 2007
Version 1.0_RevL4
Added additional information regarding supported processors, and
minor editorial updates.
October 2007
Version 1.0_RevL5
Corrected batch authorization method request example
December 2007
Version 1.0_RevL6
Clarified use of Special Characters for ItemDescription and
rtItemDescription. Changed URL for Echo utility, changed Verified by
Visa entry for COMDATA in processor table. Minor editorial updates.
January 2008
Version 1.0_RevL7
Modified the Track data examples to correct error
May 2008
Version 1.0_RevL8
Modified Approval Code information to reflect new code syntax.
August 2008
Version 1.0_RevM1
Restructured Skipjack Integration Guide and created separate
guides: Skipjack Reporting API Guide and Skipjack Integration
Overview Guide.
Updated technical details and minor editorial changes throughout.
Added details about new TSYS PIN-based Debit Service for debit
processing.
Clarified information about Level I, II, and III data usage details and
background information.
September 2008
Version 1.0_RevM2
Minor editorial updates.
Page 10
 2009 Skipjack Financial Services
Skipjack Integration Guide
September 2008
Version 1.0_RevM3
Added note to the “Trackdata Capture, Formatting and Usage Notes”
section of Appendix H: Using Trackdata Details in Transactions”
regarding potential for Declines with swiped transactions in special
circumstances. Minor editorial updates.
December 2008
Version 1.0_RevM4
Added details about the TSYS enhancements for credit card
processing.
Added details about enhanced Change Status functionality.
Clarified details about use of Split Settlement.
Added information about AVS code G.
Clarified details about TrackData usage.
Updated Soft Indicator information.
Clarified usage details for County Code usage.
Added new Appendix R: Variable Mapping information.
Assorted minor technical and editorial changes.
NOTE: This version of the guide was released for internal
Skipjack use only.
January 2009
Version 1.0_RevM5
Added details regarding new Change Status feature enhancements.
Updated the szReturnCode table.
Assorted minor technical and editorial changes.
February 2009
Version 1.0_RevM6
Minor editorial changes to Authorization Logic and Appropriate
Failsafe Mechanisms section.
April 2007
Version 1.0_RevM7
Assorted minor technical and editorial changes..
Changes to clarify ChangeStatus response formatting and related
details.
Improved descriptions for OrderString and lvl3_orderstring variables.
Added table for new Test Cards for use with Fifth Third Processing
Solutions.
April 2007
Version 1.0_RevM8
Added new Skipjack Master Error Code section (Appendix to replace
previous szResponseCode Error table and to provide additional
troubleshooting and error information.
Minor technical changes added as part of internal technical review.
Page 11
 2009 Skipjack Financial Services
Skipjack Integration Guide
Documentation Conventions
The material presented in this guide uses the following text conventions throughout, where
applicable.
Convention
Usage
Example
Courier
text
Code Snippets, HTML Code,
Skipjack Transaction Network
Request Response
Examples text
<form name="Button"
action="https://vpos.skipjack.com/ezPay/order.
asp" method="post">
Bold text
Browser Elements, Fields Names,
and Menu Items,
Emphasis
Notes
…click on a Submit button….
…make sure you enter your HTML Serial Number....
NOTE: You must consider the following when…
Blue
Underline
Hyperlinks (links) to external
resources on the Web. Click on
these to go to the document or
web site identified by the link.
Visit http://www.skipjack.com to learn more about Skipjack
Financial Services.
“Quoted text”
Primary use is to denote crossreferences (clickable hotlinks in the
PDF version) to a location within
this document.
“See the “About this Document” section for details.”
This field can also include the “.” (period) character.
Also used within tables in this
document to enclose characters
that might otherwise be
overlooked.
Italics
Document Title
See the Skipjack Integration Guide for details.
Page 12
 2009 Skipjack Financial Services
Skipjack Integration Guide
Definitions of Variable Types
There are three types of variables for all methods: Required, Optional, and Conditional variables.
1. Required Variables are mandatory variables which must be included in all transaction data
requests sent. If required variables are missing in transaction data sent to the Skipjack
Transaction Network, an error code will be returned to your application.
2. Optional Variables are not required and may be omitted.
3. Conditional Variables are variables that are required if another condition applies, for instance
variable A is required if variable B is not included or in cases of a variable applying to specific
Payment Processors or services. There are relatively few conditional variables.
Permitted Syntax for Variable Fields
The permitted characters for variables used in the transaction variable tables throughout are defined
below. Please ensure you follow these conventions when entering data into the applicable variable
fields.
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: &,%.*
Special Characters
Special characters only.
"~`!@#%^&*()_-+= only
Obtaining Additional Information
A complete listing of resources including User Guides, Integration Guides, Developer and Merchant
resources, support links, and other resources is available from the Skipjack Financial Services Web
site at the links listed below:
•
•
http://www.skipjack.com/developers.aspx
http://www.skipjack.com/support.aspx
Page 13
 2009 Skipjack Financial Services
Skipjack Integration Guide
Obtaining Referenced Documents
This document references other Skipjack documentation available from the Skipjack Financial
Services Web site by clicking on the links below.
•
•
•
•
•
•
•
•
Skipjack Integration Guide (Latest version of this Guide)
Skipjack Integration Troubleshooting Guide
Skipjack Integration Overview Guide
Skipjack TSYS PIN-based Debit Services Guide
Skipjack Level II and III Transaction Overview Guide
Skipjack Merchant Reporting Guide
Skipjack Merchant Services Guide
Skipjack Reporting API Integration Guide
Contacting Skipjack Financial Services
If you have problems using the Skipjack Transaction Network 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
Email: support@skipjack.com
Obtaining a Developer Account with Skipjack Financial Services
You can find out more information and request your Skipjack Development Account(s) online at
http://www.skipjack.com/developers.aspx or by calling 1-888-368-8507 and speaking with a Skipjack
Customer Support representative.
Obtaining a Merchant Account from a Financial Institution
Merchant Accounts are provided by financial institutions and must be in place before the live
application can activated within Skipjack Financial Services. There is some lead time required for the
setup of the Merchant Account. Developers must ensure that the Merchant you are working with is
aware of this and begins the process of obtaining their Merchant Account to ensure that live testing
and rollout of your application can be completed on time.
Page 14
 2009 Skipjack Financial Services
Skipjack Integration Guide
Getting Started: Application Development Lifecycle
Overview: Recommended Development Process
We suggest that you complete the steps in the order listed below:
1. Read all applicable development information including this document to understand the
development process and options.
2. Familiarize yourself with the available integration tools and methods from Skipjack Financial
Services.
3. Choose your integration methods keeping in mind the requirements of the Merchant and any
other third-party systems requirements.
4. Write the code for your application.
5. Obtain and configure your Skipjack Development Account(s) by contacting Skipjack Financial
Services by calling 1-888-368-8507 or on the Web: http://www.skipjack.com/developers.aspx.
6. Test your integration in the Skipjack Test Environment using your Skipjack Development
Account(s). For further information about testing, see the testing details described in the
Skipjack Developers Overview Guide.
7. Deploy your application Live in the Skipjack Financial Services Production Environment.
8. Test the integration and Skipjack Account settings in the Skipjack Production Environment.
9. 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 by going to www.skipjack.com/certification.
10. 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 about registering, go to
https://secure.skipjack.com/partners/search.aspx or email partners@skipjack.com.
Page 15
 2009 Skipjack Financial Services
Skipjack Integration Guide
Payment Processors Supported by Skipjack Financial Services
The Skipjack Transaction Network supports the Payment Processors (also called Processors in this
document) listed below. Advanced Processors are noted by red* and transactions posted to these
Payment Processors use a specific URL, as noted for each applicable transaction method.
Skipjack has links to all Merchant Banks through the Processors listed below.
1
TSYS
(VITAL)
NOVA
First
Data
Nashville
Global
Payments
East
First
Tennessee
Bank
Fifth Third
(St. Pete)
Concord
EFS Net
RBS
LYNK
Paymentech
Salem*
Paymentech
Tampa*
COMDATA*
Ecommerce
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
Mail Order
YES
YES
YES
YES
YES
YES
NO
YES
YES
YES
YES
Retail
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
Verified By
Visa
YES
NO
YES
YES
YES
YES
NO
NO
YES
YES
NO
Master Card
Secure Code
YES
NO
YES
YES
YES
YES
NO
NO
YES
YES
NO
Level I
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
Level II
YES
NO
YES
YES
YES
YES
NO
NO
YES
YES
YES
Level III
YES
NO
YES
NO
NO
NO
NO
NO
YES
NO
NO
Soft
Indicators
/Descriptors
YES
NO
NO
NO
NO
NO
NO
NO
YES
NO
NO
Track 1 Data
NO
YES
YES
YES
YES
YES
YES
YES
YES
YES
YES
Track 2 Data
YES
NO
NO
YES
NO
YES
NO
NO
YES
YES
YES
PIN-based
Debit
YES
NO
NO
YES
NO
YES
NO
NO
NO
NO
NO
1
Settled on First Data Omaha
Page 16
 2009 Skipjack Financial Services
Skipjack Integration Guide
Payment Processor Information for Canadian Merchant Accounts and
Payment Processors
•
Canadian Merchant Accounts are supported by Global Payments East and Paymentech only.
•
All Merchant Account Providers in Canada (including Paymentech) can be processed through
Global Payments East.
•
To use Paymentech as your Payment Processor in Canada you must use Paymentech as your
Merchant Account Provider.
•
Canadian Merchant Accounts using Global Payments East must submit their Merchant
Account information to Global Payments Systems for registration at least two weeks before it
can be used for transaction processing. The registration process takes approximately 2 weeks
to complete.
Page 17
 2009 Skipjack Financial Services
Skipjack Integration Guide
Connection Types
The Skipjack Transaction Network uses three main connection types for all transaction processing.
Direct Skipjack API Posts
Direct posts are used to send data as name-value pairs directly to the Skipjack Transaction Network
via a secure HTTPS using an HTTPS form POST request. A response is sent back from the Skipjack
Transaction Network to the originating application as a comma-delimited test string with carriagereturn and Line Feed (CR/LF) record delimiters.
Skipjack will also be providing a web service interface shortly, please contact your Relationship
Manager for more information. Web services-based transaction processing will be supported for
Authorize, Change Status and Recurring Payments methods. Exact WSDL locations will be provided
in a separate Web Services document upon request.
Installed API Posts
Skipjack provides the .NET Retail API for installation on client hardware. For more information please
visit the Skipjack web site at http://www.skipjack.com/developers.aspx and use the Integration
Toolkits link to access information about the Skipjack RetailAPI.
Skipjack previously supported an installable COM API but not longer supports it for new integrations.
(Skipjack Financial Services will continue to support existing applications that use COM-based posts.)
Batch Posts
Batch posting is a mechanism for processing transactions as grouped batches in an offline mode.
Batch posting may be more efficient for processing large volumes of transactions and situations
where it is not practical to process each transaction separately.
Page 18
 2009 Skipjack Financial Services
Skipjack Integration Guide
Level I, II, III Card Data Transaction Overview
The Skipjack Transaction Network supports processing of all card types including Level I, Level II,
and Level III card data. Level II and Level III transaction processing are sometimes collectively
referred to as Enhanced Data transactions and are normally used in a business-to-business or
business-to-government transactions rather than a consumer-level purchases.
Level I Transactions
Level I card credit transaction data are submitted for all standard consumer credit card transactions
and primarily used in credit card purchases made by most consumers. Level I data normally include
all the required name-value pairs as described in the main section of this guide.
For Level I card transactions the information returned and reported on the Customer’s card statement
regarding the transaction is limited to basic transaction details, such as the Merchant Name, City,
Date, Amount, and so on. Basic transaction processing rates are applied in accordance with the
details provided by the Merchant Account Provider for Level I transactions.
Level II Transactions
Level II credit cards are typically issued to individuals employed by large enterprises or organizations
and governments for making corporate purchases, often for larger transaction amounts than typical
Level I transactions.
Level II transactions can qualify for a discounted transaction rates resulting in significant savings to
the enterprise if all requirements of the Merchant Account Provider are met and the properly
formatted transaction data is sent in the transaction request.
Level II card data includes all the required Level I data plus three additional parameters. All must be
sent to qualify for Level II rates. These parameters are: Purchase Order Number, Customer Code,
and Customer Tax.
The additional data collected in the transaction data may be used for back-office functions such as
program administration (such as monitoring employee spending), accounting and reconciliation
functions (for example, general ledger allocations), tax reporting and auditing (providing a breakdown
of Local, State, Federal taxes) and supplier monitoring.
Level II cardholders typically receive detailed card statements with enhanced details describing the
sales tax breakdown, customer reference number (PO Number), and Merchant Order Number on
their card statements.
Page 19
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example of Level II Data Request String
NOTE: Level II transaction name-value pairs shown in red.
serialnumber=000289255730&ordernumber=FS4RRM8YHV4DFB2FNA5DWX&transactionamount=1.00&accou
ntnumber=4445999922225&month=08&year=2009&cvv2=999&sjname=TestName&email=test@skipjack.co
m&streetaddress=8320 TestDrive&city=Houston&state=TX&zipcode=85284&phone=0000000000&
shiptophone=0000000000&orderstring=001~Test Payment~1.00~1~N~||&comment=TEST
PAYMENT&customercode=A10&purchaseordernumber=5553424234234234&customertax=0.10
NOTE 1: Skipjack Financial Services only supports Level II transaction processing for the
Payment Processors listed in the “Payment Processors Supported by Skipjack Financial
Services” section.
Level III Transactions
Level III credit card transactions are sometimes called Purchase Cards or Corporate Card purchases.
Level III transaction data include additional name-value request variables not used for Level I and
Level II transactions. Level III transactions are important in the large business-to-business or
business-to-government environments as considerably more data is collected for each transaction
and can qualify for the lowest discount rates.
The Level III transaction data includes all the required Level I and Level II transaction data (Level II
data must be sent in a Level III request) as well as additional Level III transaction data. Level III
transaction data can be used in an enterprise to support back-end processing and data exchange
tasks typically used in accounting and reconciliation tasks.
Obtaining the best discount rate depends on several requirements specified by the Merchant Account
Provider and that the required Level III transaction parameters are sent for each transaction.
At present, the Skipjack Transaction Network is one of the relative few Payment Gateways that fully
support Level II and III transactions. As an integrator you must be aware that to be able to process
Level II and Level III transaction data and obtain the expected (best) Level III transaction rates
requires that all required Level III name-value pairs be properly formatted and sent in each Level III
transaction request.
NOTE 1: Skipjack Financial Services only supports Level III transaction processing for the
Payment Processors listed in the “Payment Processors Supported by Skipjack Financial
Services” section.
NOTE 2: For Level III transactions all required Level I, Level II, and Level III name-value pairs
must be submitted in each transaction request with valid values to qualify for the Level III
discount rates. Omitting even a single required name-value pair or assigning an incorrect
value for a variable (such as Purchase Order) may result in the transaction being downgraded
from the fully-qualified rate to a less qualified rate resulting in unexpected (higher) per
transaction rates for the Merchant.
Page 20
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example of Level III Data Request String
sjname=Vendor Name&Email=test@skipjack.com&Streetaddress=123 Test
Road&City=Cincinnati&State=OH&Zipcode=40511&Ordernumber=9727TEST&Accountnumber=4445999922
225&Month=07&Year=08&Transactionamount=51.40&&Shiptostreetaddress=123
TestRoad&Shiptocity=Cincinnati&Shiptostate=OH&Shiptozipcode=40511&Shiptophone=5135882100&
Customertax=2.64&Customercode=123456&Purchaseordernumber=PONUMBER&Shiptocountry=840&Shipp
ingamount=4.76&Shippinghandling=0.01&Restockingfee=0.02&Uniquevatinvoicenumber=1010&Vatta
xamount=0.03&Vattaxrate=0.04&Customervatnumber=1234&Dutyamount=0.05&Summarycommoditycode=
2500&Nationaltax=0.06&Discountamount=0.07&Orderstring_lvl3=31711~PCARDTRANS~44.00~1.000~N
~EA~0.08~44.00~2500~0.09~0.10~0.11~0.12~30~0.13~||33910~PCARDTRANS~0.00~5.000~N~EA~0.00~0
.00~2500~0.00~0.00~0.00~0.00~0~0.00~||
NOTE: This string is sent as a single line of text.
See Also
• See the “Transaction Requests for Authorize and AuthorizeAPI” section for a complete list of
Level I, II, and III transaction data used in transaction Authorizations.
Page 21
 2009 Skipjack Financial Services
Skipjack Integration Guide
Core & Supplementary Transaction Methods
The methods described in this guide can be functionally classified as either Core or Supplementary
methods. A detailed description of all Core and Supplementary transaction methods is provided.
Core Methods
The Core transaction methods are fundamental methods that perform the most widely-used
transaction functions. The Core methods include the following:
1. Authorize and AuthorizeAPI
2. Get Transaction Status
3. Change Transaction Status
Supplementary Methods
The Supplementary methods are those that are used in conjunction with the Core methods to perform
more specialized or tertiary operations on transactions.
The available Supplementary Methods for transaction processing:
1. Recurring Payments
a) Add Recurring Payment
b) Get Recurring Payments Status
c) Delete Recurring Payment
d) Edit Recurring Payment
2. Batch Upload
a) Batch Authorization
b) Check Batch File Status
c) Modify (Edit) Batch File Status
d) Get Batch File Response
3. Reports API
a) Transaction Detail Report
b) Daily Deposit Summary
c) Batch Summary Report
d) Customized Report
NOTE: For integration details about the Reporting API methods, see the companion
guide Skipjack Reporting API Integration Guide.
4. Batch Settlement
a) Close Current Open Batch
b) Get Batch Settlement Status
Page 22
 2009 Skipjack Financial Services
Skipjack Integration Guide
Authorize and AuthorizeAPI Methods
The Authorize and AuthorizeAPI methods are used to submit transaction data to the Skipjack
Transaction Network for Authorization.
Both methods, Authorize and AuthorizeAPI, use the same variables, field names, and values in their
requests and responses. The usage of each method is described in this section.
Authorize
The Authorize method sends an HTTPS POST request to the Skipjack transaction server and
receives the responses as a postback with the responses as name-value pairs in the header of the
response post.
Post-Back Locations for Authorize Method
There are three locations for the response types (Approval, Decline, Failure) generated by an
Authorize transaction method. Additional information about setting post-back locations can be found
in the Skipjack Merchant Services Guide.
AuthorizeAPI
The AuthorizeAPI method sends a request to the transaction server via a HTTPS connection using a
request POST and receives a comma-delimited response string with carriage return/ line feed
(CR/LF) line breaks.
Transaction Requests for Authorize and AuthorizeAPI
This section describes the variables sent in transaction data requests for Authorize and AuthorizeAPI
methods.
Details for Submitting Transaction Requests for Authorize and AuthorizeAPI
Development Server: Authorize
https://developer.skipjackic.com/scripts/evolvcc.dll?Authorize
Development Server Authorize
*Advanced Processors Only
See “Payment Processors Supported by Skipjack
Financial Services” for a list of Advanced
Processors.
https://developer.skipjackic.com/evolvcc/evolvcc.aspx?Authorize
Development Server: AuthorizeAPI
https://developer.skipjackic.com/scripts/evolvcc.dll?AuthorizeAPI
Development Server Authorize API
*Advanced Processors Only
See “Payment Processors Supported by Skipjack
Financial Services” for a list of Advanced
Processors.
https://developer.skipjackic.com/evolvcc/evolvcc.aspx?AuthorizeAPI
Production Server: Authorize
https://www.skipjackic.com/scripts/evolvcc.dll?Authorize
Page 23
 2009 Skipjack Financial Services
Skipjack Integration Guide
Production Server Authorize
*Advanced Processors Only
See “Payment Processors Supported by Skipjack
Financial Services” for a list of Advanced
Processors.
https://www.skipjackic.com/evolvcc/evolvcc.aspx?AuthorizeAPI
Production Server: AuthorizeAPI
https://www.skipjackic.com/scripts/evolvcc.dll?AuthorizeAPI
Production Server AuthorizeAPI
*Advanced Processors Only
See “Payment Processors Supported by Skipjack
Financial Services” for a list of Advanced
Processors.
https://www.skipjackic.com/evolvcc/evolvcc.aspx?AuthorizeAPI
Development Server Host Name
developer.skipjackic.com
Production Server Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
NOTE 1: The submitted variables and values and response string values are identical for both
the Authorize and AuthorizeAPI methods.
NOTE 2: Information highlighted in the following tables with yellow background fill indicates
information applicable to those using Paymentech as their Payment Processor and
implementing Soft Indicators.
NOTE 3: Information highlighted with blue background fill in the following tables indicates
information applicable to those using TSYS as their Payment Processor and processing TSYS
PIN-based debit transactions.
NOTE 4: Information highlighted with orange background fill in the following tables indicates
information applicable to those using TSYS or GLOBAL as their Payment Processor and using
POSEntryMode Settlement Flags options.
Request Variables for Authorize and AuthorizeAPI Methods
Variable Name
Variable
Description
Required /
Optional
Variable
Type
Min /
Max
Length
SerialNumber
HTML Serial
Number.
Required
Numeric
12/12
1
000111222333
Conditional
AlphaNumeric
12/12
1
ABC123456789
Data
Level
Example
Skipjack-assigned
unique HTML serial
number.
DeveloperSerialNumber
Developer Serial
Number
Page 24
 2009 Skipjack Financial Services
Skipjack Integration Guide
Developer Serial
Number Assigned
to the Skipjack
Account.
This variable is
conditional as
determined by
whether or not this
option is set as
mandatory in the
Merchant Services
Interface.
SJName
Customer's Name
Required
All
Characters
1/40
1
John Doe
Cardholder’s Billing
Name.
NOTE: You should
not use the AND
symbol (&) in this
variable, or else this
will truncate the
name at this symbol
and may cause
problems with
Skipjack Reports.
Email
Customer's Billing
Email Address
Required
Valid email
Characters
1/40
1
jd@skipjack.com
StreetAddress
Customer's Billing
Street Address
Required
AlphaNumeric
and
comma (',')
and period
('.')
1/40
1
1 Skipjack Way
StreetAddress2
Additional Billing
Address Information
Optional
AlphaNumeric
comma (',')
and period
('.')
0/40
1
Apartment 1
StreetAddress3
Additional Billing
Address Information
Optional
AlphaNumeric
and
comma (',')
and period
('.')
0/40
1
Lower Level
StreetAddress4
Additional Billing
Address Information
Optional
AlphaNumeric
and
comma (',')
and period
('.')
0/40
1
Side Door
Page 25
 2009 Skipjack Financial Services
City
Customer's Billing
City
Skipjack Integration Guide
Required
AlphaNumeric
1/40
1
Cincinnati
All Spaces within a
City will be removed
State
Customer's Billing
State or Province
Required
AlphaNumeric
1/40
1
OH
ZipCode
Customer's Billing
Zip or Postal Code
Required
AlphaNumeric
and '-'
1/10
1
12345 or
123456789
Country
Customer's Billing
Country.
Optional*
AlphaNumeric
*0/3
OR
0/40
1
*For Paymentech
Salem:
UK
*NOTE: Required
variable when using
Paymentech (Salem
or Tampa) as your
Payment Processor.
OR
For other
Processors:
USA
Canada
840
See “Appendix A:
Permitted Country
Code” section for
specific Country
Codes used for this
variable and any
usage restrictions
required by specific
Payment
Processors.
Phone
Customer's Phone
Number
Optional
Numeric
and dash
('-')
1/12
1
8005551212 or
800-555-1212
Fax
Customer's Fax
Number
Optional
Numeric
and dash
('-')
1/12
1
8005551212 or
800-555-1212
ShipToName
The Ship To Name
Optional
AlphaNumeric
1/40
1
Jane Doe
ShipToStreetAddress
Customer's Billing
Street Address
Optional
AlphaNumeric
and
comma (',')
and period
('.')
1/40
1
1 Skipjack Way
ShipToStreetAddress2
Additional Billing
Address Information
Optional
AlphaNumeric
and
comma (',')
and period
('.')
0/40
1
Apartment 1
ShipToStreetAddress3
Additional Billing
Address Information
Optional
AlphaNumeric
and
0/40
1
Lower Level
Page 26
 2009 Skipjack Financial Services
Skipjack Integration Guide
comma (',')
and period
('.')
ShipToStreetAddress4
Additional Billing
Address Information
Optional
AlphaNumeric
and
comma (',')
and period
('.')
0/40
1
Side Door
ShipToCity
Customer's Billing
City
Optional
AlphaNumeric
1/40
1
Cincinnati
ShipToState
Customer's Billing
State or Province
Optional
Level 1
AlphaNumeric
1/40
3
OH
AlphaNumeric
and dash
('-')
1/10
3
12345 or
123456789
AlphaNumeric
0/40
3
USA, Canada,
UK, 840
Required
Level 3
ShipToZipCode
Customer's Billing
Zip or Postal Code
Optional
Level 1
Required
Level 3
Customer's Billing
Country
Optional
Level 1
See the “Appendix
A: Permitted
Country Code”
section for specific
Country Codes
used for this
variable and any
usage restrictions
required by specific
Payment
Processors.
Required
Level 3
ShipToPhone
Phone Number for
Customer at
Shipping
Destination
Required
Numeric
and dash
('-')
1/12
1
8005551212 or
800-555-1212
ShipToFax
Customer’s Fax
Number
Optional
Numeric
and dash
('-')
1/12
1
8005551212 or
800-555-1212
OrderNumber
Order Number
Required
AlphaNumeric
1/20*
1
ABC123 or 123
ShipToCountry
The order identifier
(ID) assigned by the
Merchant’s
application when
the order is placed
to identify the
transaction
Page 27
 2009 Skipjack Financial Services
Skipjack Integration Guide
uniquely.
OrderNumber
should be uniquely
generated by the
application to
prevent duplicates.
(Duplicates order
numbers are
repeated Order
Numbers that occur
within a 24 hour
period)
NOTE: For those
using Paymentech
Salem as the
Payment Processor
the Order Number
can be a maximum
of 22 alphanumeric
characters and must
be unique per
Settlement Batch,
otherwise a Decline
will be returned.
See also “Appendix
I: Unique Order
Numbers: section.
OrderDescription
Soft Indicator
Descriptor
Optional
Applies only to
Paymentech Salem
and TSYS for
processing credit
card only.
This variable must
be in the format of
X*Y
where X is the
Company
Identifier and Y is
the Item Identifier.
Three formatting
options are
permitted:
3 characters*18
characters
Page 28
Alphanumeric
and a
single
asterisk “*”
4/22
1
DDS*123456789
012345678
 2009 Skipjack Financial Services
Skipjack Integration Guide
7 characters*14
characters
12 characters*9
characters.
X+Y= 21 characters
plus an asterisk (*)
for a total of 22
characters.
AccountNumber
Customer’s Credit
Card Number
Required
Numeric
13/18
1
41111111111111
1
NOTE: Spaces are
not permitted.
Month
Customer’s Credit
Card Expiration
Month
Required
Numeric
1/2
1
9 or 09
Year
Customer’s Credit
Card Expiration
Year
Required
Numeric
2/4
1
09 or 2009
CVV2
Card Verification
Value
Optional
Numeric
3/4
1
123 or 1234
Required
Numeric
and period
(".")
3/10
(does
not
include
Decimal
)
1
1.00 or 1000.00
NOTE: CVV
validation may not
be supported by the
credit card issuing
bank.
See also “Appendix
C: CVV and
Interpreting CVV
Return Codes”
section.
TransactionAmount
The purchase
amount to be
authorized on the
Customer's credit
card.
Use XX.XX or
XXXX format for
this value.
All amounts must
contain only two
digits to the right of
the decimal.
Page 29
 2009 Skipjack Financial Services
Skipjack Integration Guide
A negative
TransactionAmount
can be used to
perform a Blind
Credit if the Blind
Credit feature is
enabled in the
Merchant Services
Interface.
Comment
Any comment about
the transaction.
Optional
AlphaNumeric
0/255
1
This is a
comment
Optional
See Notes
See
descript
-ion
1
See “Appendix H:
Using Trackdata
Details in
Transactions” for
examples.
Optional
AlphaNumeric
0/255
1
color = blue
Customer Sales
Tax Amount
Optional
Level 1
Numeric
and period
(".")
4/12
2
10.10
Sales tax amount in
percentage, in
XX.XX formatting.
Required
Level 2
NOTE: All characters
in excess of the
maximum length of
255 characters will
be truncated.
TrackData
TrackData
Track 1, Track 1
and 2, or Track 2
Magstripe data on
back of credit card.
See also “Appendix
H: Using Trackdata
Details in
Transactions”.
userdefined
Any defined
variable name
Up to 30 userdefined fields are
permitted per
transaction.
The name of the
user defined fields
can only be 40
characters long.
CustomerTax
*NOTE 1: For VISA,
to qualify for Level II
and III discount rates
this variable must
contain a value of
0.1 to 22.00
Required
Level 3
Page 30
 2009 Skipjack Financial Services
Skipjack Integration Guide
otherwise the
transaction will be
downgraded.
*NOTE 2: For
MasterCard, to
qualify for Level II
and III discount rates
this variable must
contain a value of
0.10 to 30.00,
otherwise the
transaction will be
downgraded.
See also “Appendix
E: Configuring
Level II Transaction
Data ”.
CustomerCode
Customer Code
*For VISA this value
can be Numeric
only.
PurchaseOrderNumber
Optional
Level 1
*AlphaNumeric
0/17
2
12345678901234
567
AlphaNumeric*
1/25
2
A123456777
AlphaNumeric
0/40
1
A123456100200
Required
Level 2
See also “Appendix
E: Configuring
Level II Transaction
Data” section.
Required
Level 3
Purchase Order
Number
Optional
Level 1
NOTE 1: To qualify
for Level II discount
rates this variable
must contain a value
otherwise the
transaction will be
downgraded to Level
I rates.
Required
Level 2
Required
Level 3
*NOTE 2: When
TSYS is the Payment
Processor the
underscore “_”
character is
permitted.
See also “Appendix
E: Configuring
Level II Transaction
Data”.
InvoiceNumber
Invoice Number
Optional
Page 31
 2009 Skipjack Financial Services
ShippingAmount
Skipjack Integration Guide
Shipping Charges
(Amount.)
Optional
Level 1
All amounts must
contain two digits to
the right of the
decimal.
Required
Level 3
Numeric
and period
(".")
3/12
3
3.25
AlphaNumeric
0/15
3
000000000
Numeric
and period
(".")
0/12
3
0.00
Numeric
0/4
3
0.0
AlphaNumeric
0/13
3
Numeric
0/12
3
1.23
Alphanumeric
0/4
3
5085
If 1.0 is passed, 10
cents ($ 0.10) will
be charged.
UniqueVatInvoiceNumber
VAT Invoice
Reference Number
Optional
Level 1
Required
Level 3
VatTaxAmount
VAT Tax Amount or
Alternate Tax
Amount
Optional
Level 1
Required
Level 3
VatTaxRate
VAT Tax Rate
Optional
Level 1
Required
Level 3
CustomerVatNumber
Customer VAT
Registration ID
Optional
Level 1
Required
Level 3
DutyAmount
Duty Amount
Optional
Level 1
Required
Level 3
SummaryCommodityCode
Summary
Commodity Code
Optional
Level 1
NOTE: If the
Payment Processor
is Global then all
Alpha Characters
should be passed as
uppercase.
Required
Level 3
See
https://vpos.skipjack
.com/ps/l3/Summary
CommodityCode.asp
for a list of
Commodity Codes.
Page 32
 2009 Skipjack Financial Services
NationalTax
National Tax
Amount
Skipjack Integration Guide
Optional
Level 1
Numeric
and period
(".")
0/12
3
1.05
Numeric
and period
(".")
0/12
3
1.04
Required
AlphaNumeric,
'||' and '~'
15/2000
1
ItemNumber~ite
mDescription~ite
mCost~Quantity~
Taxable~||
Optional
Level 1
AlphaNumeric,
'||' and '~'
53/2000
3
ItemNumber~ite
mDescription~ite
mCost~Quantity~
Taxable~UnitofM
easure~itemdisco
unt~extendedam
ount~commodityc
ode~vattaxamou
nt~vattaxrate~alt
ernatetaxamount
~taxrate~taxtype
~taxamount~||
Optional
AlphaNumeric
0/6
1
012345
01234D
Conditional
Numeric
0/1
1
2
Required
Level 3
DiscountAmount
Discount Amount
Optional
Level 1
Required
Level 3
OrderString
Level 1 Line Item
Details.
See also “Appendix
K: Orderstring
Variables” section.
orderstring_lvl3
Level 3 Data Line
Item Detail for
Purchase Cards.
See also “Appendix
K: Orderstring
Variables” section.
ApprovalCode
Approval/
Authorization Code
Required
Level 3
The Approval
/Authorization Code
must be obtained
from a voice
authorization and
submitted with
request.
ResponseFlags
Response Flags
(Used only with Global
Payments East and
TSYS)
Optional request
variable to be used
by Skipjack
Accounts using
Global Payments
East Host or TSYS
as the Payment
Processors.
Use this request
variable to the
enable the viewing
Page 33
 2009 Skipjack Financial Services
Skipjack Integration Guide
of the optional
response variables
returned in the
transaction data
used for proprietary
transaction
Settlement.
NOTE: Usage
depends on Skipjack
Account settings.
1 = Return optional
Settlement data
excluding the
POSEntryMode
variable.
2 = Return optional
Settlement data
including the
POSEntryMode
variable.
3 = Return optional
Settlement data
including the
szProductID
variable.
PINBlock
(*Used only with TSYS as
your Payment Processor
for PIN-based debit
processing)
Personal ID
Number Block
*Conditional
*Required for
TSYS PIN-based
Debit Service,
otherwise is
Optional.
The PINBlock is an
encrypted string
generated by the
supported DUK/PT
compliant PINpads
and used only in a
PIN-based debit
card transactions
and when using
TSYS as your
Payment Processor.
PINBlock is a
Required variable
for a Debit
Page 34
Alphanumeric
0/32
1
AAAAAAAAAAA
AAAAAKKKKKK
KSSSSSSSSSS
 2009 Skipjack Financial Services
Skipjack Integration Guide
(purchase)
transaction, for a
Credit transaction
but cannot be
submitted with a
Reversal request for
TSYS PIN-based
debit transactions.
See also “Appendix
F: TSYS PIN-based
Debit Transactions
Information” and the
Skipjack TSYS PINbased Debit Guide.
Unqtransactionid
(*Used only with TSYS as
your Payment Processor
for PIN-based debit
processing)
Unique Transaction
ID
*Conditional
*Required for
TSYS PIN-based
Debit Service.
*Optional, is used
for TSYS credit card
Reversal
processing. The
inclusion of this
variable containing
the value of any
unsettled
authentication’s
szTransactionFile
Name will result in
the Reversal of that
transaction. The
cardholder’s credit
limit is adjusted to
reflect the updated
credit limit. NOTE:
The Approval Code
will be the same as
the original
transaction for
successful
Reversals and will
be different for
unsuccessful
Reversals.
For Debit card
Reversals use the
TransactionID that
uniquely identifies
the transaction you
Page 35
Numeric
and period
(“.”)
10/18
1
A1234567890
 2009 Skipjack Financial Services
Skipjack Integration Guide
wish to Reverse.
NOTE: All Reversals
depend on having
the Reversals option
enabled in the
Skipjack Merchant
Register.
See also “Appendix
F: TSYS PIN-based
Debit Transactions
Information” or
“Appendix Q: Usage
Guidelines for Using
Paymentech as
Payment
Processor” and the
Skipjack TSYS PINbased Debit Guide
for more
information.
CashbackAmount
Cash Back Amount
(*Used only with TSYS as
your Payment Processor
for PIN-based debit
processing)
*Optional for TSYS
PIN-based debit
Service
transactions.
*Conditional
This is the amount
of cash requested
by cardholder and
disbursed as cash
for pin-based Debit
transactions.
Use XX.XX format
for this value.
NOTE: For Reversals
of transactions
where the original
transaction included
a CashbackAmount,
the Customer must
return the Cashback
money and the
CashbackAmount
and Transaction
Amount values from
the original
transactions must
be applied to the
Reversal otherwise a
szReturnCode=-57
Page 36
Numeric
and period
(".")
3/10
(does
not
include
Decimal
)
1
1.00
 2009 Skipjack Financial Services
Skipjack Integration Guide
will be returned.
See also “Appendix
F: TSYS PIN-based
Debit Transactions
Information” and the
Skipjack TSYS PINbased Debit Guide.
BalanceInquiry
Balance Inquiry
Optional
Numeric
0/1
1
Optional
Numeric
1/1
1
Applies only to
credit card
transactions
processed by TSYS
as the Payment
Processor.
Transactions must
be posted using
AuthorizeAPI
otherwise an error
is returned.
This variable
facilitates the return
of the balance
information for up to
4 additional
amounts.
The balance of up
to 4 accounts
associated with the
credit card will be
returned when this
variable is set to 1.
NOTE: The Skipjack
Merchant Account
must have this
feature enabled in
the Merchant
Register in order to
function.
CardAuthentication
Card Authentication
Applies only to
credit card
transactions
processed by TSYS
as the Payment
Processor.
Page 37
0 or 1
 2009 Skipjack Financial Services
Skipjack Integration Guide
This variable
permits a zero
dollar authorization
(also known as a
Preauthorization or
Preauth) to check
that the credit card
valid.
NOTE: The Skipjack
Merchant Account
must have this
feature enabled in
the Merchant
Register in order to
function.
Transaction Examples for Authorize and Authorize API Methods
Request Example 1: Authorize
<!--Fixed Values-->
<FORM NAME="sampleauthorization"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?Authorize" METHOD=POST>
<INPUT NAME="serialnumber" VALUE="111222333444">
<!--Card Holder Data-->
<INPUT NAME="sjname” VALUE="John Doe">
<INPUT NAME="streetaddress" VALUE="123 Demo Street">
<INPUT NAME="city" VALUE="Cincinnati">
<INPUT NAME="state" VALUE="OH">
<INPUT NAME="zipcode" VALUE="12345">
<INPUT NAME="shiptophone" VALUE="9024319977">
<INPUT NAME="email" VALUE="test@test.com">
<!--Purchase Data-->
<INPUT NAME="ordernumber" VALUE="ABC123">
<INPUT NAME="orderstring" VALUE="1~Sample Order~1.00~1~N~||">
<INPUT NAME="transactionamount" VALUE="1.00">
<!--Credit Card Data-->
<INPUT NAME="accountnumber" VALUE="4111111111111111">
<INPUT NAME="month" VALUE="08">
<INPUT NAME="year" VALUE="09">
Page 38
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Example 1: Authorize
"<!--AUTHCODE=VITAL5--><!--szSerialNumber=111222333444--><!--szTransactionAmount=1900-><!--szAuthorizationDeclinedMessage=--><!--szAVSResponseCode=N--><!-szAVSResponseMessage=Card authorized, no address or zip code match.--><!-szOrderNumber=1--><!--szAuthorizationResponseCode=000067--><!--szReturnCode=1--><!-szCVV2ResponseCode=--><!--szCVV2ResponseMessage=--><!--szIsApproved=1--><!-szTransactionFileName=9802850951761.009--><!--szCAVVResponseCode=-->
NOTE: Response string is returned as a single text line.
Request Example 2: AuthorizeAPI
<!--Fixed Values-->
<FORM NAME="sampleauthorization"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?AuthorizeAPI" METHOD=POST>
<INPUT NAME="serialnumber" VALUE="999888777666">
<!--Card Holder Data-->
<INPUT NAME="sjname" VALUE=”John Doe">
<INPUT NAME="streetaddress" VALUE="123 Demo Street">
<INPUT NAME="city" VALUE="Cincinnati">
<INPUT NAME="state" VALUE="OH">
<INPUT NAME="zipcode" VALUE="12345">
<INPUT NAME="shiptophone" VALUE="9024319977">
<INPUT NAME="email" VALUE="test@test.com">
<!--Purchase Data-->
<INPUT NAME="ordernumber" VALUE="ABC123">
<INPUT NAME="orderstring" VALUE="1~Sample Order~1.00~1~N~||">
<INPUT NAME="transactionamount" VALUE="1.00">
<!--Credit Card Data-->
<INPUT NAME="accountnumber" VALUE="4111111111111111">
<INPUT NAME="month" VALUE="08">
<INPUT NAME="year" VALUE="09">
Response Example 2: AuthorizeAPI
"""AUTHCODE"",""szSerialNumber"",""szTransactionAmount"",""szAuthorizationDeclinedMessage
"",""szAVSResponseCode"",""szAVSResponseMessage"",""szOrderNumber"",""szAuthorizationResp
onseCode"",""szIsApproved"",""szCVV2ResponseCode"",""szCVV2ResponseMessage"",""szReturnCo
de"",""szTransactionFileName"",""szCAVVResponseCode"",
""000067"",""999888777666"",""1900"","""",""N"",""Card authorized, exact address match
with 5 digit zipcode."",""1"",""000067"",""1"","""","""",""1"",
""10138083786558.009"","""""
NOTE: Response string is returned as two lines with a carriage return after the Header Row.
Page 39
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 3: TSYS Credit Card Balance Inquiry
<INPUT NAME="serialnumber" VALUE="000123456789">
<INPUT NAME="ordernumber" VALUE="12345">
<INPUT NAME="sjname" VALUE="Name_Test">
<INPUT NAME="streetaddress" VALUE="Address_Test">
<INPUT NAME="city" VALUE="Cincinnati">
<INPUT NAME="state" VALUE="OH">
<INPUT NAME="zipcode" VALUE="45206">
<INPUT NAME="country" VALUE="US">
<INPUT NAME="email" VALUE="none@none.com">
<INPUT NAME="shiptophone" VALUE="8883688507">
<INPUT NAME="orderstring" size="40" VALUE="001~TestName_1~1.00~1~N~||">
<INPUT NAME="transactionamount" VALUE="1.00">
<INPUT NAME="trackdata" size="130"
VALUE="B4445222299990007^TESTCARD/TEST^0912101000000520000000052000000?;4445222299990007=
09121010000005200000?">
<INPUT NAME="accountnumber" VALUE="4445222299990007">
<INPUT NAME="month" VALUE="08">
<INPUT NAME="year" VALUE="09">
<INPUT NAME="cvv2"VALUE="999">
<INPUT NAME="cardauthentication" size="1" VALUE="0">
<INPUT NAME="balanceinquiry" size="1" VALUE="0">
<INPUT NAME="unqtransactionid" VALUE="">
<INPUT NAME="orderdescription" size="25" VALUE="">
Response Example 3: TSYS Credit Card Balance Inquiry
"AUTHCODE","szSerialNumber","szTransactionAmount","szAuthorizationDeclinedMessage","szAVSResponseCo
de","szAVSResponseMessage","szOrderNumber","szAuthorizationResponseCode","szIsApproved","szCVV2Resp
onseCode","szCVV2ResponseMessage","szReturnCode","szTransactionFileName","szAccountType1","szAmount
Type1","szCurrencyCode1","szSign1","szAmount1","szAccountType2","szAmountType2","szCurrencyCode2","
szSign2","szAmount2","szAccountType3","szAmountType3","szCurrencyCode3","szSign3","szAmount3","szAc
countType4","szAmountType4","szCurrencyCode4","szSign4","szAmount4","szCAVVResponseCode"
"BALINQ","000123456789","0","","0","Card authorized, address verification result
unknown.","12345","BALINQ","1","M","Match","1","10000000000355.111","00","01","840","C","0000007766
55","","","","","","","","","","","","","","","",""
NOTE: Response string is returned as two lines with a carriage return after the Header Row.
Page 40
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Variables for Authorize and AuthorizeAPI Methods
This section lists and describes the response variables returned for the Authorize and AuthorizeAPI
methods.
There is a slight variation in the return format for Authorize and Authorize API transaction records.
The return records are formatted as follows:
1. The AuthorizeAPI method returns a Header Record whereas the Authorize does not. Authorize
only returns a single record as a comma-delimited name-value return string without a header
record. For Authorize the variables are listed in the table below.
2. For the AuthorizeAPI method the second record returned is the Response Record (Data
Record), containing the transaction return variables and values listed below.
Response Variables for Authorize and AuthorizeAPI Methods
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
1
AUTHCODE
Authorization Code
AlphaNumeric
0
(empty)
or 6
012345
05738D
Numeric
12/12
000111222333
Numeric
3/12
500 (Five dollars)
A zero (empty field) or
six-digit code
identifying whether
Authorization was
Successful (Approved)
or Unsuccessful
(Declined/Not
Approved) for a
transaction returned
from cardholder's bank
(Issuer).
2
szSerialNumber
HTML Serial Number.
Assigned unique HTML
serial number.
3
szTransactionAmount
The purchase amount
to be authorized on the
Customer's credit card.
The return of the
TransactionAmount
variable.
Page 41
 2009 Skipjack Financial Services
4
szAuthorizationDeclinedMessage
Skipjack Integration Guide
Decline message as
returned from the
Issuing Bank.
AlphaNumeric
0/60
Authorization Failed or
Card Declined
See also the “Appendix
B: Address Verification
System (AVS)
Checking” section for
more information.
5
szAVSResponseCode
AVS Response Code
returned from the
Issuing Bank.
Alpha
1/1
See also the “Appendix
B: Address Verification
System ” section for
more information.
6
szAVSResponseMessage
Text message
describing the results of
the AVS Response
Code from the Issuing
Bank.
Alpha
0/60
Exact 5 digit Zip Code
Match Only
7
szOrderNumber
Unique Order Identifier
created by the ordering
application at the time
the order was
generated.
AlphaNumeric
1/20
ABC123 or 123
AlphaNumeric
6/6
T12345
Fifth Third Processing
Solutions highly
recommends that that
OrderNumber created
by your application be
unique to prevent
confusion and
complications.
8
szAuthorizationResponseCode
A six-digit Authorization
(Approval) code
returned from the
cardholder's bank
(Issuer).
If the transaction is
Approved this field will
contain a six-digit
string.
If the transaction is
Declined this field will
contain NULL, empty or
be empty.
Page 42
 2009 Skipjack Financial Services
9
szIsApproved
Skipjack Integration Guide
Single Character
indicating the
transaction results
returned by the
Merchant Gateway.
Numeric
1/1
1, 0, or blank (empty)
szIsApproved = 1 for
Approved transactions
szIsApproved = 0 for
Declined transactions
NOTE: This field does
not carry the AVS
filtering value.
Transactions that
show an Approval
value here may still
be Declined because
of AVS filtering.
10
szCVV2ResponseCode
The CVV response
code returned from the
cardholder’s bank.
Alpha
1/1
See also
CVV Response Codes
for Visa and
MasterCard/Eurocard
11
szCVV2ResponseMessage
Text description of the
CVV Response Code.
Alpha
0/60
No Match
See also
CVV Response Codes
for Visa and
MasterCard/Eurocard
12
szReturnCode
Return Code generated
by the Merchant
Gateway denoting
whether or not the
transaction data is valid
and was sent to
Processor.
Returns the results of
the Validation Phase of
the Approval Process.
See also ”Appendix S:
Master Error Code
Table”.
Page 43
Numeric
and
dash
("-")
1/4
See the ”Appendix S:
Master Error Code
Table” section for more
information.
 2009 Skipjack Financial Services
13
szTransactionFileName
Skipjack Integration Guide
Unique Transaction File
Name (Transaction ID)
generated by the
Merchant Gateway for
each transaction.
Numeric
and
period
(“.”)
10/18
9802850951761.009
Numeric
0/4
1225
NOTE: In all other
transaction methods
this is Transaction ID.
14
szCAVVResponseCode
Cardholder
Authentication
Verification Value
Response Code
(CAVV) from the card
issuer.
Page 44
 2009 Skipjack Financial Services
Skipjack Integration Guide
If optional BalanceInquiry =1 is sent in request, the following variables are returned for up to 4 accounts associated
with the credit card. See the “Response Example 3: TSYS Credit Card Balance Inquiry” for an example.
15
szAccount TypeX
where X is a value of 1 to 4
Account Type field denotes
the type of account(s)
associated with the credit
card, for up to 4 accounts.
NOTE 1: This variable name is
appended with numerals 1 to 4
to denote return values for
each of the 4 accounts. Empty
values are returned for
account(s) that do not apply.
NOTE 2: The return of these
values will depend on
configuration settings set by
your Payment Processor
and/or credit card issuer.
00 = Not specified
10 = Savings
20 = Checking
30 = Credit Card
40 = Universal
60 = Stored Value Account
96 = Cash Benefits Account
(for use by Electronic Benefits
Transfer transactions only)
98 = Food Stamps Account
(for use by Electronic Benefits
Transfer transactions only)
Page 45
Numeric
0/2
10
 2009 Skipjack Financial Services
16
szAmount Type
Skipjack Integration Guide
Amount Type denotes the
type of account(s) associated
with the credit card, for up to
4 accounts.
NOTE: This variable name is
appended with numerals 1 to 4
to denote return values for
each of the 4 accounts. Empty
values are returned for
account(s) that do not apply.
01 = Deposit account: Ledger
balance Credit card account:
Open to buy
02 = Deposit account:
Available balance Credit card
account: Credit limit
4S = Amount Healthcare
(Visa authorization request
only)
4T = Amount Transit (Visa
authorization request only)
3S = Amount Co-payment
57 = Original Amount
10 = Partial authorized
amount
4U = Amount Prescription/Rx
(Visa and MC authorization
requests)
4V = Amount Vision/Optical
(Visa authorization request
only)
4W = Amount clinic/other
qualified medical (Visa
authorization request only)
4X = Amount Dental (Visa
authorization request only)
80 = Amount cash overDiscover only
81 = Original Amount Cash
Over- Discover Only
Page 46
Numeric
0/2
01
 2009 Skipjack Financial Services
17
szCurrencyCode
Skipjack Integration Guide
The Currency Code field
contains a three-character
numeric CurrencyCode (ISO
4217 standard) identifying the
currency type associated with
each account balance, for up
to 4 accounts associated with
the card.
Numeric
0/3
840
Alpha
0/1
C
Numeric
0/12
000000001299
NOTE: This variable name is
appended with numerals 1 to 4
to denote return values for
each of the 4 accounts. Empty
values are returned for
account(s) that do not apply.
For a list of valid currency
codes see
http://www.iso.org/iso/support
/faqs/faqs_widely_used_stan
dards/widely_used_standards
_other/currency_codes/curren
cy_codes_list-1.htm
18
szSign
Value Sign
Indicates whether the balance
amount returned is a positive
amount or a negative amount.
NOTE: This variable name is
appended with numerals 1 to 4
to denote return values for
each of the 4 accounts. Empty
values are returned for
account(s) that do not apply.
C = Positive balance
D = Negative balance
19
szAmount
This variable denotes the
12-character numeric account
balance, left-justified and
zero-filled (the decimal is
implied) for up to 4 accounts.
NOTE: This variable name is
appended with numerals 1 to 4
to denote return values for
each of the 4 accounts. Empty
values are returned for
account(s) that do not apply.
Page 47
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Variables Returned when ResponseFlags Variable Sent in Transaction
Request
The following variables are returned in the transaction data only when the ResponseFlags variable
is sent in an Authorization request and Global Payments East or TSYS are used as the Payment
Processor.
The purpose of the ResponseFlags variable is to return Settlement data for those Merchants that
wish to use this information and/or submit transactions for Settlement directly without using the
Skipjack Transaction Network for Settlement. The return of these values may depend on your
Skipjack Merchant Account settings.
NOTE: For comprehensive details about each of these variables and related information
received from Global Payments East contact Global Payments East directly to obtain required
specification documentation to ensure the application development of your Settlement
implementation complies with their specifications and requirements.
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
15
szACI
Authorization Characteristic Indicator
Alphanumeric
1/1
W
Visa
Valid values are listed below.
A = Card Present
C = Card Present, Merchant name and
location sent in Request, Cardholderactivated or self service terminal
E = Card Present, Merchant name and
location sent in Request
F = Card Not Present, Merchant name and
location sent in Request
I = Incremental Authorization
K = Card Present, Keyed Entry
N= Not a CPS (Custom Payment Services)
Qualified Transaction or Merchant not a
CPS participant
P = Card Not Present, Preferred Customer
Program participation
S = Electronic Commerce 3D Secure attempt
T = Transaction cannot participate in CPS
U = Electronic Commerce 3D Secure
V = Card Not Present, AVS Request or Bill
Payment transaction
W = Electronic Commerce non-3D Secure,
AVS requested
Y = Full contents of Track 1 and Track 2 or
Page 48
 2009 Skipjack Financial Services
Skipjack Integration Guide
card not present with AVS present or keyed
retail transaction. Electronic Commerce non 3D secure. Electronic Commerce 3D secure
MasterCard
P = Premier Service Indicator, Card Not
Present, Preferred Customer Program
participant
R = Card Not Present, Recurring Payment
Y = Full contents of Track 1 and Track 2 or
card not present with AVS present or
keyed retail transaction. Electronic
Commerce non -3D secure. Electronic
Commerce 3D secure
Other Credit Card Types
Not Used
16
szTransId
Transaction ID
Alphanumeric
0/15
Alphanumeric
2/2
Visa
Assigned by Visa in the original authorization
response. Must be present in all subsequent
incremental Authorizations, partial Credits,
and Settlement.
MasterCard
Assigned by MasterCard in the original
authorization response.
Positions 1-9 = Banknet Reference Number
Positions 10-13 = Banknet Date
Positions 14-15 = Reserved for Future Use
NOTE: Because MasterCard plans to use all 15
characters in the future Point of Sale (POS)
devices should be coded to capture the entire
field whenever data is present.
Stored Value Systems
6 digit STAN (System Trace Audit Number)
Other Credit Card Types
Not Used.
17
szValidationCode
Validation Code
Visa
Value assigned by Visa in the Authorization
response message for qualifying
transactions.
If the authorization is Declined, Visa will
Page 49
123456789012
345
 2009 Skipjack Financial Services
Skipjack Integration Guide
assign the first 2 characters as the
downgrade reason according to the valid
values listed below.
01= Approved
02 = Primary account number missing
18 = Merchant type missing
22 = Point of Sale entry mode not equal to
90
42 = Card acceptor ID code is missing
59 = Merchant’s zip code is missing
AN = Account number missing in track data
AV = AVS not requested
CK = Does not meet CPS key entry criteria
CN = cash not qualified CPS
CV = Not monitored or participating in CVV
CX = Acquirer temporarily excluded from
CVV
ED = Expiration date missing in track data
EM = Enriched card acceptor name/location
IC = Invalid Country Code
IM = Invalid Merchant Code
IP = Invalid Purchase identifier
IS = Invalid Sate Code
MC = Not participating in multi-currency
NA = Not approved in response
NP = Not participating in PS/2000
NS = Not secure electronic commerce
transaction
NT = Not participating in CPS/ATM
NV = Not a Visa transaction
TA = Account number does not match track
data
TD = Expiration date does not match track
data
TI = Transaction Identifier invalid
Other Credit Cards
Not used.
18
szAuthSourceCode
Authorization Source Code
Visa
For Visa transactions only, this field is a
single digit denoting the source of the
transaction authorization.
Valid values returned:
0 = Source Unknown
1 = STIP, Timeout Response
Page 50
Alphanumeric
1/1
5
 2009 Skipjack Financial Services
Skipjack Integration Guide
2 = LCS Response
3 = STIP, Issuer in Suppression –inq Mode
4 = STIP Response, Issuer Unavailable
5 = Issuer Approval
7 = Acquirer Approval, Base 1 Down
8 = Acquirer Approval of Referral
Other Card Types
Not used
19
szResponseCode
Alphanumeric
Response Code
Visa
Two-character value assigned in the
authorization response for transactions
submitted for special interchange
qualifications.
MasterCard
For MasterCard used to convey the
downgrade reason on transactions that failed
the magnetic stripe data edits. A list of valid
values for a downgrade reason for
MasterCard is listed below. Formatted as left
justified, space filled.
First Character (Error Indicator)
A = Track 1 or Track 2 not present in
message
B = Track 1 or Track 2 present in message
C = Primary account number not equal in
track data
D = Expiration date not equal in track data
E = Card type invalid in track data
F = Field separators invalid in track data
G = A field within the track data exceeds the
maximum length
H = Transaction category code is T for
telephone order
I = Point of Sale customer presence indicator
is 1 for customer not present
J = Point of Sale card presence indicator is 1
for card not present
Second Character (Status Indicator)
Y = Authorization system replaced Point of
Sale entry mode 90 with a value
Stored Value Systems
Authorization Server Return Code
Page 51
0/2
 2009 Skipjack Financial Services
Skipjack Integration Guide
American Express
Reserved for Future Use
For Other Cards
Not Used
19
szPOSEntryMode
Point of Sale Entry Mode
Point of Sale Entry mode indicates the way
in which the transaction was entered in the
Point of Sale device.
The response field for ResponseFlags
variable returned when using Global as the
Payment Processor and the
ResponseFlags=2 variable is sent in the
Request.
For a complete interpretation of the 12-digit
code returned for this variable, see
“szPOSEntryMode Return Variable Values
by Position”, below.
Page 52
Alphanumeric
12/12
600550670000
 2009 Skipjack Financial Services
Skipjack Integration Guide
szPOSEntryMode Return Variable Values by Position
The table below denotes the mapping and valid return values for the szPOSEntryMode variable
introduced previously.
Position
Description
Values
1
Data Input Capability
0 = Not Known
1 = Manual, No terminal (Voice/ARU/IVR)
2 = Magnetic Stripe
4 = Contactless Magnetic Stripe
6 = Key Entered
2
Authentication Capability
0 = No Electronic Authentication
1 = PIN
2 = UCAF Enabled
3
Card Capture Capability
0 = Not Used
4
Operating Environment
0 = No Terminal
1 = On Premises, Attended
2 = On Premises, Not Attended
3 = Off Premises, Attended
4 = On Premises, Attended (Home PC)
5
Cardholder Present
0 = Present
2 = Not Present (Mail Order)
3 = Not Present (Phone Order)
4 = Not Present (Standing Authorization)
5 = Electronic Order (Home PC/Internet)
6
Language Code
0 = English
1 = French
2 = Reserved
7
Card Input Mode
0 = Not Specified
2 = Complete Magnetic Stripe Read, Track 1 or 2
6 = Manually Key Entered
7 = Key-Entered because of magnetic stripe or terminal failure
8 = Key Entered and UCAF (Universal Cardholder Authentication
Field) Data included
9 = Track data via contactless entry
8
MOTO/EC Indicator
0 = Not Applicable
1 = Single Transaction
2 = Recurring Transaction
3 = Installment Payment (Not Supported)
4 = Unknown Classification/other Mail Order
5 = Secure Electronic Commerce Transaction
6 = Non-Authenticated Security Transaction (Merchant is capable of
doing 3D Secure transactions)
7 = Non-Authenticated Security Transaction, such as encrypted or SSL
8 = Non-Secure Electronic Commerce Transaction
Page 53
 2009 Skipjack Financial Services
Skipjack Integration Guide
9
Prepaid Card Capability
0 = Point of Sale cannot support partial authorization responses or
receipt of balance information
1 = Point of Sale can support partial authorization responses and
receipt of balance information
2= Point of Sale can support receipt of balance information only
10
Not Used
Not Used
11
Not Used
Not Used
12
Not Used
Not Used
Example Using ResponseFlags Request Variables
Example 1
NOTE: The optional variables for ResponseFlags are highlighted in red for emphasis.
responseflags=1, Market Type set to Ecommerce on Skipjack Account
"AUTHCODE","szSerialNumber","szTransactionAmount","szAuthorizationDeclinedMessage","szAVS
ResponseCode","szAVSResponseMessage","szOrderNumber","szAuthorizationResponseCode","szIsA
pproved","szCVV2ResponseCode","szCVV2ResponseMessage","szReturnCode","szTransactionFileNa
me","szACI","szTransId","szValidationCode","szAuthSourceCode","szResponseCode","szCAVVRes
ponseCode"
"000037","000262265864","100","","N","Card authorized, no address or zip code
match.","Test2","000037","1","P","NotProcessed","1","11402014096716.102",
"W","006205567810100","0100","5","00",""
Example 2
NOTE: The optional variables for ResponseFlags are highlighted in red for emphasis.
responseflags=2, Market Type set to Ecommerce on Skipjack Account
"AUTHCODE","szSerialNumber","szTransactionAmount","szAuthorizationDeclinedMessage","szAVS
ResponseCode","szAVSResponseMessage","szOrderNumber","szAuthorizationResponseCode","szIsA
pproved","szCVV2ResponseCode","szCVV2ResponseMessage","szReturnCode","szTransactionFileNa
me","szACI","szTransId","szValidationCode","szAuthSourceCode","szResponseCode",
"szPOSEntryMode","szCAVVResponseCode"
"000037","000262265864","100","","N","Card authorized, no address or zip code
match.","Test3A","000037","1","P","Not Processed","1","11402014096972.102",
"W", "006205567810100","0100","5","00","600550670000",""
Page 54
 2009 Skipjack Financial Services
Skipjack Integration Guide
Development Notes for AuthorizeAPI Response Handling
The following should be considered when applying logic in your application to handle Approvals and
Declines during the Authorization process. Understanding the logic of the request and response
variable handling in the Skipjack Transaction Network will eliminate unnecessary complications.
1. Parse by location not by position.
The Skipjack Transaction Network retains the right to add variables to the authorization
responses. Every effort will be made to add variables only to the end of the return string.
However you should base your application logic to parse by location such as “next to”,
“preceding”, “after”, '”before”, and so on rather than parsing on position, such as by
referring to “x” number of characters “away”.
2. Do not parse on commas.
There may be commas in the szAuthorizationDeclinedMessage and perhaps other
responses and messages. For this reason, do not parse on commas. Skipjack does not
control the content of messages sent from your Payment Processor.
3. Approvals or Declines should be determined based on the variable szIsApproved return
values (1 = Approved; 0 = Declined).
4. Skipjack does not return a decimal in the szTransactionAmount variable.
The Skipjack Transaction Network requires two decimal-place accuracy or Skipjack will
insert a decimal place.
5. Skipjack does not control the szAuthorizationResponseCode. This code is typically 6
characters but it can be less. The Skipjack Transaction Network does not pad approval
codes with characters if it is less than 6 characters.
6. Do not base your Approval logic on the presence or format of an Approval Code. Issuers
may change the Approval code syntax at any time.
Page 55
 2009 Skipjack Financial Services
Skipjack Integration Guide
Annotated Examples for Authorize and AuthorizeAPI
This section illustrates and explains common Authorization examples.
Assumptions
•
The request and response variables and values used in these examples are condensed to
include key variables only in order to simplify and best illustrate each example.
•
It is assumed that all required fields have been properly formed and passed for each
transaction.
Each example includes a brief contextual statement describing the assumed conditions for each
example, as well as a brief explanation of the return results.
Example 1: Authorization Successful for a Basic Credit Card
Transaction
In this example the Merchant is sending an authorization request with an Ordernumber=000123. (No
CVV and AVS data are sent or required and AVS filtering is set to OFF in the Skipjack Merchant
Account.)
Interpretation
•
This is a basic transaction Approval. All key return fields contain valid return codes and values
associated with an Approved transaction.
•
Transaction passed validation by the Skipjack Transaction Network as indicated by
szReturnCode = 1, meaning transaction data is complete and valid.
Page 56
 2009 Skipjack Financial Services
Skipjack Integration Guide
•
Transaction was Approved by the Processor/Issuer as indicated by the szIsApproved = 1.
szAuthorizationresponseCode = 6 digit code. A valid AUTHCODE = six digit code, also
indicates an Approved transaction.
•
No AVS or CVV response codes or messages were returned because they were not passed in
the transaction data and were not required in this example.
Page 57
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 2: Authorization Decline for a Basic Transaction
In this example the Merchant is sending an authorization request with an Ordernumber=000123. (No
CVV and AVS data not sent or required and AVS filtering is set to OFF in the Skipjack Merchant
Account.)
Interpretation
•
Transaction passed Validation as indicated by szReturnCode = 1.
• szIsApproved = 0, Issuing bank declined the transaction.
• szAuthorizationResponseCode = <empty> indicates that the card Issuer has not processed
the transaction.
• Authcode = <empty> means that the Authorization was Declined.
Page 58
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 3: Authorization Failure for a Basic Transaction
In this example the Merchant is sending an order with an Order Number=000123. In this example the
Merchant has not entered the credit card number correctly (only 4 digits entered). AVS and CVV data
is not sent and not required by the configuration set in the Skipjack Merchant Account.
Interpretation
•
Transaction failed Validation as indicated by szReturnCode = -35, which is the code returned
for an incomplete or incorrect credit card number.
• Transaction was not further processed and the transaction data was not submitted to the
Processor/Issuer as indicated by the szIsApproved = <empty>.
• szAuthorizationresponseCode = <empty> indicates that the card Issuer has not processed
the transaction.
• Authcode = <empty> means that no Authorization was obtained.
Page 59
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 4: Authorization Successful with AVS Filtering Off
In this example the Merchant is sending an authorization request with an Ordernumber=000123 with
AVS filters disabled on the Skipjack Merchant Account.
Interpretation
•
All fields contain valid return data compatible with an Authorization Approval as indicated by:
AUTHCODE = 6 digit code, szIsApproved = 1, szReturnCode = 1, and
szAuthorizationresponseCode = valid 6 digit code.
•
AVS filtering is OFF, however Issuer/Processor returned full AVS match as indicated by
szAVSResponseCode = X.
Page 60
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 5: Authorization Successful with AVS Filtering On
In this example, the Merchant is sending an authorization request with an Ordernumber 000123 and
AVS filters are enabled on the Skipjack Merchant Account.
Interpretation
•
All fields contain valid return data compatible with an Approval as indicated by:
AUTHCODE = 6 digit code, szIsApproved = 1, szReturnCode=1, and
szAuthorizationresponseCode = 6 digit code.
•
Partial match of AVS match as denoted by the szAVSResponseCode = P compared with
authorization and approval codes means that the AVS filtering threshold was not breached and
Transaction therefore is Approved.
Page 61
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 6: Authorization Failed with AVS Filtering On
In this example, the Merchant is sending an authorization request with an Ordernumber=000123 and
AVS filters are enabled on the Skipjack Merchant Account.
Interpretation
•
Similar to previous example, all fields contain valid return data compatible with an Approval as
indicated by: AUTHCODE = 6 digit code, szIsApproved = 0, szReturnCode = 1, and
szAuthorizationresponseCode = 6 digit code.
•
The distinction between this and the previous example is that this transaction returned a
szIsApproved = 0 and a partial match for AVS (szAVSResponseCode = P). This is
interpreted as the Skipjack Transaction Network’s AVS filter requiring a higher (better) match
than was returned with the transaction and therefore the transaction was Declined.
Page 62
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 7: Authorization Successful with CVV matching for Visa and
MasterCard
In this example, the Merchant is sending an authorization request with for Ordernumber=000123 and
AVS filters are enabled on the Merchant Skipjack account. CVV checking is required and is
enabled. This is a Visa or MasterCard Transaction.
Interpretation
•
All return values indicate approval: AUTHCODE, szIsApproved, szReturnCode, and
szAuthorizationReponseCode are valid Approval values.
•
CVV matched as indicated szCVV2ResponseCode=M.
Page 63
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 8: Authorization Failure with CVV not matching for Visa and
MasterCard
In this example, the Merchant is sending an authorization request with an Ordernumber=000123 and
AVS filters are enabled on the Skipjack Merchant Account. CVV checking is set as required and
CVV code has been sent with the authorization request data. This is a Visa or MasterCard
Transaction.
Interpretation
•
Authcode = EMPTY, szIsApproved=0 and szAuthorizationresponseCode = <empty> all
indicate a Declined transaction.
•
szReturnCode = 1 denotes that this transaction was successfully Validated.
•
szCVV2ResponseCode = N indicates that CVV code did not match, and may be the reason
for the Decline.
Page 64
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 9: Authorization Success with CVV matching for Amex or
Discover
In this example, the Merchant is sending an authorization request with an Ordernumber=000123 and
AVS filters are enabled on the Skipjack Merchant Account. CVV checking is required and CVV code
was sent in the transaction data. This is an American Express or Discover credit card purchase.
Interpretation
•
American Express and Discover check but do not return CVV response codes, therefore the
szCVV2ResponseCode = EMPTY.
•
All other return variables denote Approval by Skipjack Transaction Network, Processor, and
Issuer: AUTHCODE = 6 digit code, szIsApproved = 1, szReturnCode = 1,
szAuthorizationresponseCode = 6 digit code.
Page 65
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example 10: Authorization Failure because of CVV not matching for
Amex or Discover
In this example, the Merchant is sending an Authorization request for Ordernumber=000123 and AVS
filters are enabled on the Skipjack Merchant Account. CVV checking is required and enabled. CVV
code was sent in the transaction data. This is an American Express or Discover Transaction.
Interpretation
•
American Express and Discover check but do not return CVV response codes therefore
szCVV2ResponseCode = EMPTY.
•
All other return variables indicate Decline by Skipjack Transaction Network, Processor, and
Issuer: AUTHCODE = EMPTY, szIsApproved = 0, szAuthorizationresponseCode = valid 6
digit code.
szReturnCode = 1, indicates a successful Validation.
•
Page 66
 2009 Skipjack Financial Services
Skipjack Integration Guide
Get Transaction Status Method
Description
The Get Transaction Status method allows users to determine the current status of transactions
previously Authorized using the Authorize method or AuthorizeAPI method.
The Get Transaction Status method sends an HTTP name-value pair request POST to the Skipjack
Transaction Server over a secure HTTPS connection. The Skipjack Transaction Server returns a
comma-delimited response string with line feed/carriage return (LF/CR) record breaks between
records.
When Used
The Get Transaction Status method can be used to determine the status of a transaction or as a
failsafe method for transactions. Additionally this method can be used to validate the status of a
transaction prior to the Change Transaction Status method being applied.
See Also
•
•
•
To see the Get Transaction Status method in use for failsafe checking, see the “Authorization
Logic and Appropriate Failsafe Mechanisms” section.
To see examples of the Get Transaction Status method in use see the “Scenario 1: Split
Authorization Scenario
” and “Scenario 3: Recurring Payments Scenario” sections.
Transaction Variables for the Get Transaction Status Method
This section describes the variables used in transaction requests for Get Transaction Status.
Details for Submitting Get Transaction Status Method Requests
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_TransactionStatusRequest
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_TransactionStatusRequest
Development Server Host
Name
developer.skipjackic.com
Production Server Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
NOTE: Requests submitted without a secure connection will be refused.
Page 67
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Variables for Get Transaction Status
Variable Name
Variable Description
Required /
Not
Required
Variable
Type
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number.
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
123412341234
Conditional
AlphaNumeric
1/20
ABC123
Conditional
Numeric
and back
slash "/"
10/10
05/30/2008
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumb
er
Developer Serial Number
Developer Serial Number
Assigned to the Skipjack
Account.
szOrderNumber
Order Number
The unique identifier (ID)
generated by the Merchant’s
Application when the order is
placed.
See also “Appendix I: Unique
Order Numbers” section.
If this variable is omitted
szDate is Required.
szDate
The transaction date
requested.
If this variable is omitted
szOrderNumber is
Required.
MM/DD/YYYY formatting.
Page 68
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Variables for Get Transaction Status
This section describes the variables and parameters returned by the Skipjack Transaction Network
for the Get Transaction Status method.
Interpreting the Get Transaction Status Response Messages
Response strings are returned as a text string in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. Two types of records are returned for the Get Transaction Status
method:
1. Status Record (Header Record) is the first record returned contains information about the
subsequent records: szSerialNumber, szErrorCode, szNumberRecords and Reserved (empty)
fields. If an error occurs, the second record is a text description of the error.
2. Response Record (Data Record) is the second and subsequent record returned for successful
transactions (when szErrorCode=0). The Response Record(s) contains specifics about
transactions as listed in the table below.
Status Record (Header Record) for Get Transaction Status
The first record returned, the Status Record, contains information about the API call and the number
of Response Records that follow. Details of the Status Record are listed in the table below.
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
1
szSerialNumber
HTML Serial Number.
Numeric
12/12
000111222333
Numeric
and dash
"-"
1/2
-8
Skipjack-assigned unique HTML serial
number.
2
szErrorCode
Error Code (Response Code)
0 = Success
-1 = Invalid Command
-2 = Parameter Missing
-3 = Failed retrieving response
-4 = Invalid Status
-5 = Failed reading security flags
-6 = Developer serial number not found
-7 = Invalid Serial Number
See also ”Appendix S: Master Error
Code Table”.
Page 69
 2009 Skipjack Financial Services
3
szNumberRecords
Skipjack Integration Guide
Number of Response Records
Numeric
1/4
This will be
total number of
records
returned
Reserved
Reserved
Not Applicable
The number of response records
returned.
4-13
Reserved
Reserved Variables
NOTE: Second record is a text description of any error if the API call failed, see szErrorCode description
above.
Response Records for Get Transaction Status
The Response Record (Data Record) is the second and subsequent record returned for successful
transactions (when szErrorCode=0). The Response Record(s) contains specifics about transactions
as listed in the table below.
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
1
HTML Serial Number
HTML Serial Number is a
Skipjack-assigned unique
HTML Serial Number
Numeric
12/12
000111222333
Numeric
and
period
(".")
6/12
5.1500
This is the return of the
szSerialNumber variable.
2
Transaction Amount
Transaction Amount is the
purchase amount to be
Authorized on the Customer's
credit card.
The return of the
TransactionAmount variable.
Page 70
 2009 Skipjack Financial Services
3
Transaction Status Code
Skipjack Integration Guide
Transaction Status Code is a
two-digit response code
denoting the transaction’s
current status and pending
status.
Numeric
2/2
12
The first digit denotes the
Current Status:
0 = Idle
1 = Authorized
2 = Denied
3 = Settled
4 = Credited
5 = Deleted
6 = Archived
7 = Pre-Authorized
8 = Split Settled
The second digit denotes the
Pending Status:
0 = Idle
1 = Pending Credit
2 = Pending Settlement
3 = Pending Delete
4 = Pending Authorization
5 = Pending Manual
Settlement (Manual
Settlement accounts)
6 = Pending Recurring
7 = Submitted for Settlement
4
Transaction Status Message
Text message describing the
Transaction Status Code
returned above.
AlphaNumeric
0/60
5
Order Number
Unique Order Identifier
generated during the original
Authorization.
AlphaNumeric
1/20
Return of the szOrderNumber
variable.
Page 71
ABC123 or 123
 2009 Skipjack Financial Services
Skipjack Integration Guide
6
Transaction Date and Time
Date and time of the original
transaction Authorization
returned in MM/DD/YYYY
HH:MM:SS format.
Numeric
and "/"
1/1
11/29/2009 13:15:59
7
Transaction ID
Unique Transaction File Name
/ Transaction ID generated by
the Skipjack Transaction
Network for each transaction.
Numeric
and
period
(".")
10/18
9802850951761.009
This is also known as the
TransactionFileName in an
Authorization return string.
8
Approval Code
6 digit Authorization
(Approval) code returned from
the cardholder's bank (Issuer).
AlphaNumeric
6/6
000067 or T12345
9
Batch Number
The batch number code
assigned by the Skipjack
Transaction Network to the
batch that would be assigned
if the transaction were Settled.
Numeric
12/12
000000262514
Examples for Get Transaction Status Method
Request Example 1: Get Transaction Status Method specifying szDate
<!--Fixed Values-->
<FORM NAME="samplegettransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_TransactionStatusReque
st" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="123456789102">
<INPUT NAME="szDeveloperSerialNumber" VALUE="123456789102">
<!--Purchase Data-->
<INPUT NAME="szDate" VALUE="04/11/06">
Response Example 1: Get Transaction Status specifying szDate
"123456789102","0","4","","","","","","","","",""
"123456789102","1.2200","15","Approved","XX45645645","04/11/06
11:23:58","10796218819934.015","000059","000003828521"
"123456789102","1.2200","15","Approved","XX45645645","04/11/06
11:25:55","10796218819939.015","000059","000003828521"
"123456789102","1.2200","15","Approved","XX45645645","04/11/06
11:30:48","10018377568212.022","000059","000003828521"
"123456789102","1.2200","15","Approved","XX45645645","04/11/06
11:31:52","10018377568218.022","000059","000003828521"
Page 72
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 2: Get Transaction Status Method specifying szOrderNumber
<!--Fixed Values-->
<FORM NAME="samplegettransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_TransactionStatusReque
st" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="123456789102">
<INPUT NAME="szDeveloperSerialNumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="XX45645645">
Response Example 2: Get Transaction Status specifying szOrderNumber
"123456789102","0","4","","","","","","","","",""
"123456789102","1.2200","15","Approved","XX45645645","03/09/06 16:21:28",
"10796218797935.015","000057","000003741330"
"123456789102","1.2200","15","Approved","XX45645645","03/09/06 16:21:43",
"9725745399281.011","000057","000003741330"
"123456789102","1.2200","15","Approved","XX45645645","03/06/06 16:56:27",
"9715746816459.012","000057","000003741330"
"123456789102","1.2200","15","Settled","XX45645645","04/04/06 13:36:06",
"10018377562143.022","000097","000003820688"
Page 73
 2009 Skipjack Financial Services
Skipjack Integration Guide
Change Transaction Status Method
Description
The Change Transaction Status method allows the changing of the status of any existing transaction
from its current status to a new (desired) status.
Change Status feature enhancements permit additional processing functions and the ability to submit
and change most of the AuthorizeAuthorizeAPI name-value pairs, except for the credit card data in
each transaction request. The enhanced Change Status functions are listed below and are denoted
with the Ex in their respective function names (for example AuthorizeAdditionalEx).
When Used
The Change Transaction Status method can are used for changing previously processed transactions
held within the Skipjack Transaction Network from one status to another (desired) status. The
Change Status functions include the following transaction functions:
•
•
•
•
•
•
•
•
•
•
•
•
•
Authorize
AuthorizeEx
Authorize Additional (Re-Bill)
Authorize AdditionalEx (Re-Bill)
Credit (Refund)
CreditEx
Delete (Void)
Freeze
Settle
SettleEx
SplitSettle (Partial Settle)
SplitSettleEx
Thaw
Page 74
 2009 Skipjack Financial Services
Skipjack Integration Guide
Change Status Functionality Matrix
The following table lists all Change Status functions and all possible states that apply to each.
Change Status Function
Possible Applicable States
Authorize
Authorized: Pending Manual Settle
Authorized: Pending Settle
Declined
AuthorizeEx
Authorized: Pending Manual Settle
Authorized: Pending Settle
Declined
AuthorizeAdditional
Authorized: Pending Manual Settle
Authorized: Pending Settle
Settled
Credited
Declined
Archived
AuthorizeAdditionalEx
Authorized: Pending Manual Settle
Authorized: Pending Settle
Settled
Credited
Declined
Archived
Credit
Settled
Credited
CreditEx
Settled
Credited
Settle
Authorized: Pending Manual Settle
Authorized: Pending Settle
SettleEx
Authorized: Pending Manual Settle
Authorized: Pending Settle
SplitSettle
Authorized: Pending Manual Settle
Authorized: Pending Settle
SplitSettle
SplitSettleEx
Authorized: Pending Manual Settle
Authorized: Pending Settle
SplitSettle
Delete
Authorized: Pending Manual Settle
Authorized: Pending Settle
Settled
Settled: Pending Credit
Credited
Pending Credit
Pending Authorize
Freeze
Authorized: Pending Manual Settle
Authorized: Pending Settle
Settled: Pending Credit
Page 75
 2009 Skipjack Financial Services
Skipjack Integration Guide
Pending Credit
Pending Authorize
Thaw
Frozen
See Also
•
•
To see examples of the Change Transaction Status method in use, see the “Scenario 1: Split
Authorization Scenario
and “Re-Authorization Scenarios”.
Details for Submitting Change Transaction Status Method Requests
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_TransactionChangeStatusRequest
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_TransactionChangeStatusRequest
Development Server
Host Name
developer.skipjackic.com
Production Server
Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused
Page 76
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Requests for Change Transaction Status Method
NOTE: When any of the optional variables listed below are not submitted the values from the original transaction
will apply (if applicable) except where specifically noted in the table below.
Variable Name
Variable Description
Required /
Not
Required
Variable
Type
Data
Level
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number.
Required
Numeric
1
12/12
000111222333
Required
AlphaNumeric
1
12/12
123412341234
Conditional
AlphaNumeric
1
0/40
ABC123
Conditional
AlphaNumeric
1
0/40
ABC1234
Conditional
Numeric
and
period
(".")
1
10/18
12345678910
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNu
mber
Developer Serial Number
The Developer Serial Number
assigned to the Skipjack
Account.
szOrderNumber
Order Number
The unique Order Number
generated by the ordering
application (Merchant’s
Application) when the
transaction is originated.
The Order Number should be
unique to each transaction. If
the Order Number matches
multiple transactions,
regardless of their Status, an
error will be generated if the
Reject Duplicate Order
Numbers option is configured
in the Merchant Account.
See also “Appendix I: Unique
Order Numbers” section.
If this variable is omitted the
variable szTransactionId is
required.
szNewOrderNumber
New Order Number
If this value is not specified
then the original OrderNumber
is applied to the transaction.
szTransactionId
Transaction ID
Unique Transaction ID
Page 77
 2009 Skipjack Financial Services
Skipjack Integration Guide
assigned by Skipjack to each
transaction.
If this variable is omitted the
variable szOrderNumber is
required.
szDesiredStatus
Desired Status
Required
The status to which the
transaction should be
changed.
Valid parameters and usage
guidelines for each function
are provided below.
Authorize
Re-authorizes in real-time the
original transaction without
creating an additional (second)
transaction so that only a
single transaction need be
Settled.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
Retains same Audit ID as
original transaction.
If szReturnCode= -37 is
returned for the authorization,
the transaction will be placed
in Pending Authorization
status.
Standard response string is
returned.
This function can be applied to
transactions in the following
states:
• Authorized: Pending
Manual Settle
• Authorized: Pending Settle
• Declined
If szAmount is sent in the
request a new Pending
Authorization transaction with
Page 78
Alpha
1
DELETE
 2009 Skipjack Financial Services
Skipjack Integration Guide
this specified amount is
processed and the original
transaction is marked as
Archived.
If szAmount is not sent in the
request the original transaction
is marked as Pending
Authorization and the amount
from the original transaction is
applied.
AuthorizeEx
Re-authorizes in real-time the
original transaction without
creating an additional (second)
transaction with the ability to
apply enhanced functions to
the transaction.
All Optional request variables
described later in this table
can be submitted.
Retains same Audit ID as
original transaction.
An enhanced response string
is returned.
If szReturnCode= -37 is
returned for the authorization,
the transaction will be placed
in Pending Authorization
status.
This function can be applied to
transactions in the following
states:
• Authorized: Pending
Manual Settle
• Authorized: Pending Settle
• Declined
If szAmount is not sent in the
request the original transaction
is marked as Pending
Authorization and the original
transaction amount is applied
to the transaction.
AuthorizeAdditional
Page 79
 2009 Skipjack Financial Services
Skipjack Integration Guide
Creates a new (separate)
transaction in real-time for a
previously Authorized
transaction.
Creates a separate transaction
that requires Settlement on its
own separately from the
original transaction.
New AuditID is created for the
transaction.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
Standard response string is
returned.
If szReturnCode= -37 is
returned for the authorization,
the transaction will be placed
in Pending Authorization
status.
szAmount must always be
specified in an
AuthorizeAdditional request.
This function can be applied to
transactions in the following
states:
• Authorized: Pending
Manual Settle
• Authorized: Pending Settle
• Archived
• Credited
• Declined
• Settled
AuthorizeAdditionalEx
Creates a new (separate)
transaction in real-time for a
previously Authorized
transaction with the ability to
apply enhanced functions to
the transaction.
All Optional request variables
described later in this table
Page 80
 2009 Skipjack Financial Services
Skipjack Integration Guide
can be submitted.
An enhanced response string
is returned.
If szReturnCode= -37 is
returned for the authorization,
the transaction will be placed
in Pending Authorization
status.
szAmount must always be
specified in an
AuthorizeAdditional request.
This function can be applied to
transactions in the following
states:
• Authorized: Pending
Manual Settle
• Authorized: Pending Settle
• Archived
• Credited
• Declined
• Settled
Credit
Reverses a specified amount
to the cardholders account.
(Also commonly referred to as
a Refund.)
Retains same Audit ID as
original transaction.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
A standard response string is
returned.
Creates a new transaction that
is in a Pending Credit status.
Default value for
szForceSettlement=1 is sent
(settlement batch closed).
If szAmount is sent this will
Page 81
 2009 Skipjack Financial Services
Skipjack Integration Guide
credit the original transaction
for this new amount otherwise
the original transaction amount
will apply to the credit.
This function can be applied to
transactions in the following
states:
• Credited
• Settled
CreditEx
Reverses a specified amount
to the cardholders account
with the ability to apply
enhanced functions to the
transaction.
All Optional request variables
described later in this table
can be submitted.
Retains same Audit ID as
original transaction.
Creates a new transaction in a
Pending Credit status.
An enhanced response string
is returned.
If szAmount is sent this will
credit the original transaction
for this new amount otherwise
the original transaction amount
will apply to the credit.
Default value for
szForceSettlement=0 is sent
(settlement batch left open).
This function can be applied to
transactions in the following
states:
• Credited
• Settled
Delete
Deletes a previously
Authorized transaction and
upon completion marks the
Page 82
 2009 Skipjack Financial Services
Skipjack Integration Guide
transaction as Deleted.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
Delete can be legitimately
used to delete test
transactions but should not be
used for Settled transactions.
NOTE: DO NOT DELETE
SETTLED TRANSACTIONS. For
Settled transactions, use the
Credit function instead,
otherwise the settlement
amounts displayed in the
Skipjack Merchant Register will
not be reconcilable.
This function can be applied to
transactions in the following
states:
• Authorized: Pending
Manual Settle
• Authorized: Pending Settle
• Settled
• Settled, Pending Credit
• Credited
• Pending Credit
Freeze
Places a previously Authorized
transaction in a frozen state so
that no further actions possible
without Thawing the
transaction.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
Marks the transaction as
Frozen upon successful
completion of transaction.
This function can be applied to
transactions in the following
states:
• Authorized: Pending
Manual Settle
Page 83
 2009 Skipjack Financial Services
•
•
•
•
Skipjack Integration Guide
Authorized: Pending Settle
Settled, Pending Credit
Pending Authorize
Pending Credit
Settle
Places a previously Authorized
transaction into the Settlement
queue to be Settled according
to the preferences set for the
Merchant Account: for
example Manual Settlement,
Automatic, or Daily Settlement.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
Retains same Audit ID as
original transaction.
Upon successful completion
places transaction in a
Pending Settle status.
If the szAmount is specified in
the request a new Pending
Settle transaction is created
with this specified amount and
the original transaction is
marked as Archived.
If szAmount is not specified
the original transaction is
marked as Pending Settle and
the amount from the original
transaction is applied.
Default value for
szForceSettlement=1 is sent
(settlement batch closed).
This function can be applied to
transactions in the following
states:
• Credited
• Settled
SettleEx
Places a previously Authorized
transaction into the Settlement
Page 84
 2009 Skipjack Financial Services
Skipjack Integration Guide
queue to be Settled according
to the preferences set for the
Merchant Account: for
example Manual Settlement,
Automatic, or Daily Settlement
with enhanced functionality
described below. Ability to
apply enhanced functions to
the transaction.
All Optional request variables
described later in this table
can be submitted.
An enhanced response string
is returned.
Retains same Audit ID as
original transaction.
Default value for
szForceSettlement=0 is sent
(settlement batch left open).
If the szAmount is specified in
the request a new Pending
Settle transaction is created
with this specified amount and
the original transaction is
marked as Archived.
If szAmount is not specified
the original transaction is
marked as Pending Settle and
the amount from the original
transaction is applied.
This function can be applied to
transactions in the following
states:
• Authorized, Pending
Manual Settle
• Authorized, Pending Settled
SplitSettle
Allows a previously Authorized
transaction to be Settled in
separate Settlement amounts
and batches.
Use this variable option to
break a single transaction into
Page 85
 2009 Skipjack Financial Services
Skipjack Integration Guide
smaller transactions for
Settlement according to the
preferences set in the
Merchant Account. Split
Settlement allows for charging
the cardholder’s card separate
incremental amounts in
instances.
NOTE: Some Payment
Processors and Card Issuers
may prohibit the use of
SplitSettle functionality or
impose additional fees for
using the SplitSettle function.
Review your Settlement
guidelines with your Merchant
Account Provider before you
implement this functionality.
Cannot submit any Optional
name-value fields supported
by the Ex functions.
A standard response string is
returned.
Retains same Audit ID as
original transaction.
Upon successful completion
creates a new transaction in a
Pending Settle status and
marks the original transaction
as a Split-Settled status.
If szAmount is sent in the
request a new transaction will
settle for this amount
otherwise when if szAmount
is not specified the original
transaction amount is applied.
This function can be applied to
transactions in the following
states:
• Authorized, Pending
Manual Settle
• Authorized, Pending Settle
• Split-Settle
SplitSettleEx
Allows a previously Authorized
Page 86
 2009 Skipjack Financial Services
Skipjack Integration Guide
transaction to be Settled in
separate Settlement amounts
and batches with the ability to
apply enhanced functions to
the transaction.
NOTE: Some Payment
Processors and Card Issuers
may prohibit the use of
SplitSettle functionality or
impose additional fees for
using the SplitSettle function.
Review your Settlement
guidelines with your Merchant
Account Provider before you
implement this functionality.
All Optional request variables
described later in this table
can be submitted.
Retains same Audit ID as
original transaction.
An enhanced response string
is returned.
Upon successful completion
creates a new transaction in a
Pending Settle status and
marks the original transaction
as a Split Settled status.
If szAmount is sent in the
request a new transaction will
settle for this amount
otherwise when the szAmount
is not specified the original
transaction amount is applied.
This function can be applied to
transactions in the following
transaction states:
• Authorized, Pending
Manual Settle
• Authorized, Pending Settled
• Split-Settle
Thaw
Returns a previously frozen
transaction to an active state.
Cannot submit any Optional
Page 87
 2009 Skipjack Financial Services
Skipjack Integration Guide
name-value fields supported
by the Ex functions.
This function can be applied to
transactions in the following
states:
• Frozen
szAmount
The desired Transaction
Amount for the selected action
that applies to the transaction.
Conditional
Numeric
and
decimal
(‘.’)
1
Use XX.XX or XXXX format for
this value.
3/12
(Count
does not
Include
Decimal
)
12018
or
120.18
1/1
0 or 1
All amounts must contain only
two digits to the right of the
decimal.
NOT
120.185
(Invalid
Amount error
returned.)
A negative TransactionAmount
can be used to perform a Blind
Credit if the Blind Credit
feature is enabled in the
Merchant Services Interface.
This variable is Required for
AuthorizeAdditional and
AuthorizeAdditionalEx and
Optional for all other Change
Status functions. If the
szAmount variable is not
specified the amount from the
original transaction applies.
szForceSettlement
Force Settlement
Optional
This variable is used to trigger
the close of a Settlement
Batch.
Set szForceSettlement=0 to
not force Settlement.
Set szForceSettlement=1 to
force Settlement.
This variable affects the
transaction only when the
desired status is the following
types: Credit, CreditEx, Settle,
or SettleEx.
If this variable is omitted
Page 88
Numeric
1
 2009 Skipjack Financial Services
Skipjack Integration Guide
Settlement is forced by default
except where otherwise noted.
Therefore, consider including
the szForceSettlement=0 for
all transactions, even though it
is an optional variable unless
as otherwise recommended.
For Batch Files, the
szForceSettlement variable
can be used to control the
number of transactions that
are submitted in a Settlement
Batch. This is achieved by
setting all but the last
transaction to have a
szForceSettlement=0 and the
szForceSettlement=1 for the
last transaction in the batch.
Fields Applicable to Change Status Ex Functions (Extended Functionality) Only
SJName
Customer's Name
Optional
AlphaNumeric
1
1/40
John Doe
Cardholder’s Billing Name.
Email
Customer's Billing Email
Address
Optional
Valid email
Charact
ers
1
1/40
jdoe@skipjack.
com
StreetAddress
Customer's Billing Street
Address
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
1/40
1 Skipjack Way
StreetAddress2
Additional Billing Address
Information
Optional
AlphaNumeric
comma
(',') and
period
('.')
1
0/40
Apartment 1
StreetAddress3
Additional Billing Address
Information
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
0/40
Lower Level
Page 89
 2009 Skipjack Financial Services
Skipjack Integration Guide
StreetAddress4
Additional Billing Address
Information
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
0/40
Delivery Door
City
Customer's Billing City
Optional
AlphaNumeric
1
1/40
Cincinnati
All Spaces within a City will be
removed
State
Customer's Billing State or
Province
Optional
AlphaNumeric
1
1/40
OH
ZipCode
Customer's Billing Zip or
Postal Code
Optional
AlphaNumeric
and '-'
1
1/10
12345 or
123456789
Country
Customer's Billing Country.
Conditional
AlphaNumeric
1
*0/3
OR
0/40
*For
Paymentech
Salem:
UK
Must be the corresponding
country number for Level III
qualification. See “Appendix A:
Permitted Country Code
Values” section for specific
Country Codes used for this
variable and any usage
restrictions required by specific
Payment Processors.
OR
For other
Processors:
USA
Canada
840
NOTE: Required if using
Paymentech Salem or
Tampa as your Payment
Processor.
Phone
Customer's Phone Number
Optional
Numeric
and
dash ('-')
1
1/12
8005551212 or
800-555-1212
Fax
Customer's Fax Number
Optional
Numeric
and
dash ('-')
1
1/12
8005551212 or
800-555-1212
ShipToName
The Ship To Name
Optional
AlphaNumeric
1
1/40
Jane Doe
ShipToStreetAddress
Customer's Billing Street
Address
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
1/40
1 Skipjack Way
Page 90
 2009 Skipjack Financial Services
Skipjack Integration Guide
ShipToStreetAddress2
Additional Billing Address
Information
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
0/40
Apartment 1
ShipToStreetAddress3
Additional Billing Address
Information
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
0/40
Lower Level
ShipToStreetAddress4
Additional Billing Address
Information
Optional
AlphaNumeric
and
comma
(',') and
period
('.')
1
0/40
Side Door
ShipToCity
Customer's Billing City
Optional
AlphaNumeric
1
1/40
Cincinnati
ShipToState
Customer's Billing State or
Province
Optional
Level 1
AlphaNumeric
1
1/40
OH
AlphaNumeric
and
dash ('-')
1
1/10
12345 or
123456789
AlphaNumeric
1
0/40
USA, Canada,
UK, 840
Required
Level 3
ShipToZipCode
Customer's Billing Zip or
Postal Code
Optional
Level 1
Required
Level 3
ShipToCountry
Customer's Billing Country
Optional
Level 1
Required
Level 3
ShipToPhone
Phone Number for Customer
at Shipping Destination
Optional
Numeric
and
dash ('-')
1
1/12
8005551212 or
800-555-1212
ShipToFax
Customer’s Fax Number
Optional
Numeric
and
dash ('-')
1
1/12
8005551212 or
800-555-1212
Page 91
 2009 Skipjack Financial Services
OrderNumber
Order Number
Skipjack Integration Guide
Conditional
The order identifier (ID)
assigned by the Merchant’s
application when the order is
placed to identify the
transaction uniquely.
OrderNumber should be
uniquely generated by the
application to prevent
duplicates. (Duplicates order
numbers are repeated Order
Numbers that occur in a 24
hour period)
NOTE: For those using
Paymentech Salem as the
Payment Processor the Order
Number can be a maximum of
22 alphanumeric characters and
must be unique per Settlement
Batch, otherwise a Decline will
be returned.
See also “Appendix I: Unique
Order Numbers: section.
Page 92
AlphaNumeric
1
1/20*
ABC123 or 123
 2009 Skipjack Financial Services
OrderDescription
Soft Indicator Descriptor
Skipjack Integration Guide
Optional
Alphanumeric
and a
single
asterisk
“*”
1
4/22
DDS*12345678
9012345678
Optional
AlphaNumeric
1
0/255
This is a
comment
Optional
AlphaNumeric
1
0/255
color = blue
Applies only to Paymentech
Salem and TSYS for
processing credit card only.
This variable must be in the
format of
X*Y
where
X is the Company Identifier
and
Y is the Item Identifier.
Three formatting options are
permitted:
3 characters*18 characters
7 characters*14 characters
12 characters*9 characters.
X+Y= 21 characters plus an
asterisk (*) for a total of 22
characters.
Comment
Any comment about the
transaction.
NOTE: All characters in excess
of the maximum length of 255
characters will be truncated.
userdefined
Any user defined variable
name.
Up to 30 user-defined fields
are permitted per transaction.
The name of the user defined
fields can only be 40
characters long.
Page 93
 2009 Skipjack Financial Services
CustomerTax
Customer Sales Tax Amount
Sales tax amount in
percentage, in XX.XX
formatting.
*NOTE: To qualify for Level II
discount rates this variable
must contain a value of 0.1 to
22.00 otherwise the transaction
will be downgraded.
Skipjack Integration Guide
Optional
Level 1
Required
Level 2
Numeric
and
period
(".")
2
4/12
10.10
*AlphaNumeric
2
0/17
123456789012
34567
AlphaNumeric
2
1/25
A123456777
Required
Level 3
See also “Appendix E:
Configuring Level II
Transaction Data ”
CustomerCode
Customer Code
*For VISA only this value can
only be Numeric.
See also “Appendix E:
Configuring Level II
Transaction Data” section
PurchaseOrderNumbe
r
Purchase Order Number
NOTE: To qualify for Level II
discount rates this variable
must contain a value otherwise
the transaction will be
downgraded to Level I rates.
Optional
Level 1
Required
Level 2
Required
Level 3
Optional
Level 1
Required
Level 2
Required
Level 3
See also “Appendix E:
Configuring Level II
Transaction Data”
InvoiceNumber
Invoice Number
Optional
AlphaNumeric
1
0/40
A12345610020
ShippingAmount
Shipping Charges (Amount.)
Optional
Level 1
Numeric
and
period
(".")
3
3/12
3.25
AlphaNumeric
3
All amounts must contain two
digits to the right of the
decimal.
Required
Level 3
If 1.0 is passed, 10 cents ($
0.10) will be charged.
UniqueVatInvoiceNum
ber
VAT Invoice Reference
Number
Optional
Level 1
Required
Level 3
Page 94
0/15
000000000
 2009 Skipjack Financial Services
VatTaxAmount
VAT Tax Amount or Alternate
Tax Amount
Skipjack Integration Guide
Optional
Level 1
Required
Level 3
VatTaxRate
VAT Tax Rate
Optional
Level 1
Numeric
and
period
(".")
3
0/12
0.00
Numeric
3
0/4
0.0
AlphaNumeric
3
0/13
Numeric
3
0/12
1.23
Alphanumeric
3
0/4
5085
Numeric
and
period
(".")
3
0/12
1.05
Numeric
and
period
(".")
3
0/12
1.04
AlphaNumeric
, '||' and
'~'
1
15/2000
ItemNumber~it
emDescription~
itemCost~Quan
tity~Taxable~||
Required
Level 3
CustomerVatNumber
Customer VAT Registration ID
Optional
Level 1
Required
Level 3
DutyAmount
Duty Amount
Optional
Level 1
Required
Level 3
SummaryCommodityC
ode
Summary Commodity Code
NOTE: If the Payment
Processor is Global then all
Alpha Characters should be
passed as uppercase.
Optional
Level 1
Required
Level 3
See
https://vpos.skipjack.com/ps/l3/
SummaryCommodityCode.asp
for a list of Commodity Codes.
NationalTax
National Tax Amount
Optional
Level 1
Required
Level 3
DiscountAmount
Discount Amount
Optional
Level 1
Required
Level 3
OrderString
Level 1 Line Item Details.
Optional
See also “Appendix K:
Orderstring Variables” section.
Page 95
 2009 Skipjack Financial Services
orderstring_lvl3
ApprovalCode
Skipjack Integration Guide
Level 3 Data Line Item Detail
for Purchase Cards.
Optional
Level 1
See also “Appendix K:
Orderstring Variables” section.
Required
Level 3
Approval/ Authorization Code
Optional
The Approval /Authorization
Code must be obtained from a
voice authorization and
submitted with request.
Page 96
AlphaNumeric
, '||' and
'~'
3
53/2000
AlphaNumeric
1
0/6
ItemNumber~it
emDescription~
itemCost~Quan
tity~Taxable~U
nitofMeasure~it
emdiscount~ex
tendedamount~
commoditycode
~vattaxamount
~vattaxrate~alt
ernatetaxamou
nt~taxrate~taxt
ype~taxamount
~||
012345
01234D
 2009 Skipjack Financial Services
Skipjack Integration Guide
Development Notes for Change Transaction Status Method
•
To be able to use szDesiredStatus: Settle and specify an amount or (szAmount) above the
original amount, your Skipjack Account must be configured to Allow Settlement Above
Original Amount. Contact Skipjack Financial Services Support to enable this function on your
Skipjack Account, if this function is required.
•
To be able to use szDesiredStatus: Credit and specify an amount (szAmount) above the
original amount, your Skipjack Account must be configured to Allow Credits Above Original
Amount. Contact Skipjack Financial Services Support to enable this function on your Skipjack
Account.
•
When performing any Change Status functions there is a latency of approximately 1 to 5
second seconds for Production and slightly longer for Development environments. This interval
is required for the transaction to transition from its current status to its final status. Please
consider this latency when using Change Status functions in your integration.
•
When submitting amounts (szAmount) that are different than the original amount, your
Payment Processor may downgrade the transaction processing rate and impose other fees.
Please ensure that you are familiar with the implications of using these options and contact
your Payment Processor for details about any costs associated with these payment processing
options.
•
When a transaction is in either Pending Credit or Pending Settle states and has been
submitted to the Processor, no Change Status operations can be performed on the
transaction.
•
When Authorize, AuthorizeEx, AuthorizeAdditional, or AuthorizeAdditionalEx functions are
used a real-time authorization is performed.
•
If a transaction was originally swiped, performing a ChangeStatus with the Authorize,
AuthorizeEx, AuthorizeAdditional, or AuthorizeAdditionalEx functions will be handled as a nonswiped (keyed transaction). This may have implications on the interchange rate applied to the
transaction.
•
For transactions in either a Pending-Credit or Pending-Settle state and has been submitted to
the processor, no Change Status functions can be applied to the transaction.
Page 97
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Variables for the Change Transaction Status Method
Interpreting the Change Transaction Status Response Records
Response strings are returned as a text string in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. Types of records returned are listed below:
1. Status Record (Header Record) is the first record returned and contains information about the
subsequent records.
2. Response Record (Data Record) is the second row returned for successful transactions
(szErrorCode=0) and includes transaction information described in the table below.
If an error is returned for when an error condition exists (szErrorCode• 0), the second row will
contain a brief text description of the error.
Status Records (Header Record – Row 1) Variables for Change Transaction Status
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
1
szSerialNumber
HTML Serial Number
Numeric
12/12
000111222333
Numeric
and "-"
1/2
-1
Merchant's Skipjack-assigned unique
HTML Serial Number.
2
szErrorCode
Error Code
Response Error Code indicating success
or error conditions.
0 = Success
-1 = Invalid Command
-2 = Parameter Missing
-3 = Failed retrieving response
-4 = Invalid Status
-5 = Failed reading security flags
-6 = Developer Serial number not found
-7 = Invalid Serial Number
-8 = Authorization Result Unknown.
Perform Get Status
-51 = Invalid Amount
See also ”Appendix S: Master Error Code
Table”.
3
szNumberRecords
The number of records in the response.
Numeric
1/4
5
4-12
Reserved
Reserved Variables for Future Use
NOTE: AuthorizeEx and
AuthorizeAdditionalEx will return data in
this format:
Reserved
Reserved
Reserved
Page 98
 2009 Skipjack Financial Services
Skipjack Integration Guide
Row1: 12 fields+ Authorize Response
Row 2: 12 fields + Authorize Response
See examples below for more details.
Page 99
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Record (Row 2) Variables for the Change Transaction Status Method
Response Record (Data Record – Row2) is the second and subsequent record(s) returned for
successful transactions (szErrorCode=0) and includes transaction information described in the table
below.
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
1
Serial Number
HTML Serial Number
Numeric
12/12
000111222333
Numeric
and
period
(".")
5/14
Response of 5.1500 =
Five dollars fifteen
cents
Skipjack-assigned unique
HTML serial number.
2
Transaction Amount
Transaction Amount
The Transaction Amount is the
purchase amount to be
Authorized on the Customer's
credit card.
(Response for this
amount has 4
decimals.)
The return of the
TransactionAmount variable
3
Desired Status
Desired status for transaction.
AlphaNumeric
CREDIT
AlphaNumeric
SUCCESSFUL
UNSUCCESSFUL
NOT ALLOWED
The return of the
szDesiredStatus variable.
4
Status Response
The response text of the status
change. The valid entries are:
SUCCESSFUL
UNSUCCESSFUL
NOT ALLOWED
5
Status Response
Message
Detailed text message
describing the reason for the
response.
AlphaNumeric
0/60
Valid or
Status Mismatch
6
Order Number
The Order Number created
during the original
Authorization.
Numeric
and ("/")
1/40
A1234567890
Numeric
and
period
(".")
10/18
10138084223445.009
The return of the
szOrderNumber variable.
7
TransactionID
TransactionID
Unique Audit ID assigned by
Skipjack Transaction Network
for each transaction returned.
Page 100
 2009 Skipjack Financial Services
8-12
Enhanced Function
Response
Skipjack Integration Guide
Applies to enhanced functions
only (Ex) and numbers of fields
returned varies depending on
function applied.
NOTE: AuthorizeEx and
AuthorizeAdditionalEx will
return data in this format:
Row1: 12 fields+ Authorize
Response
Row 2: 12 fields + Authorize
Response
See examples below for more
details.
Page 101
AlphaNumeric
“”,””,””
 2009 Skipjack Financial Services
Skipjack Integration Guide
Examples for Change Transaction Status Method
Request Example 1: Change Transaction Status: Credit – Specifying szOrderNumber
(Error)
<!--Fixed Values-->
<FORM NAME="samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="ABC123">
<INPUT NAME="szAmount" VALUE="100.00">
<INPUT NAME="szDesiredStatus" VALUE="CREDIT">
Response Example 1: No Records Found for Order Number (Error)
"000123456789","-3","","","","","","","","","",""
No Records Found
Request Example 2: Change Transaction Status (Error - Incorrect Amount for Credit)
<!--Fixed Values-->
<FORM NAME="samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="ABC123">
<INPUT NAME="szAmount" VALUE="100.00">
<INPUT NAME="szDesiredStatus" VALUE="CREDIT">
Page 102
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Example 2: Change Transaction Status (Error- Incorrect Amount for Credit)
"000123456789","0","1","","","","","","","","",""
"000123456789","10000","CREDIT","UNSUCCESSFUL","Invalid Amount","ABC123",
"10138084223445.009"
Request Example 3: Change Transaction Status – SplitSettle specifying
szOrderNumber
<!--Fixed Values-->
<FORM NAME=" samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="ABC123">
<INPUT NAME="szAmount" VALUE="5.00">
<INPUT NAME="szDesiredStatus" VALUE="SPLITSETTLE">
Response Example 3: Change Transaction Status – SplitSettle
"000123456789","0","1","","","","","","","","",""
"000123456789","100","SPLITSETTLE","SUCCESSFUL","Valid","ABC123","10138084247034.009"
Request Example 4: Change Transaction Status – Credit specifying szOrderNumber
<!--Fixed Values-->
<FORM NAME=" samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="ABC123">
<INPUT NAME="szAmount" VALUE="8.00">
<INPUT NAME="szDesiredStatus" VALUE="CREDIT">
Response Example 4: Change Transaction Status Credit – Error: Status Mismatch
"000123456789","0","1","","","","","","","","",""
"000123456789","800","CREDIT","UNSUCCESSFUL","StatusMismatch","ABC123","10138084247034.00
9"
Page 103
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 5: Change Transaction Status – Split Settle specifying
szOrderNumber
<!--Fixed Values-->
<FORM NAME=" samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="ABC123">
<INPUT NAME="szAmount" VALUE="1.00">
<INPUT NAME="szDesiredStatus" VALUE="SPLITSETTLE">
Response Example 5: Change Transaction Status – Successful: Split Settle
"000123456789","0","1","","","","","","","","",""
"000123456789","100","SPLITSETTLE","SUCCESSFUL","Valid","ABC123","10138084247034.009"
Request Example 6a and 6b: Change Transaction Status: Authorize
<!--Fixed Values-->
<FORM NAME=" samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_Trans
actionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="ABC123">
<INPUT NAME="szAmount" VALUE="1.00">
<INPUT NAME="szDesiredStatus" VALUE="AUTHORIZE">
Response Example 6a: Authorize Response
"000123456789","0","1","","","","","","","","",""
"000123456789","100","AUTHORIZE","SUCCESSFUL","Valid","ABC123","10138084247456.009"
Response Example 6b: AuthorizeEx Response
"000123456789","0","1","","","","","","","","","","AUTHCODE","szSerialNumber","szTransact
ionAmount","szAuthorizationDeclinedMessage","szAVSResponseCode","szAVSResponseMessage","s
zOrderNumber","szAuthorizationResponseCode","szReturnCode","szIsApproved","szCVV2Response
Code","szCVV2ResponseMessage","szTransactionFileName","szCAVVResponseCode"
"000123456789","150","AUTHORIZEEX","SUCCESSFUL","Valid","20090422100706673","114020335690
13.102","","","","","","000017","000123456789","0","","Y","Card authorized, exact address
match with 5 digit zip code.","20090422100706673","","1","1","P","Not
Processed","11402033569013.102",""
Page 104
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 7: ChangeStatus:CreditEx
<!--Fixed Values-->
<FORM NAME="samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="987654321000">
<INPUT NAME="szDeveloperSerialnumber" VALUE="000123456789">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="998865464">
<INPUT NAME="szAmount" VALUE="1500.00">
<INPUT NAME="ShipToPhone" VALUE="9025551212">
<INPUT NAME="szDesiredStatus" VALUE="CreditEx">
<INPUT NAME="szforcesettlement" VALUE="0">
Response Example 7: ChangeStatus:CreditEx
"000123456789","0","1","","","","","","","","",""
"000123456789","150000","CREDITEX","SUCCESSFUL","Valid","998865464","11402033569015.102",
"","","","",""
Request Example 8: Change Transaction Status: AuthorizeAdditionalEx
<!--Fixed Values-->
<FORM NAME="samplechangetransactionstatus"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?
SJAPI_TransactionChangeStatusRequest" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialnumber" VALUE="987654321000">
<!--Purchase Data-->
<INPUT NAME="szOrderNumber" VALUE="test123">
<INPUT NAME="szAmount" VALUE="6.50">
<INPUT NAME="ShipToPhone" VALUE="9025551212">
<INPUT NAME="szDesiredStatus" VALUE="AuthorizeAdditionalEx">
<INPUT NAME="szforcesettlement" VALUE="0">
Response Example 8: ChangeStatus: AuthorizeAdditionalEx
"000123456789","0","1","","","","","","","","","","AUTHCODE","szSerialNumber","szTransact
ionAmount","szAuthorizationDeclinedMessage","szAVSResponseCode","szAVSResponseMessage","s
zOrderNumber","szAuthorizationResponseCode","szReturnCode","szIsApproved","szCVV2Response
Code","szCVV2ResponseMessage","szTransactionFileName","szCAVVResponseCode"
"000123456789","650","AUTHORIZEADDITIONALEX","SUCCESSFUL","Valid","test123","114020335690
18.102","","","","","","000017","000511327200","650","","Y","Card authorized, exact
address match with 5 digit zip code.","test123","","1","1","P","Not
Processed","11402033569018.102",""
Page 105
 2009 Skipjack Financial Services
Skipjack Integration Guide
Supplemental Transaction Methods
Supplementary methods are those methods that are used in conjunction with the Core methods to
perform more specialized, or tertiary, operations on transactions.
The available Supplementary Methods for transaction processing include the following:
1. Recurring Payments Methods
a) Add Recurring Payment
b) Get Recurring Payments Status
c) Delete Recurring Payment
d) Edit Recurring Payment
2. Batch Upload Methods
a) Batch Authorization
b) Check Batch File Status
c) Modify (Edit) Batch File Status
d) Get Batch File Response
3. Reports API Methods
a) Transaction Detail Report
b) Daily Deposit Summary
c) Batch Summary Report
d) Customized Report
NOTE: For integration details about the Reporting API methods, see the companion
guide Skipjack Reporting API Integration Guide
4. Batch Settlement Methods
a) Close Current Open Batch
b) Get Batch Settlement Status
Page 106
 2009 Skipjack Financial Services
Skipjack Integration Guide
Recurring Payments Overview
Description
The Recurring Payment methods allow a single transaction request to activate a series of automatic
transactions based on a predetermined schedule.
There are nine payment schedules for use with Recurring Payment transactions:
1.
2.
3.
4.
5.
6.
7.
8.
9.
Weekly - Starting Date + 7 Days
Monthly - Every Month
Bi-Weekly - Starting Date + 14 Days
Twice-Monthly - Starting Date + 15 Days
Every Four Weeks - Every Fourth Week
Bi-Monthly - Every Other Month
Quarterly – Every Third Month
Semi-Annually - Twice a Year
Annually – Once a Year
Development Notes about Recurring Payments Transactions
•
Recurring Transactions are scheduled transactions and are not Authorized until the date of the
scheduled transaction arrives. Transaction responses received at the time of submission of an
Add Recurring Payment method to the Skipjack Transaction Network indicates only that the
Recurring Payment transaction data was or was not properly formed.
•
The Skipjack Transaction Network cannot check the expiration of the card against future
scheduled payments. Since most credit cards are reissued every two to four years, avoid
unnecessarily large numbers of recurring transactions scheduled far into the future, otherwise
the recurring transactions may be Declined when the credit card is reissued.
•
Skipjack Transaction Network accepts Recurring Payments for days 1 to 28 in any month.
Therefore, payments falling on the 29th, 30th, and 31st of any month will be returned as
invalid. Move payments falling on these dates into the acceptable date range to ensure the
addition of these Recurring Payments transactions will not be rejected by the Skipjack
Transaction Server.
•
The HTTPS direct POST method of Add Recurring Payment returns a comma-delimited string.
This is not a useful message for displaying in a Web browser. Additional programming
techniques must be employed to convey the results of the request to the Web browser.
•
When a Recurring Payment transaction is entered into the Skipjack Transaction Network, it is
held in the Recurring Payments area of Skipjack Merchant Services. On the recurring date for
the transaction, the transaction is Authorized and moved to the Transaction (Interactive)
Register for processing of the payment. If e-mail responses are enabled, all recipients will
receive the appropriate e-mail message (Approval, Decline, System Failure) for the recurring
transaction at that time.
Page 107
 2009 Skipjack Financial Services
Skipjack Integration Guide
•
The starting and ending dates for the Recurring Payments schedule can be configured.
•
Recurring Payments can be controlled through the Interactive Register or through an
application API. For more information on using the Interactive Register for Recurring
Payments, see the Merchant User Guide.
•
Recurring Payments can be processed as single real-time transactions or within a batch file.
For information about off-line submission of Recurring Payments in batch format, see the
“Batch File Methods for Transaction Processing” section.
•
Do not set the number of payments in a Recurring Payment schedule to an unreasonably high
value (such as 999) because when the credit card is replaced with a new card reaching the
expiration date, any subsequent scheduled transactions will fail. Skipjack Financial Services
suggests limiting the payment schedule to a maximum of 2 years (maximum) worth of
recurring payments in any recurring payment schedule.
Recurring Payment Methods;
The following Recurring Payment methods can be used with transactions:
•
•
•
•
“Add Recurring Payment Method”
“Edit Recurring Payments Method”
“Delete Recurring Payment Method”
“Get Recurring Payment Information Method”
See Also:
•
For usage examples, see the “Scenario 3: Recurring Payments Scenario” section.
Page 108
 2009 Skipjack Financial Services
Skipjack Integration Guide
Add Recurring Payment Method
When Used
The Add Recurring Payment method is used to add one or more scheduled Recurring Payments to a
previously Authorized transaction.
Submitting Requests for Add Recurring Payments
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_RecurringPaymentAdd
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_RecurringPaymentAdd
Development Server Host Name
developer.skipjackic.com
Production Server Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
See Also
•
To see examples of the Add Recurring Payment method in use, see the “Scenario 3: Recurring
Payments Scenario” section.
Transaction Requests for the Add Recurring Payments Method
This section describes the variables sent in transaction data requests for Add Recurring Payments
method.
Variable Name
Variable Description
Required/
Optional
Variable
Type
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
100111222333
Skipjack-assigned unique HTML
serial number.
szDeveloperSerialNumb
er
Developer Serial Number
The Developer Serial Number
assigned to the Skipjack
Account.
Page 109
 2009 Skipjack Financial Services
rtOrderNumber
Skipjack Integration Guide
Recurring Payment Order
Number
Required
AlphaNumeric
1/20
A1234567890
Required
All
Characters
1/40
John Doe
Required
AlphaNumeric
and (',') and
period ('.')
1/40
1 Skipjack Way
Optional
AlphaNumeric
and comma
(',') and
period ('.')
0/40
Apartment 1
Optional
AlphaNumeric
and comma
(',') and
period ('.')
0/40
Lower Level
Optional
AlphaNumeric
and comma
(',') and
period ('.')
0/40
Side Door
Required
AlphaNumeric
1/40
Cincinnati
Required
AlphaNumeric
1/40
OH
Required
AlphaNumeric
and dash
('-')
1/40
12345 or
123456789
The Merchant-defined Order
Number to be associated with
the Recurring Payment.
See also “Appendix I: Unique
Order Numbers” section.
rtName
Customer Billing Name
The billing name of the person
who will be charged.
rtAddress1
Customer’s Billing Street
Address Line 1
The Customer's billing street
address, line 1.
rtAddress2
Customer’s Billing Street
Address Line 2
The Customer's billing street
address, line 2.
rtAddress3
Customer’s Billing Street
Address Line 3
The Customer's billing street
address, line 3.
rtAddress4
Customer’s Billing Street
Address Line 4
The Customer's billing street
address, line 4.
rtCity
Customer's Billing City
The Customer’s billing city. All
Spaces within a City will be
removed.
rtState
Customer’s Billing State
The Customer's Billing State or
Province
rtPostalCode
Customer’s Billing Postal Code
The Customer's billing Zip or
Postal Code.
Page 110
 2009 Skipjack Financial Services
rtCountry
Skipjack Integration Guide
Customer's Billing Country
Optional*
Alpha
1/40
USA, Canada,
UK
Required
Numeric
and dash
('-')
1/12
8005551212 or
800-555-1212
Optional
Numeric
and dash
('-')
1/12
8005551212 or
800-555-1212
Required
Numeric
1/16
4111111111111
11
Required
Numeric
2/2
06
Required
Numeric
4/4
2006
Required
All
Characters
Excluding
comma (",")
1/20
Part 3
Required
Alphanumeric
1/120
Red Shoes Size
12
The Customer’s billing city.
rtCountry is a Required
variable when using Soft
Indicator functionality and using
Paymentech as the Payment
Processor.
See the “Appendix A: Permitted
Country Code” section for
specific Country Codes used for
this variable and any usage
restrictions required by specific
Payment Processors.
rtPhone
Customer's Phone Number
The Customer’s billing phone
number.
rtFax
Customer's Fax Number
The Customer’s billing fax
number.
rtAccountNumber
Customer’s Credit Card Number
The Customer’s billing credit
card number.
rtExpMonth
Customer’s Billing Expiration
Month
The billing Customer’s credit
card expiration month.
rtExpYear
Customer’s Billing Expiration
Month
The billing Customer’s credit
card expiration year of the
Recurring Payment.
rtItemNumber
Item Number
The item number represented in
the order detail for the Recurring
Payment.
rtItemDescription
Item Description
The item description
represented in the order detail of
the Recurring Payment.
Page 111
 2009 Skipjack Financial Services
rtComment
Skipjack Integration Guide
Comment
Optional
All
Characters
0/255
This is a sample
comment.
Required
Numeric
and period
(".")
4/12
1.00
Required
Numeric
and back
slash ("/")
10/10
04/06/2006
Required
Numeric
Only
1/1
2
Any comment assigned to the
Recurring Payment.
rtAmount
Amount Charged
The amount to be charged as
the Recurring Payment.
This amount must be in X.XX
format and must include the
decimal point.
rtStartingDate
Recurring Payment Starting
Date
Starting date of the first
Recurring Payment transaction.
rtFrequency
Recurring Payments Frequency
The frequency to be assigned to
the recurring transactions
according to the schedule
below:
0 = Weekly
(Starting Date + 7 Days)
1 = Bi-Weekly
(Starting Date + 14 Days)
2 = Twice Monthly
(Starting Date + 15 Days)
3 = Monthly
(Every month)
4 = Every Four Weeks
(Every fourth week)
5 = Bi-Monthly
(Every other month)
6 = Quarterly
(Every third month)
7 = Semi-Annually
(Twice a year)
8 = Annually
(Once a year)
Page 112
 2009 Skipjack Financial Services
rtTotalTransactions
Skipjack Integration Guide
Total Number of Recurring
Payments
Required
Numeric
Only
2/2
10
Required
Valid e-mail
characters
1/40
jdoe@skipjack.c
om
Total number of recurring
transactions to be scheduled.
NOTE: Skipjack Financial
Services suggests using a
reasonable number of payments
in your recurring payment
schedule so that no more than 3
years recurring payments are
scheduled. This will prevent
problems (Declines) when
cardholders have new credit
cards issued to replace expired
cards.
rtEmail
Customer's Billing E-mail
Address
Page 113
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Responses for Add Recurring Payments Method
This section describes the transaction responses for the Add Recurring Payments method.
Interpreting the Response Records for Add Recurring Payments Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. The Header Record and the Data Record are combined and only one record is returned for
successful Add recurring Payments Method transactions. This record contains all information
about the Add Recurring Payments as defined in the table below.
2. If an error is encountered, a brief text-based explanation of this error is returned as the second
record.
Response Records Variables for Add Recurring Payments Method
Return
Order
Variable
Description
Variable
Type
Min /
Max
Length
Example
1
Serial
Number
HTML Serial Number
Numeric
12/12
000123456789
Numeric
and
hyphen
(‘-‘)
1/2
-1
Numeric
1/4
5
Skipjack-assigned unique HTML serial
number.
2
Response
Codes
Responses Codes:
0 = Success
-1 = Invalid command
-2 = Parameter missing
-3 = Failed retrieving message
-4 = Invalid Status
-5 = Failed reading security flags
-6 = Developer serial number not found
-7 = Invalid serial number
-8 = Expiration year is not 4 characters
-9 = Credit card has expired
-10 = Invalid starting date
-11 = Failed Adding Recurring Payment
-12 = Invalid Recurring Payment frequency
-15 = Failed
-16 = Invalid expiration month
See also ”Appendix S: Master Error Code
Table”.
3
Number of
Records
Number of records in the response.
Page 114
 2009 Skipjack Financial Services
Skipjack Integration Guide
4
Recurring
Payment ID
Recurring Payment ID
Alphanumeric
and
decimal
(‘.’)
10/18
R1304216213943.0
23
5
Order
Number
Order Number assigned to all the recurring
transactions in that Recurring Payment.
AlphaNumeric
1/20
ORDER12345
6-12
Reserved
Reserved
Reserved
Reserved
Reserved
Examples for Add Recurring Payments Method
Request Example 1: Add Recurring Payments Request
<!--Fixed Values-->
<FORM NAME="sampleaddrecurringpaymentsrequest"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentAdd"
METHOD=POST>
<INPUT NAME="serialnumber" VALUE="111222333444">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!--Card Holder Data-->
<INPUT NAME="rtName" VALUE="John Doe">
<INPUT NAME="rtCity" VALUE="Cincinnati">
<INPUT NAME="rtState" VALUE="OH">
<INPUT NAME="rtPostalCode" VALUE="123456">
<!--Credit Card Data-->
<INPUT NAME="rtAccountnumber" VALUE="4111111111111111">
<INPUT NAME="rtExpMonth" VALUE="08">
<INPUT NAME="rtExpYear" VALUE="2006">
<!--Purchase Data-->
<INPUT NAME="rtItemNumber" VALUE="DEF123">
<INPUT NAME="rtItemDescription" VALUE="SizeBiggie">
<INPUT NAME="rtAmount" VALUE="1.00">
<!—Recurring Payment Data-->
<INPUT NAME="rtStartingDate" VALUE="08/12/2006">
<INPUT NAME="rtFrequency" VALUE="7">
<INPUT NAME="rtTotalTransactions" VALUE="02">
Response Example 1: Add Recurring Payments Records – Successful
"111222333444","0","1","R0791220832082.009","07092005-100a","","","","","","",""
Page 115
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 2: Add Recurring Payments Request
<!--Fixed Values-->
<FORM NAME="sampleaddrecurringpaymentsrequest"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentAdd"
METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="111222333444">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!--Card Holder Data-->
<INPUT NAME="rtName" VALUE="John Doe">
<INPUT NAME="rtCity" VALUE="Cincinnati">
<INPUT NAME="rtState" VALUE="OH">
<INPUT NAME="rtPostalCode" VALUE="123456">
<!--Credit Card Data-->
<INPUT NAME="rtAccountnumber" VALUE="4111111111111111">
<INPUT NAME="rtExpMonth" VALUE="08">
<INPUT NAME="rtExpYear" VALUE="2006">
<!--Purchase Data-->
<INPUT NAME="rtItemNumber" VALUE="DEF123">
<INPUT NAME="rtItemDescription" value="part123">
<INPUT NAME="rtAmount" VALUE="1.00">
<!—Recurring Payment Data-->
<INPUT NAME="rtStartingDate" VALUE="08/06/2006">
<INPUT NAME="rtFrequency" VALUE="3">
<INPUT NAME="rtTotalTransactions" VALUE="12">
Response Example 2: Add Recurring Payments Records – Error: Starting Date
"111222333444","-10","1","","","","","","","","",""
Invalid starting date entered. Date must not be more than 60 days earlier than the
current date: (12/12/2006)
Page 116
 2009 Skipjack Financial Services
Skipjack Integration Guide
Edit Recurring Payments Method
When Used
The Edit Recurring Payment method is used to edit a previously submitted (added) Recurring
Payment transaction.
Submitting Requests for Edit Recurring Payments
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_RecurringPaymentEdit
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_RecurringPaymentEdit
Development Server Host Name
developer.skipjackic.com
Production Server Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
See Also
•
To see examples of the Edit Recurring Payment method in use, see the “Scenario 3: Recurring
Payments Scenario” section.
Transaction Requests for Edit Recurring Payments Method
This section describes the variables sent in transaction data requests for the Edit Recurring
Payments Method.
Variable Name
Variable Description
Required /
Optional
Variable
Type
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
100200300400
Required
Alphanumeric
and
decimal (‘.’)
10/18
R13042162139
43.023
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumbe
r
Developer Serial Number
The Developer Serial Number
assigned to the Skipjack
Account.
szPaymentId
Recurring Payment ID
The unique ID assigned to an
individual Recurring Payment.
Page 117
 2009 Skipjack Financial Services
szTransactionDate
Skipjack Integration Guide
Transaction Date
Conditional
Numeric
and
forward
slash (‘/’)
10/10
12/05/2006
Required
AlphaNumeric
1/40
Jane Doe
Date assigned to an individual
Recurring Payment
transaction.
MM/DD/YYYY format.
NOTE: If the
szTransactionDate variable is
submitted, only the individual
transaction matching that date
within a Recurring Payment
schedule will be edited.
If this variable is NOT
SUPPLIED, ALL scheduled
Recurring Payment
transactions matching the
request variables submitted
will be edited.
rtName
Customer Billing Name
The billing name of the person
who will be charged.
rtEmail
Customer's Billing E-mail
Address
Required
Valid
e-mail
characters
1/40
jdoe@skipjack.
com
rtAddress1
Customer’s Billing Street
Address Line 1
Required
AlphaNumeric
and comma
(',') and
period ('.')
1/40
1 Skipjack Way
Optional
AlphaNumeric
comma (',')
and period
('.')
0/40
Apartment 1
Optional
AlphaNumeric
comma (',')
and period
('.')
0/40
Lower Level
Optional
AlphaNumeric
comma (',')
and period
('.')
0/40
Side Door
The Customer's billing street
address, line 1.
rtAddress2
Customer’s Billing Street
Address Line 2
The Customer's billing street
address, line 2.
rtAddress3
Customer’s Billing Street
Address Line 3
The Customer's billing street
address, line 3.
rtAddress4
Customer’s Billing Street
Address Line 4
The Customer's billing street
address, line 4.
Page 118
 2009 Skipjack Financial Services
rtCity
Skipjack Integration Guide
Customer's Billing City
Required
AlphaNumeric
1/40
Cincinnati
Required
AlphaNumeric
1/40
OH
Required
AlphaNumeric
and dash ('')
1/40
12345 or
123456789
Optional*
Alpha
1/40
USA, Canada,
UK
Required
Numeric
and dash ('')
0/12
8005551212 or
800-555-1212
Optional
Numeric
and dash ('')
0/12
8005551212 or
800-555-1212
All Spaces within a City will be
removed
rtState
Customer’s Billing State
The Customer's Billing State or
Province
rtPostalCode
Customer’s Billing Postal Code
The Customer's billing Zip or
Postal Code.
rtCountry
Customer's Billing Country
The Customer’s billing city.
rtCountry is a Required
variable when using Soft
Indicator functionality and
using Paymentech as the
Payment Processor.
See the “Appendix A:
Permitted Country Code”
section for specific Country
Codes used for this variable
and any usage restrictions
required by specific Payment
Processors.
rtPhone
Customer's Phone Number
The Customer’s billing phone
number.
rtFax
Customer's Fax Number
The Customer’s billing fax
number.
Page 119
 2009 Skipjack Financial Services
rtAccountNumber
Skipjack Integration Guide
Customer’s Credit Card
Number
Required
Numeric
5/16
411111111111
111
Required
Numeric
2/2
12
Required
Numeric
4/4
2009
Required
All
Characters
Excluding
comma (",")
and (‘&’)
ampersand
1/20
001
Required
Alphanumeric
1/120
Monthly
Hosting
Optional
All
Characters
0/255
This is a
sample
comment
Required
AlphaNumeric
1/40
ORD123456
The Customer’s billing credit
card number.
NOTE: Spaces are not
permitted.
You can send only the last five
digits of the Customers credit
card number. This can be
obtained using the “Get
Recurring Payment
Information Method”.
rtExpMonth
Customer’s Billing Expiration
Month
The billing Customer’s credit
card expiration month.
rtExpYear
Customer’s Billing Expiration
Month
The billing Customer’s credit
card expiration year of the
Recurring Payment.
rtItemNumber
Item Number
The item number represented
in the order detail for the
Recurring Payment.
rtItemDescription
Item Description
The item description
represented in the order detail
of the Recurring Payment.
rtComment
Comment
Any comment assigned to the
Recurring Payment.
rtOrderNumber
Order Number
The Merchant-assigned new
Order Number for this
Recurring Payment
transaction.
See also “Appendix I: Unique
Order Numbers”.
Page 120
 2009 Skipjack Financial Services
rtAmount
Skipjack Integration Guide
Amount Charged
Required
The amount to be charged as
the Recurring Payment.
Numeric
and
decimal (‘.’)
4/12
3.00
This amount must be in X.XX
format and must include the
decimal point.
Transaction Responses for Edit Recurring Payments Method
This section lists and describes the response variables returned for Edit Recurring Payments method.
Interpreting the Response Records for Edit Recurring Payments Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. A Header Record (Data Record) is the only record returned for successful transactions and
contains information about the subsequent records in addition to Response Record data, see
table below for information.
2. If an error is encountered, a text-based explanation of this error is returned as the second record.
Response Records (Header Record) Variables for Edit Recurring Payments Method
Return
Order
Variable
Description
Variable
Type
Min /
Max
Length
Example
1
Serial
Number
HTML Serial Number
Numeric
12/12
000123456789
Numeric
1/3
0
Skipjack-assigned unique HTML serial number.
2
Response
Codes
Responses Codes:
0 = Success
-1 = Invalid Command
-2 = Parameter Missing
-3 = Failed retrieving message
-4 = Invalid Status
-5 = Failed reading security flags
-6 = Developer serial number not found
-7 = Invalid serial number
-8 = Expiration year is not 4 characters
-9 = Credit card has expired
-10 = Invalid starting date
-14 = Failed editing of Recurring Payment
-16 = Invalid expiration month
Page 121
 2009 Skipjack Financial Services
Skipjack Integration Guide
See also ”Appendix S: Master Error Code
Table”.
3-12
Reserved
Reserved.
Reserved
Reserved
Reserved
Examples for Edit Recurring Payments Method
Request Example 1: Edit Recurring Payments Request
<!--Fixed Values-->
<FORM NAME="sampleeditrecurringpaymentsrequest"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentEdit"
METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000055512123">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!--Card Holder Data-->
<INPUT NAME="rtName" VALUE="John Doe">
<INPUT NAME="rtEmail" VALUE="JDoe@office.com">
<INPUT NAME="rtAddress1" VALUE="1 Skipjack Way">
<INPUT NAME="rtCity" VALUE="Cincinnati">
<INPUT NAME="rtPostalCode" VALUE="123456">
<INPUT NAME="rtPhone" VALUE="8005551212">
<!--Credit Card Data-->
<INPUT NAME="rtAccountnumber" VALUE="4111111111111111">
<INPUT NAME="rtExpMonth" VALUE="08">
<INPUT NAME="rtExpYear" VALUE="2006">
<!--Purchase Data-->
<INPUT NAME="rtItemNumber" VALUE="Item123">
<INPUT NAME="rtItemDescription" VALUE="Partnumber127">
<INPUT NAME="rtAmount" VALUE="1.00">
<INPUT NAME="rtOrderNumber" VALUE="12588963">
<INPUT NAME="szPaymentId" VALUE="12345678998">
Response Example 1: Edit Recurring Payments – Success
"000055512123","0","","","","","","","","","",""
Page 122
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 2: Edit Recurring Payments
<!--Fixed Values-->
<FORM NAME="sampleeditrecurringpaymentsrequest"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentEdit"
METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000055512123">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!--Card Holder Data-->
<INPUT NAME="rtName" VALUE="John Doe">
<INPUT NAME="rtEmail" VALUE="JDoe@office.com">
<INPUT NAME="rtAddress1" VALUE="1 Skipjack Way">
<INPUT NAME="rtCity" VALUE=" Cincinnati">
<INPUT NAME="rtPostalCode" VALUE="123456">
<INPUT NAME="rtPhone" VALUE="8005551212">
<!--Credit Card Data-->
<INPUT NAME="rtAccountnumber" VALUE="4111111111111111">
<INPUT NAME="rtExpMonth" VALUE="08">
<INPUT NAME="rtExpYear" VALUE="2006">
<!--Purchase Data-->
<INPUT NAME="rtItemNumber" VALUE="Item123">
<INPUT NAME="rtItemDescription" VALUE="Partnumber127">
<INPUT NAME="rtAmount" VALUE="1.00">
<INPUT NAME="rtOrderNumber" VALUE="12588963">
<INPUT NAME="szPaymentId" VALUE="">
Response Example 2: Edit Recurring Payments – Error: Missing szPaymentId
999888777666,"-2","","","","","","","","","",""
Parameter Missing:(szPaymentId)
Page 123
 2009 Skipjack Financial Services
Skipjack Integration Guide
Delete Recurring Payment Method
The Delete Recurring Payment method is used to delete any or all Recurring Payments previously
created using the Add Recurring Payment method.
Submitting Requests for Delete Recurring Payment Method
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_RecurringPaymentDelete
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_RecurringPaymentDelete
Development Server Host
Name
developer.skipjackic.com
Production Server Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
See Also
•
To see examples of the Delete Recurring Payment method in use, see the “Scenario 3:
Recurring Payments Scenario” section.
Transaction Requests for Delete Recurring Payment Method
Variable Name
Variable Description
Required /
Optional
Variable
Type
Min / Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
100200300400
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumb
er
Developer Serial Number
The Developer Serial Number
assigned to the Skipjack
Account.
Page 124
 2009 Skipjack Financial Services
szPaymentId
Skipjack Integration Guide
Recurring Payment ID
Required
Alphanumeric
and decimal
(‘.’)
10/18
R130421621394
3.023
Conditional
Numeric
and back
slash (‘/’)
12/12
11/28/2009
A unique ID assigned to an
individual Recurring
Payment.
NOTE: Including the
szPaymentId variable in a
request will delete all
Recurring Payments
outstanding in the payment
schedule.
szTransactionDate
Transaction Date
The date assigned to an
individual (scheduled)
Recurring Payment
transaction.
Use MM/DD/YYYY format.
NOTE: Including the
szTransactionDate variable in
the request will ONLY DELETE
the individual transaction
matching the specified date
within this Recurring Payment
schedule.
Transaction Responses for Delete Recurring Payments Method
This section lists and describes the response variables returned for Delete Recurring Payments
method.
Interpreting the Response Records for Delete Recurring Payments Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. A successful transaction response for a Delete Recurring Payments transaction returns only a
Status Record (Header Record) with HTML Serial Number, Response Code, and a sting of
empty (Reserved) values. See the table below for detailed information.
2. If an error is encountered, a brief text-based explanation of this error is returned as the second
record.
Page 125
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Records (Header Record) Variables for Delete Recurring Payments
Return
Order
Variable
Description
Variable
Type
Min /
Max
Length
Example
1
Serial
Number
HTML Serial Number
Numeric
12/12
000123456789
Numeric
1/3
-10
Reserved
Reserved
Reserved
Skipjack-assigned unique HTML serial
number.
2
Response
Codes
Responses Codes:
0 = Success
-1 = Invalid Command
-2 = Parameter Missing
-3 = Failed retrieving message
-4 = Invalid Status
-5 = Failed reading security flags
-6 = Developer serial number not found
-7 = Invalid serial number
-13 = Failed Delete of Recurring Payment
-15 = Failed
See also ”Appendix S: Master Error Code
Table”.
3-14
Reserved
Reserved
Examples for Delete Recurring Payment Method
Request Example 1: Delete Recurring Payments Request specifying szPaymentId
<!--Fixed Values-->
<FORM NAME="sampledeleterecurringpaymentsinfo"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentDelete
" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="111222333444">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Recurring Payment Data-->
<INPUT NAME="szPaymentId" VALUE="R802852117715.022">
Response Example 1: Delete Recurring Payment specifying szPaymentId – Successful
"111222333444","0","","","","","","","","","",""
Page 126
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 2: Delete Recurring Payments Request specifying szTransactionDate
<!--Fixed Values-->
<FORM NAME="samplegeterecurringpaymentsinfo"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentDelete
" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Recurring Payment Data-->
<INPUT NAME="rtTransactionDate" VALUE="06/10/2006">
Response Example 2: Delete Recurring Payment specifying szTransactionDate –
Successful
"000123456789","0","","","","","","","","","",""
Request Example 3: Delete Recurring Payments Request specifying szTransactionDate
<!--Fixed Values-->
<FORM NAME="samplegeterecurringpaymentsinfo"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentDelete
" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Recurring Payment Data-->
<INPUT NAME="rtTransactionDate" VALUE="01/02/2006">
Response Example 3: Delete a Recurring Payment – Error: Failed Deleting
"000012345678","-13","","","","","","","","","",""
Failed deleting recurring payment
Page 127
 2009 Skipjack Financial Services
Skipjack Integration Guide
Get Recurring Payment Information Method
(Also referred to as Request Recurring Payment Information Method)
Description
The Get Recurring Payment Information method allows the retrieval of all information about Recurring
Payments for a Merchant’s Account.
When Used
Use the Get Recurring Payments Information method to obtain information about Recurring
See Also
•
To see examples of the Get Recurring Payment method in use, see the “Scenario 3: Recurring
Payments Scenario” section.
Transaction Requests for Get Recurring Payment Information
Submitting Requests for Get Recurring Payment Information
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_RECURRINGPAYMENTREQUEST
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_RECURRINGPAYMENTREQUEST
Development Server
Host Name
developer.skipjackic.com
Production Server
Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
Transaction Requests for Get Recurring Payments Method
Variable
Description
Required /
Optional
Variable
Type
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
100987654321
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumber
Developer Serial Number
The Developer Serial
Number assigned to the
Skipjack Account.
Page 128
 2009 Skipjack Financial Services
szPaymentId
Skipjack Integration Guide
Recurring Payment ID
Conditional
Alphanumeric
and
decimal
(‘.’)
10/18
R1304216213943.023
Conditional
Numeric
10/10
11/28/2009
Unique identifier (ID)
assigned to an individual
Recurring Payment.
NOTE: If this variable is
sent in the request all
transactions will be
retrieved for the individual
Recurring Payment. If this
variable is not sent, all
Recurring Payments for the
Merchant will be returned.
szTransactionDate
Transaction Date
and back
slash (‘/’)
Date assigned to an
individual transaction
within a Recurring
Payment. Use
MM/DD/YYYY format.
NOTE: If only the
szTransactionDate variable
is sent in the request and
szPaymentId is not sent,
this variable will be
ignored. If
szTransactionDate and
szPaymentId are both sent
in the request only
information about the
Recurring Payment for the
SPECIFIED DATE will be
returned.
NOTE: Supplying only Required Variables will list ALL Recurring Payments records for the Merchant Account .
Transaction Response for Get Recurring Payment Information
This section lists and describes the response variables returned for Get Recurring Payments method.
Interpreting the Response Records for Get Recurring Payment Information Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records returned are formatted as followed:
1. The Status Record (Header Record) is the first record returned and contains information about the
subsequent records, see table below for information.
2. If an error is encountered, a brief text-based explanation of this error is returned as the second
record.
Page 129
 2009 Skipjack Financial Services
Skipjack Integration Guide
Status Records (Header Record) Variables for Get Recurring Payment Information
Method
Return
Order
Variable
Description
Variable
Type
Min /
Max
Length
Example
1
Serial Number
HTML Serial Number
Numeric
12/12
000123456789
Numeric
1/3
-12
Skipjack-assigned unique HTML serial number.
2
Response
Codes
Responses Codes:
0 = Success
-1 = Invalid Command
-2 = Parameter Missing
-3 = Failed retrieving message
-4 = Invalid Status
-5 = Failed reading security flags
-6 = Developer serial number not found
-7 = Invalid serial number
See also ”Appendix S: Master Error Code
Table”.
3
Number of
Records
Number of records in the response
Numeric
1/4
10
4-14
Reserved
Reserved
Reserved
Reserved
Reserved
Page 130
 2009 Skipjack Financial Services
Skipjack Integration Guide
Interpreting the Response Records (Data Records) for Get Recurring Payment
Information Method
This section contains the responses returned for the Get Recurring Payment Information method.
The Response Records (Data Records) are returned as the second and subsequent records for
successful Get Recurring Payment Information transactions and these records include the information
listed below.
Response Records (Data Records) returned for Get Recurring Payment Method
Information Method
Return
Order
Variable Name
Variable Description
Variable
Type
Min /
Max
Length
Example
1
HTML Serial Name
HTML Serial Number
Numeric
12/12
000111222333
AlphaNumeric
12/12
100987654321
Alphanumeric and
decimal (‘.’)
10/18
R123456789.111
Alphanumeric
1/40
Jane Doe
Numeric
1/2
12
Numeric
3/12
1200
Skipjack-assigned unique HTML
serial number.
2
Developer Serial
Number
Developer Serial Number
The Developer Serial Number
assigned to the Skipjack Account.
3
Recurring Payment ID
Recurring Payment ID
The unique Recurring Payment ID
generated by the Skipjack
Transaction Server and assigned
to the individual Recurring
Payment.
4
Customer’s Name
The new Customer name for this
payment/transaction.
Return of the rtName variable.
5
Payment Frequency
The frequency of the Recurring
Payment schedule.
Return of the rtFrequency
variable.
6
Recurring Amount
Recurring Payment Amount
The amount for the scheduled
Recurring Payments.
Page 131
 2009 Skipjack Financial Services
7
Transaction Date
Skipjack Integration Guide
Date assigned to and individual
transaction Recurring Payment in
MM/DD/YYYY format.
Numeric and
back slash
(‘/’)
12/12
08/25/2009
Numeric and
back slash
(‘/’)
12/12
06/12/2007
Return of the rtTransactionDate
variable.
NOTE: If this variable is supplied,
only the individual transaction
within a Recurring Payment record
schedule will be edited. If this
variable is NOT SUPPLIED, the
payment is globally edited for ALL
scheduled payments.
8
First Payment/Payment
Date
The date of the first Recurring
Payment in MM/DD/YYYY format.
In the case of a transaction this
will be the payment date not the
starting date.
9
Total Transactions
The total number of payments
recognized for this Recurring
Payment transaction.
Numeric
1/2
15
10
Remaining Transactions
The number of remaining
transactions for this Recurring
Payments.
Numeric
1/2
10
11
Customer E-mail
Address
The new Customer e-mail
address for this
transaction/payment.
Valid E-mail
Characters
1/60
jdoe@home.com
AlphaNumeric and
(',') and ('.')
1/40
1 Skipjack Way
AlphaNumeric and
(',') and ('.')
0/40
Apartment 1
AlphaNumeric and
(',') and ('.')
0/40
Lower Level
Return of the rtEmail variable.
12
Customer Address 1
Customer's Billing Street Address,
line 1.
Return of rtAddress1 variable.
13
Customer Address 2
Customer's Billing Street Address,
line 2.
Return of the rtAddress2 variable.
14
Customer Address 3
Customer's Billing Street Address,
line 3.
Return of the rtAddress3 variable.
Page 132
 2009 Skipjack Financial Services
15
Customer Address 4
Skipjack Integration Guide
Customer's Billing Street Address,
line 3.
AlphaNumeric and
(',') and ('.')
0/40
Side Door
AlphaNumeric
1/40
Cincinnati
AlphaNumeric
1/40
OH
AlphaNumeric and
dash ('-')
1/40
12345 or
123456789
Alpha
1/40
USA, Canada,
UK
Numeric and
dash ('-')
1/12
8005551212 or
800-555-1212
Numeric and
dash ('-')
0/12
8005551212 or
800-555-1212
Numeric
1/16
12345
Numeric
2/2
08
Return of the rtAddress4 variable.
16
Billing City Name
Customer's Billing City.
All Spaces within a City will be
removed
Return of the rtCity variable.
17
Customer’s Billing State
Customer's Billing State /
Province.
Return of the rtState variable.
18
Customer’s Postal Code
Customer's Billing Zip/Postal
Code
Return of the rtPostalCode
variable.
19
Customer’s Country
Customer's Billing Country.
Return of the rtCountry variable.
20
Customer's Phone
Number
Customer's Phone Number.
Return of the rtPhone variable.
21
Customer's Fax Number
Customer's Fax Number.
Return of the rtFax variable.
22
Customer’s Credit Card
Number
Customer’s Credit Card Number
Returns the Last 5 digits of the
Customer’s credit card number
used for the Recurring Payment.
Return of the rtAccountnumber
variable.
23
Customer’s Billing
Expiration Month
Customer’s Billing Expiration
Month.
Return of the rtExpMonth variable.
Page 133
 2009 Skipjack Financial Services
24
Customer’s Billing
Expiration Year
Skipjack Integration Guide
Customer’s Billing Expiration
Year.
Numeric
4/4
2006
All
Characters
Excluding
(‘,’)
1/20
12323
All
Characters
Excluding
(‘,’)
1/120
Red Shirt
All
Characters
0/255
This is a
comment.
AlphaNumeric
1/20
ORDER12345
Return of the rtExpYear variable.
25
Item Number
Itemnumber represented in the
order detail
Return of the rtItemNumber
variable.
26
Item Description
The item description represented
in the order detail.
Return of the rtItemDescription
variable.
27
Comment
The comment about the Recurring
Payment.
Return of the rtComment variable.
28
Order Number
The new Order Number for this
payment/transaction.
Return of the rtOrdernumber
variable.
Examples for Get Recurring Payment Information Method
Request Example 1: Get Recurring Payments Request specifying szTransactionDate
<!--Fixed Values-->
<FORM NAME="samplegeterecurringpaymentsinfo"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentReques
t" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="111222333444">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Recurring Payment Data-->
<INPUT NAME="rtTransactionDate" VALUE="08/12/2006">
Response Example 1: Get Recurring Payment Information specifying
szTransactionDate
"111222333444","0","1","","","","","","","","",""
"111222333444","999888777666","R802852117715.022","Recur1","0","1.2300","08/12/2006","0",
"0","adrian@skipjack.com","2230 Park Avenue","line 2","line 3","line4","Cincinnati",
"OH","45206","USA","513-588-2100","513-588-2101","22225","12","2007"
"Item002","ItemDesc","Comment","101"
Page 134
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 2: Get Recurring Payments Request specifying szPaymentId
<!--Fixed Values-->
<FORM NAME="samplegeterecurringpaymentsinfo"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentReques
t" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="222333444555">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Recurring Payment Data-->
<INPUT NAME="szPaymentId" VALUE="R802852117715.022">
Response Example 2: Get Recurring Payment Information specifying szPaymentId –
Success
This example returns all the Recurring Payments (3 records) with the TransactionId (szPaymentId)
highlighted. Dates and PaymentId highlighted for emphasis.
"222333444555","0","3","","","","","","","","",""
"222333444555","987654321000","R802852117715.022","Recur1","0","1.2300","05/15/2006","0",
"0","adrian@skipjack.com","2230 Park Avenue","line 2","line 3","line
4","Cincinnati","OH","45206","USA","513-588-2100","513-5882101","22225","12","2007","Item002","ItemDesc","Comment","101"
"222333444555","987654321000","R802852117715.022","Recur1","0","1.2300","06/15/2006","0",
"0","adrian@skipjack.com","2230 Park Avenue","line 2","line 3","line
4","Cincinnati","OH","45206","USA","513-588-2100","513-5882101","22225","12","2007","Item002","ItemDesc","Comment","101"
"222333444555","987654321000","R802852117715.022","Recur1","0","1.2300","07/15/2006","0",
"0","adrian@skipjack.com","2230 Park Avenue","line 2","line 3","line
4","Cincinnati","OH","45206","USA","513-588-2100","513-5882101","22225","12","2007","Item002","ItemDesc","Comment","101"
Request Example 3: Get Recurring Payments Request specifying szPaymentId
<!--Fixed Values-->
<FORM NAME="samplegeterecurringpaymentsinfo"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_RecurringPaymentReques
t" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000012365478">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Recurring Payment Data-->
<INPUT NAME="szPaymentId" VALUE="R802852117715.099">
Response Example 3: Get Recurring Payment Information – Error: No Records Found
"000012365478","-3","","","","","","","","","",""
No Records Found
Page 135
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Settlement Methods
Transaction Settlement is the process of moving funds for Authorized transactions into the Merchant’s
Account (bank account). Transaction Settlement can be accomplished in a number of ways, some of
which can only be performed using the Merchant Interface while others can be performed using the
Batch Settlement APIs. Each is identified in this section.
Available Only Though Merchant Services
Some transaction Settlement functions and options can only be performed using the Merchant
Services interface, including:
•
•
•
•
•
Freeze Batch
Thaw Batch
Re-open Batch
Delete Batch
View Transactions in a Batch
For information about the above mentioned Batch Settlement functions that must be configured using
the Merchant Services Interface, see the Skipjack Merchant Services Guide.
Performed using Batch Settlement API Methods
The following Batch Settlement methods can be completed using the API methods and are discussed
in this section:
•
•
Close Current Open Batch
Get Batch Settlement Status
Page 136
 2009 Skipjack Financial Services
Skipjack Integration Guide
Close Current Open Batch Method
Description
The Close Current Open Batch method is used to close and send transactions that currently are in
the Settlement queue to the Merchant Account.
When Used
The Close Current Open Batch method is designed to replace sending a Force Settle flag
(szForceSettlement) for a transaction within a batch.
Any transactions that are marked Pending Settle (But not Pending Manual Settle) will settle as a
batch as soon as possible. Transactions marked Pending Manual Settle will move to a new open
batch, and remain Unsettled.
Closing an open batch is not a command to process a batch. That action depends on the Merchant’s
Batch Settlement preferences. For information about these Merchant Services configured options,
see the Batch Settlement information in the Skipjack Merchant Services Guide.
See Also
•
•
See also the “Change Transaction Status Method” section for more information about using
the szForceSettlement variable (flag).
For usage examples of the Close Current Open Batch method, see the “Scenario 4: Batch
Settlement Scenario” section.
Submitting Requests for the Close Current Open Batch Method
Development
Server
https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_BATCHSETTLECLOSEOPENBATCH
Production
Server:
https://www.skipjackic.com/scripts/EvolvCC.dll?SJAPI_BATCHSETTLECLOSEOPENBATCH
Development
Server Host
Name
developer.skipjackic.com/
Production
Server Host
Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
Page 137
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Request Variables for Close Current Open Batch Method
Variable Name
Description
Required/
Optional
Type
Min/Max
Length
Example
szSerialNumber
HTML Serial
Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
123412341234
Skipjack-assigned
unique HTML serial
number.
szDeveloperSerialNumber
Developer Serial
Number
The Developer
Serial Number
assigned to the
Skipjack Account.
Interpreting the Transaction Responses for the Close Current Open Batch Method
Records are returned as text strings in comma-delimited format with a carriage return/line feed
(CR/LF) record delimiters. The records are formatted with the following values:
1. The Status Record (Header Record) is the only record returned for successful Close
Current Open Batch method transaction and this record includes: HTML Serial Number,
Response Code, and Reserved fields.
2. If an error is encountered in the transaction, the second record returned is a brief text message
describing the error that occurred.
Page 138
 2009 Skipjack Financial Services
Skipjack Integration Guide
Status Record (Header Record) Responses for the Close Current Open Batch Method
Return
Order
Variable
Description
Variable
Type
Min / Max
Length
Example
1
SerialNumber
HTML Serial Number
Numeric
12/12
000111222333
Numeric
1/2
0
Reserved
Reserved
Reserved
Skipjack-assigned unique
HTML serial number.
2
Status Code
Status Code
The Status Code associated
with the success or failure of
the Close Current Open
Batch transaction.
0 = Success
1 = Call Failed
-1 = Invalid Command
-2 = Parameter Missing
-3 = No records found
-15 = Failure
-503 = Request timed out
See also ”Appendix S:
Master Error Code Table”.
3-13
Reserved
Reserved
Request Example 1: Close Current Open Batch Method
<!--Fixed Values-->
<FORM NAME="sampleclosecurrentopenbatch"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_BATCHSETTLECLOSEOPENBA
TCH" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000111222333">
<INPUT NAME="szDeveloperSerialNumber"VALUE="999888777666">
Response Example 1: Close Current Open Batch Method – Success
"000111222333","0","","","","","","","","","",""
Request Example 2: Close Current Open Batch Method
<!--Fixed Values-->
<FORM NAME="sampleclosecurrentopenbatch"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_BATCHSETTLECLOSEOPENBA
TCH" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="">
<INPUT NAME="szDeveloperSerialNumber"VALUE="999888777666">
Page 139
 2009 Skipjack Financial Services
Skipjack Integration Guide
Response Example 2: Close Current Open Batch Method – Error (Parameter Missing)
"000123456789","-2","","","","","","","","","",""
Parameter Missing: (szSerialNumber)
Page 140
 2009 Skipjack Financial Services
Skipjack Integration Guide
Get Batch Settlement Status Method
Description
The Get Batch Settlement Status method is used to query the status of a Settlement batch.
When Used
The Get Batch Settlement Status is used to obtain the settlement history for a specified date and
Batch Number for a Skipjack Merchant Account.
See Also
• For usage examples of the Get Batch Settlement Status method see the “Scenario 4: Batch
Settlement Scenario” section.
Submitting Requests for the Get Batch Settlement Status Method
Development
Server
https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_BATCHSETTLEGETSTATUSREQUEST
Production
Server
https://www.skipjackic.com/scripts/evolvcc.dll?SJAPI_BATCHSETTLEGETSTATUSREQUEST
Development
Server Host
Name
developer.skipjackic.com/
Production
Server Host
Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
Page 141
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Request Variables for the Get Batch Settlement Status
Method
Variable Name
Description
Required/
Optional
Type
Min/Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
123412341234
Optional
Numeric
12/12
1234567891012
Required
Numeric
12/12
01/25/2009
Optional
Numeric
12/12
12/25/2009
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumber
The Developer Serial
Number
The Developer Serial
Number assigned to the
Skipjack Account.
szSkipjackBatchNumber
Skipjack Batch Number
The unique batch
identification (ID) number
assigned internally to the
batch when it is
uploaded.
szDateFrom
Date Range From
Beginning date for the
date range you wish to
query.
Use MM/DD/YYYY
format.
szDateThru
Date Range Ending
The ending date for the
date range you wish to
query.
Use MM/DD/YYYY
format.
Page 142
 2009 Skipjack Financial Services
szShowDeletedClosed
Skipjack Integration Guide
Show Deleted or Closed
transactions.
Optional
Alpha
1/1
Y
This variable allows you
select the display of
Deleted and Closed
Batches.
Permitted Values
Y= Show Deleted or
Closed
N= Do not show deleted
or Closed
Transaction Responses for the Get Batch Settlement Status Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. The Status Record (Header Record) is the first record returned and contains information about the
subsequent records to follow and is formatted as follows: HTML Serial Number, Response
Code, and Number of Records followed by empty (Reserved) fields. If an error is encountered,
the second record returned is a brief text message briefly describing the error that occurred.
2. The Response Records (Data Records) are the second and subsequent records returned for
successful Get Batch Settlement Status requests. These records contain the return variables
listed in the order below.
Transaction Responses for the Get Batch Settlement Status Method
Return
Order
Variable
Description
Variable
Type
Min /
Max
Length
Example
1
HTML Serial Number
HTML Serial Number
Numeric
12/12
000099146970
Numeric
12/12
987654321012
Skipjack-assigned unique
HTML serial number.
2
Skipjack Batch Number
Batch Number
The unique batch
identification (ID) number
assigned internally to the
batch when it is uploaded.
Page 143
 2009 Skipjack Financial Services
3
Batch Status
Skipjack Integration Guide
Batch Status
Numeric
1/1
2
Numeric
1/1
01
Numeric and
colon (‘:’) and
back slash
(‘/’) and space
(‘ ‘)
17/20
11/22/06 01:07:02
Numeric and
colon (‘:’) and
back slash
(‘/’) and space
(‘ ‘)
17/20
11/22/06 11:07:02
Valid values:
2= Open
3= Closed
4= Completed
5= Deleted
6= Processing
7= Inactive
8= Failed
4
Status
Status
Valid values:
0 = Valid/Thawed
1= Frozen
5
Opened Date
Opened Date and Time
The date and time that the
batch was opened, that is
that date and time when a
new batch was created in
Skipjack to receive new
transactions.
Returned in MM/DD/YY
HH:MM:SS format.
6
Closed Date
Batch Settlement Closed
Date and Time
The date and time that the
batch was closed
meaning the date and
time that the last
transaction was added to
the current open batch.
Returned in MM/DD/YY
HH:MM:SS format.
This time can be
configured in the
Merchant Account.
Page 144
 2009 Skipjack Financial Services
7
Process Date
Skipjack Integration Guide
Batch Settlement Process
Date and Time
The date the batch was
processed meaning the
date and time when the
current batch was
submitted to the batch
queue for processing.
8
Started Date
Batch Settlement Started
Date and Time
Returned in MM/DD/YY
HH:MM:SS format.
Numeric and
colon (‘:’) and
back slash
(‘/’) and space
(‘ ‘)
17/20
11/22/06 11:07:02
Numeric and
colon (‘:’) and
back slash
(‘/’) and space
(‘ ‘)
17/20
11/22/06 11:07:02
Numeric and
colon (‘:’) and
back slash
(‘/’) and space
(‘ ‘)
17/20
11/22/06 11:07:02
Numeric
1/5
10000
Numeric with
decimal
8/15
90.23000
The starting date and time
for the batch specifically
when the first transaction
within the settlement
batch was actually settled.
9
Completed Date
Batch Settlement
Completed Date and Time
Returned in MM/DD/YY
HH:MM:SS format.
The completed date for
the batch is the date and
time when a batch
processing is finished and
a batch-completed
response is received from
the Processor.
10
Total Transactions Processed
Number of Transaction
Processed
The total number of
transactions that were
processed in the batch.
11
Net Amount Processed
Net Amount Processed
The dollar amount of the
net processed
transactions.
Page 145
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 1: Get Batch Settlement Status Method
<!--Fixed Values-->
<FORM NAME="samplegetbatchsettlementstatusmethod"
ACTION="https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_BATCHSETTLEGETSTATUSRE
QUEST" METHOD=POST>
<INPUT NAME="szSerialNumber "VALUE="000123456789">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!--Batch Data-->
<INPUT NAME=" szSkipjackBatchNumber"VALUE="999365548445">
<INPUT NAME=" szDateFrom" VALUE="04/06/2006">
<INPUT NAME=" szDateThru" VALUE="04/12/2006">
<INPUT NAME=" szShowDeletedClosed" VALUE="N">
Response Example 1 : Get Batch Settlement Status Method – Success
"000123456789","0","3","","","","","","","","",""
"000123456789","999365548445","000003803567","4","0","04/05/06 01:03:26","04/06/06
01:07:02","03/30/06 02:02:59","04/06/06 01:29:11","04/06/06 01:29:16","3","90.230000"
"000123456789","999365548445","000003829979","4","0","04/06/06 01:07:02","04/06/06
15:35:19","04/07/06 02:02:59","04/07/06 02:03:02","04/07/06 02:03:02","0","0.000000"
"000123456789","999365548445","000003832308","4","0","04/06/06 15:42:31","04/07/06
01:02:56","04/07/06 02:02:59","04/07/06 02:03:06","04/07/06 02:03:06","0","0.000000"
Request Example 2: Get Batch Settlement Status Method
<!--Fixed Values-->
<FORM NAME="samplegetbatchsettlementstatusmethod"
ACTION="https://developer.skipjackic.com/scripts/evolvcc.dll?SJAPI_BATCHSETTLEGETSTATUSRE
QUEST" METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialNumber" VALUE="">
<!--Batch Data-->
<INPUT NAME=" szSkipjackBatchNumber" VALUE="999365548445">
<INPUT NAME=" szDateFrom" VALUE="04/06/2006">
<INPUT NAME=" szDateThru" VALUE="04/12/2006">
<INPUT NAME=" szShowDeletedClosed" VALUE="">
Response Example 2: Get Batch Settlement Status Method – Failure
"000022127832","-2","","","","","","","","","",""
Parameter Missing: (szDeveloperSerialNumber)
Page 146
 2009 Skipjack Financial Services
Skipjack Integration Guide
Batch File Methods for Transaction Processing
Batch Uploads are used to process transactions in an off-line mode for all Core Transaction Methods
(Authorize/AuthorizeAPI, Get Transaction Status, and Change Transaction Status methods) and all
Recurring Payments methods.
When Used
Two types of Batch Uploads are supported: Authorization methods (batchType=0) and nonAuthorization (batchType=1) batch upload methods.
The Authorization Batch Upload method is used when submitting multiple transactions for
Authorization. Batches make more efficient use of network resources and are used most often for
processing large volumes of transactions.
The non-Authorization Batch Upload methods are used when performing uploads for the following
batch transaction methods:
•
•
•
Change Status Method
Get Status Method
Recurring Payments Methods (Add, Delete, Edit, Change)
Mechanisms Supported for Batch File Uploads
The Skipjack Transaction Network has two mechanisms for uploading batches:
1. Merchant Services Interface Batch Uploads
2. HTTPS POST methods of Batch Uploads
To learn more about Batch Upload using the Merchant Interface see the Skipjack Merchant Services
Guide.
This section will only describe in detail the HTTPS POST methods (non Merchant Services Interface)
for performing Batch Uploads.
How Batch Upload Files are Processed and Queued
Batch files submitted to the Skipjack Transaction Network are held within a holding area on a Batch
Transaction Server which is then “swept” on a predetermined interval (approximately every one to five
minutes) and the Batch Upload files are then moved from the sweep area to another area where they
are processed line-by-line.
Page 147
 2009 Skipjack Financial Services
Skipjack Integration Guide
Enabling Batch File Processing Privileges on a Merchant Account
To submit transactions to the Skipjack Transaction Network as batch files, each Skipjack Financial
Services Merchant Account must be granted batch processing privileges. If your Skipjack Merchant
Account is not presently configured to allow the submission of batch files, contact Skipjack Financial
Services.
NOTE: Have your Skipjack Merchant Account information ready when contacting Skipjack Financial Services.
You must provide your Login Serial Number, User Name, and HTML Serial Number in order to enable Batch
Upload privileges on your Skipjack Merchant Account.
Development and Usage Notes for Batch Uploading Methods
•
•
Limit of 10,000 transactions per batch file.
90 day batch file retention.
NOTE: By request your Skipjack Merchant Account can be modified by Skipjack Financial
Services to accommodate larger batch file processing capabilities.
Workflow for Processing Batch Upload Files
Batch files should be processed in a prescribed order to avoid complications. Please follow the
workflow below when uploading batch files to the Skipjack Transaction Network:
1. Build the batch file for uploading as described below.
2. Upload the batch file to the Skipjack batch transaction servers using the appropriate URL (for
Development or Production) via the Batch Upload Method.
3. Check that the batch file was processed using the Check Batch File Status Method.
4. Retrieve the batch file that contains the transaction results using Get Batch File Response
Method.
5. Interpret the batch file appropriately for your application’s requirements. This interpretation is
handled by your application and is outside the scope of this document.
If you have problems parsing the batch data in your application, contact Skipjack Financial
Services Development Technical Support for guidance.
Details for Submitting Transaction Requests for Batch Uploads
Development Server
https://developer.skipjackic.com/scripts/BatchUpload.dll?BatchUpload01
Production Server
https://batch.skipjackic.com/scripts/BatchUpload.dll?BatchUpload01
Development Server Host Name
developer.skipjackic.com
Production Server Host Name
batch.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST, ENCTYPE=”multipart/form-data”
NOTE 1: Requests submitted without a secure connection will be refused.
NOTE 2: Web submission via BatchUpload.dll requires batchType=0. (batchType=0 is default if not specified.)
Page 148
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Requests for Batch File Uploads
Variable
Description
Required
/
Optional
Variabl
e Type
Min / Max
Length
Example
SerialNumberAUTH
HTML Serial Number
Required
Numeric
12/12
00011122233
3
Required
Numeric
1/1
1
Required
File
Not
Applicabl
e
Skipjack-assigned unique HTML
serial number.
batchType
Batch Type
Defines the type of batch file
submitted, where:
0 = Authorization
1 = Others (Change Status, Get
Status, Recurring Payments
methods)
This is case sensitive.
type=file
name=BatchUploadDataAUT
H
Input for file type and file name.
<input type="FILE"
name="BatchUploadDataAUTH
" />
Page 149
 2009 Skipjack Financial Services
Skipjack Integration Guide
Formatting Requirements of Name-Value Pairs by Batch Method Type
The name-value pairs sent within a batch file for each non-Authorization methods are illustrated
below for two transactions. You will notice that these variables are the same variables and values
used for real-time transaction methods. Please note that the return order of the return variables may
be slightly different as compared to the associated real-time method.
Also, note that each line, listed in the formatting examples below, represents an individual transaction
record. Each record is formatted and denoted by a single Line Break/Carriage Return at the end of
each record.
For methods other than batch Authorize/AuthorizeAPI method you must include the
szApiMethod=<value> name-value pair at the start of each line in the batch request file.
Batch Method
szApiMethod
Authorize and AuthorizeAPI
Not required, the batchType=0 carries this instruction
Change Transaction Status Request Method
SJAPI_TransactionChangeStatusRequest
Get Transaction Status Method
SJAPI_TransactionStatusRequest
Add Recurring Payment Method
SJAPI_RecurringPaymentAdd
Edit Recurring Payment Method
SJAPI_RecurringPaymentEdit
Delete Recurring Payment Method
SJAPI_RecurringPaymentDelete
Batch File Status Request
SJAPI_BatchFileStatusRequest
Batch File Change Status request
SJAPI_BatchFileChangeStatusRequest
Batch File Get request File
SJAPI_BatchFileGetRequestFile
Batch File Get Response File
SJAPI_BatchFileGetResponseFile
Formatting Examples by Method Types
Formatting for Batch Authorization Method Request
The request variables used for Batch Authorization method are identical to those used for a real-time
Authorization request.
sjname=Person1&email=transaction@skipjack.com&streetaddress=none&city=none&state=OH&zipco
de=55555&accountnumber=4445999922225&month=12&year=03&transactionamount=150.01&shiptophon
e=5555555555&ordernumber=testbatch1&orderstring=itemnum1~itemdesc1~150.01~1~N~||
sjname=Person2&email=transaction@skipjack.com&streetaddress=none&city=none&state=OH&zipco
de=85284&accountnumber=4445999922225&month=12&year=03&transactionamount=1.64&shiptophone=
5555555555&ordernumber=testbatch2&orderstring=itemnum2~itemdesc2~1.64~1~N~||&shoesize=8me
ns
Page 150
 2009 Skipjack Financial Services
Skipjack Integration Guide
Formatting for Get Transaction Status Method Request
For information about the variables used in a Batch Get Transaction Status Method, see the
documented parameters in the “Transaction Variables for the Get Transaction Status Method”
section.
szApiMethod=SJAPI_TransactionStatusRequest&szDeveloperSerialNumber=123456789123&szOrderNu
mber&szDate=01/01/2006
szApiMethod=SJAPI_TransactionStatusRequest&szDeveloperSerialNumber=987654321AAA&szOrderNu
mber&szDate=12/25/2005
Formatting for Change Transaction Status Request
For information about the variables used in a Batch Change Transaction Status Method, see the
documented parameters in the “Transaction Requests for Change Transaction Status Method”
section.
szApiMethod=SJAPI_TransactionChangeStatusRequest&szDeveloperSerialNumber=123456789123&szO
rderNumber&szTransactionId=123456789.DNE&szDesiredStatus=CREDIT&szAmount=1500&szForceSett
lement=0
szApiMethod=SJAPI_TransactionChangeStatusRequest&szDeveloperSerialNumber=123456789123&szO
rderNumber&szTransactionId=123456789.DNE&szDesiredStatus=DELETE&szAmount=&szForceSettleme
nt=0
Formatting for Add Recurring Payments Request
For information about the variables used in an Add Recurring Payment Method, see the documented
parameters in “Transaction Requests for the Add Recurring Payments Method” section.
szApiMethod=SJAPI_RECURRINGPAYMENTADD&ItemNumber=21&szDeveloperSerialNumber=100337117877&
rtAddress1=2230ParkAve&rtAmount=1.01&rtState=OH&rtExpMonth=12&rtExpYear=2002&rtName=Test1
Name&rtEmail=transaction@skipjack.com&rtPostalCode=45206&rtTotalTransactions=1&rtCity=Cin
cinnati&rtExpMonth=12&rtOrderNumber=101&rtStartingDate=05/02/2002&rtPhone=8883688507&rtAc
countNumber=4445999922225&rtItemNumber=item1&rtItemDescription=SJsuppo&rtComment=testcomm
ent&rtFrequency=3
szApiMethod=SJAPI_RECURRINGPAYMENTADD&ItemNumber=22&szDeveloperSerialNumber=100337117877&
rtAddress1=2230ParkAve&rtAmount=1.02&rtState=OH&rtExpMonth=12&rtExpYear=2002&rtName=Test2
Name&rtEmail=transaction@skipjack.com&rtPostalCode=45206&rtTotalTransactions=1&rtCity=Cin
cinnati&rtExpMonth=12&rtOrderNumber=101&rtStartingDate=05/02/2002&rtPhone=8883688507&rtAc
countNumber=4445999922225&rtItemNumber=item2&rtItemDescription=SJsuppo&rtComment=testcomm
ent2&rtFrequency=3
Page 151
 2009 Skipjack Financial Services
Skipjack Integration Guide
Formatting for Edit Recurring Payments
For information about the variables used in an Edit Recurring Payment Method, see the documented
parameters in the “Submitting Requests for Edit Recurring Payments” section.
szApiMethod=SJAPI_RecurringPaymentEdit&ItemNumber=22&shoesize=Mens9&szDeveloperSerialNumb
er=100337117877&rtAddress1=2230ParkAve&rtAmount=1.02&rtState=OH&rtExpMonth=12&rtExpYear=2
002&rtName=Test2Name&rtEmail=transaction@skipjack.com&rtPostalCode=45206&rtTotalTransacti
ons=1&rtCity=Cincinnati&rtExpMonth=12&rtOrderNumber=101&rtStartingDate=05/02/2002&rtPhone
=8883688507&rtAccountNumber=4445999922225&rtItemNumber=item2&rtItemDescription=SJsuppo&rt
Comment=testcomment&rtFrequency=3
szApiMethod=SJAPI_RecurringPaymentEdit&ItemNumber=22&shoesize=Mens9&szDeveloperSerialNumb
er=100337117877&rtAddress1=2230
ParkAve&rtAmount=1.02&rtState=OH&rtExpMonth=12&rtExpYear=2002&rtName=Test2Name&rtEmail=tr
ansaction@skipjack.com&rtPostalCode=45206&rtTotalTransactions=1&rtCity=Cincinnati&rtExpMo
nth=12&rtOrderNumber=101&rtStartingDate=05/02/2002&rtPhone=8883688507&rtAccountNumber=444
5999922225&rtItemNumber=item2&rtItemDescription=SJsuppo&rtComment=testcomment&rtFrequency
=3
Formatting for Delete Recurring Payments
For information about the variables used in a Delete Recurring Payments Method, see the
documented parameters in the “Transaction Requests for the Add Recurring Payments Method”
section.
szApiMethod=SJAPI_RecurringPaymentDelete&szDeveloperSerialNumber=123456789123&szPaymentId
=987654321000szPaymentDate=01/01/2006
szApiMethod=SJAPI_RecurringPaymentDelete&szDeveloperSerialNumber=123456789123&szPaymentId
=852963741.DFE&szPaymentDate=0/01/2006
Transaction Responses for Batch Upload Methods
Successfully uploaded Batch Upload file will display only a simple HTML message File Successfully
Uploaded as illustrated below.
NOTE: For failed Batch Uploads, a simple error message or a blank window is displayed.
Page 152
 2009 Skipjack Financial Services
Skipjack Integration Guide
Check Batch File Status Method
(Batch File Status Request or Get Batch File Status)
Description
The Check Batch File Status is an HTTPS method that can be used to check the status of a batch file
prior to performing other actions to the transaction is contains.
When Used
The Check Batch File Status method is typically used to retrieve the BatchId and status for batches
that were previously uploaded.
See Also
•
To see usage examples of the Check Batch File Status method, see the “Scenario 4: Batch
Settlement Scenario” section.
Details for Submitting Transaction Requests for Check Batch File Status Method
Development Server
https://developer.skipjackic.com/scripts/evolvCC.dll?SJAPI_BATCHFILESTATUSREQUEST
Production Server
https://www.skipjackic.com/scripts/evolvCC.dll?SJAPI_BATCHFILESTATUSREQUEST
Development Server
Host Name
developer.skipjackic.com
Production Server
Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
Transaction Requests for Check Batch File Status Method
Variable
Description
Required /
Optional
Variable Type
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12 / 12
000111222333
Required
AlphaNumeric
12/12
123412341234
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumbe
r
Developer Serial Number
The Developer Serial Number
assigned to the Skipjack
Account.
Page 153
 2009 Skipjack Financial Services
szBatchId
Skipjack Integration Guide
Batch ID
Optional
Numeric
0/12
000004121122
Conditional
Numeric and
back slash (‘/’)
12/12
01/12/2009
Conditional
Numeric and
back slash (‘/’)
12/12
12/12/2009
Optional
Numeric
0/1
1
The unique identification
number assigned internally to
the batch when it is uploaded.
Batch uploading will be
modified to return this value.
szUploadDateFrom
Upload Date Range Start
The beginning of the date
range for which the batches
will be retrieved based on the
upload date.
Use MM/DD/YYYY format.
NOTE: This variable will be
ignored if szBatchId is
supplied.
SzUploadDateThru
Upload Date Range End
The ending of the date range
for which the batches will be
retrieved based on the upload
date.
Use MM/DD/YYYY format.
NOTE 1: This value will be
ignored if szBatchId is
supplied.
NOTE 2: If szUploadDateFrom
is provided but
SzUploadDateThru is left blank,
the current date is assumed.
szShowDeleted
Show Deleted Batches
szShowDeleted = 1
Deleted Batch files will be
returned, as long as they
match the criteria.
szShowDeleted = 0
Deleted Batch files will not be
returned.
NOTE: Supplying only the required parameters will list all submitted batch files for the Merchant.
Page 154
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Response for Check Batch File Status Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. The Status Record (Header Record) is the first record returned and contains information about
the subsequent records including: HTML Serial Number, Response Code, Number of
Records and Reserved fields. If an error is encountered, the second record returned is a text
message briefly describing that error.
2. The Response Record(s) is the second and subsequent record(s) returned containing the
return variables and parameter values as listed below.
Response Records (Data Records) for the Check Batch File Status Method
Return
Order
Variable
Description
Value
Min/Ma
x
Length
Example
1
HTML Serial Number
HTML Serial Number
Numeric
12/12
000099146970
AlphaNumeric
12/12
100143215432
Numeric
12/12
154160148967
Numeric
1/1
1
Skipjack-assigned unique
HTML serial number.
2
Developer Serial
Number
Developer Serial Number
The Developer Serial
Number assigned to the
Skipjack Account.
3
Batch ID
Batch ID
The unique identification
(ID) number generated
and assigned by the
Skipjack Transaction
Network to the batch
when it is uploaded.
Batch uploading will be
modified to return this
value.
4
File Type
The type of file uploaded.
1 = Authorization
2 = API (All methods
other than Authorization
Batch requests.)
Page 155
 2009 Skipjack Financial Services
5
Uploaded Date
Skipjack Integration Guide
The date and time when
the file was uploaded
successfully.
Returned in
MM/DD/YYYY format.
6
Started Date
The date and time when
the file began processing.
Returned in
MM/DD/YYYY format.
7
Completed Date
The date and time when
the processing of the file
completed.
Returned in
MM/DD/YYYY format.
8
Status
The current status of the
batch.
Numeric
and back
slash (‘/’)
and colon
(‘:’) and
space (‘ ‘)
19/19
01/12/2009 13:15:25
Numeric
and back
slash (‘/’)
and colon
(‘:’) and
space (‘ ‘)
19/19
12/12/2009 12:12:05
Numeric
and back
slash (‘/’)
and colon
(‘:’) and
space (‘ ‘)
19/19
12/12/2009 16:45:59
Numeric
1/1
4
1 = Uploaded
2 = Processing
3 = Complete
4 = Deleted
5 = Rejected
6 = Frozen
9
Status Message
A text message
describing the status of
the batch.
Alphanumeric
1/50
10
Total Failed
The total number of
transactions that failed
validation, or had a server
error.
Numeric
1/5
301
Numeric
1/5
1001
Numeric
1/5
200
Total Requests minus
Total Processed.
11
Total Processed
The total number of
requests successfully
Processed.
Total without validation or
server errors.
12
Total Requests
The total number of
requests in the batch file.
Page 156
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 1: Check Batch File Status Specifying Date Range
<!--Fixed Values-->
<FORM NAME="samplebatchauthorizationresponse"
ACTION="https://developer.skipjackic.com/scripts/EvolvCC.dll?SJAPI_BatchUpload.dll?"
METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="123456789000">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Batch File Data-->
<INPUT NAME="szUploadDateFrom" VALUE="04/06/06">
<INPUT NAME="szUploadDateThru" VALUE="04/07/06">
Response Example 1: Check Batch File Status
"123456789000","0","4","","","","","","","","",""
"123456789000","987654321000","154160148967","2","04/06/06 11:05:26","04/06/06
11:05:26","04/06/06 11:05:32","3","","0","105","105"
"123456789000","987654321000","162776020442","1","04/07/06 13:11:00","04/07/06
13:12:52","04/07/06 13:28:28","3","","17","4983","5000"
"123456789000","987654321000","823914005029","1","04/07/06 15:33:27","04/07/06
15:33:40","04/07/06 15:42:52","3","","37","2996","3033"
"123456789000","987654321000","992433961192","1","04/07/06 13:12:11","04/07/06
13:14:02","04/07/06 13:36:30","3","","12","2436","2448"
Page 157
 2009 Skipjack Financial Services
Skipjack Integration Guide
Modify Batch File Status Method
(Batch File Change Status Request)
Description
The Modify Batch File Status method is a method used to modify the status of a batch file to change it
from its current state to a different (desired) state.
When Used
The Modify Batch File Status method is used to change the state of a previously uploaded batch file
and when used is most commonly used to delete a batch file. Allowable states include: Freeze, Thaw,
and Delete.
Details for Submitting Transaction Requests for Modify Batch File Status Method
Development
Server
https://developer.skipjackic.com/scripts/evolvCC.dll?SJAPI_BATCHFILECHANGESTATUSREQUEST
Production
Server
https://www.skipjackic.com/scripts/evolvCC.dll?SJAPI_BATCHFILECHANGESTATUSREQUEST
Development
Server Host
Name
developer.skipjackic.com
Production
Server Host
Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
Transaction Requests for Modify Batch File Status Method
Request Variables for Modify Batch File Status Method
Variable
Description
Required /
Optional
Variable
Type
Min /
Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12/12
000111222333
Required
AlphaNumeric
12/12
123412341234
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumber
The Developer Serial Number
The Developer Serial Number
assigned to the Skipjack
Account.
Page 158
 2009 Skipjack Financial Services
szBatchId
Skipjack Integration Guide
Batch ID
Required
Numeric
12/12
12341232322132
Required
AlphaNumeric
4/6
FREEZE
The unique identification (ID)
number assigned internally to
the batch when it is uploaded.
Batch uploading will be
modified to return this value.
szDesiredStatus
Desired Status
The desired status for the
transaction.
FREEZE = Changes the batch
into a Frozen state.
THAW = Changes the match
file back to the original status
prior to being frozen.
DELETE = Changes the batch
File into a Deleted state.
NOTE the same rules apply as
outlined in “Batch File
Processing in Merchant
Services”. Status descriptions
are also provided in this
document.
Transaction Response for Modify Batch File Status Method
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. The Status Record (Header record) is the only record returned for successful
transactions for the Modify Batch File Status Method.
This Status Record contains information about: HTML Serial Number, Response Code,
Number of Records and Reserved fields.
NOTE: Successful responses to for Modify Batch File Status Method will ONLY return
this a single Status Record.
2. If an error is encountered for a Modify Batch File Status method request, the second record
returned is a text message briefly describing that error.
Page 159
 2009 Skipjack Financial Services
Skipjack Integration Guide
Request Example 1: Modify Batch File Status
<!--Fixed Values-->
<FORM NAME="samplemodifybatchfilestatus" ACTION="
https://developer.skipjackic.com/scripts/BatchUpload.dll?SJAPI_BATCHFILESTATUSREQUEST"
METHOD=POST>
<INPUT NAME="szSerialNumber" VALUE="123456789000">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Batch File Data-->
<INPUT NAME="szBatchId" VALUE="100200300400">
<INPUT NAME="szDesiredStatus" VALUE="FREEZE">
Response Example 1: Modify Batch File Status – Success
"123456789000","0","1","","","","","","","","",""
Request Example 2: Modify Batch File Status
<!--Fixed Values-->
<FORM NAME="samplemodifybatchfilestatus" ACTION="
https://developer.skipjackic.com/scripts/BatchUpload.dll? SJAPI_BATCHFILESTATUSREQUEST"
METHOD=POST>
<INPUT NAME="szSerialnumber" VALUE="000123456789">
<INPUT NAME="szDeveloperSerialNumber" VALUE="999888777666">
<!—Batch File Data-->
<INPUT NAME="szBatchId" VALUE="100200300400">
<INPUT NAME="szDesiredStatus" VALUE="DELETE">
Response Example 2 Modify Batch File Status – Error
"000123456789","-3","","","","","","","","","",""
Failed setting batch file status.
Page 160
 2009 Skipjack Financial Services
Skipjack Integration Guide
Get Batch File Response Method
Description
The Get Batch File Response method is an HTTPS method used to retrieve the batch file response
(results) for any previously uploaded batch file that has completed processing.
Details for Submitting Transaction Requests for Get Batch File Response Method
Development Server
https://developer.skipjackic.com/scripts/evolvCC.dll?SJAPI_BATCHFILEGETRESPONSEFILE
Production Server
https://www.skipjackic.com/scripts/evolvCC.dll?SJAPI_BATCHFILEGETRESPONSEFILE
Development Server
Host Name
developer.skipjackic.com
Production Server
Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
Method
POST
NOTE: Requests submitted without a secure connection will be refused.
Request Variables for Get Batch File Response Method
Variable
Description
Required /
Optional
Variable
Type
Min / Max
Length
Example
szSerialNumber
HTML Serial Number
Required
Numeric
12 / 12
000111222333
Required
AlphaNumeric
12/12
123412341234
Required
Numeric
12/12
3423523423432
Skipjack-assigned unique
HTML serial number.
szDeveloperSerialNumber
The Developer Serial
Number
The Developer Serial
Number assigned to the
Skipjack Account.
szBatchId
Batch ID
The unique identification
(ID) number assigned
internally to the batch when
it is uploaded.
Batch uploading will be
modified to return this
value.
Page 161
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Responses for Get Batch File Response – Batch Authorize
Transactions
Response records are returned as text strings in comma-delimited format with a carriage return/line
feed (CR/LF) record delimiters. The records are formatted with the following values:
1. The Status Record (Header Record) is the first record returned and contains information about
the subsequent records: HTML Serial Number, Response Code, Number of Records and
Reserved fields. If an error is encountered, the second record returned is a text message
briefly describing that error.
2. The Response Record(s) is (are) the second and subsequent record(s) returned containing the
return variables and parameter values as listed below.
Get Batch File Transaction Response for Batch Authorize
Transactions
Response Example 1: Get Batch File Response for Batch Authorization – No Errors
NOTE: Response Variables labels returned as listed in red text and included here for clarity.
"000111222333","0","3,"","","","","","","","",""
"000067","000111222333","15001","","N","Card authorized, exact address match with 5 digit
zip code.","100200300","1","","","1","10138083786558.009",""
“Authcode”, “szSerialNumber”, “Transaction Amount”, ”Authorization Decline Message”, AVS
Response Code”, “AVS Response Message”, “Order Number”, “Return Code”, CVV2 Response
Code”, “CVV2 Response Message”, “IsApproved”, “Transaction File Name”, “CAVV Response
Code”
"000069,"000111222333","164","","N","Card authorized, exact address match with 5 digit
zip code.","200300500","1","","","1","10138083786958.010""
"000078,"000111222333","175","","N","Card authorized, exact address match with 5 digit
zip code.","2255889999","1","","","1","10138083090958.016""
Example 2: Batch Authorization Response String – Error
"000092592328","-2","","","","","","","","","",""
Parameter Missing: (szBatchId)
Page 162
 2009 Skipjack Financial Services
Skipjack Integration Guide
Echo Utility
The Echo Utility permits any transaction request to be echoed back from the Skipjack Transaction
Network server showing the name-value pairs without executing the transaction request.
When Used
This utility is used for debugging and troubleshooting purposes.
Details for Submitting an Echo Utility Request
Development Server
https://developer.skipjackic.com/secure/echo.asp
Production Server
https://www.skipjackic.com/secure/echo.asp
Development Server Host Name
www.skipjack.com
Production Server Host Name
www.skipjack.com
Server Port
443
HTTP Type
1.0 Compliant
NOTE: Requests submitted without a secure connection will be refused.
NOTE: Posting to the above URLs will not process (Authorize) transactions. No methods will
be executed. Only an echo of the variables and name-value pairs submitted will be returned.
Transaction Requests for the Echo Utility
You can host this utility on your internal Web site by copying and pasting the following ASP code:
<html>
<head><title>Echo Variables</title></head>
<body>
<%@ "LANGUAGE" = VBScript %>
<%
If StrComp(Request("REQUEST_METHOD"),"POST",vbTextCompare) = 0 Then
Set FormValues = Request.Form
Else
Set FormValues = Request.QueryString
End If
For Each item in FormValues
Response.Write "<b>" & item & "</b>: " & FormValues(item) & "<br>"
Next
%>
</body>
</html>
Page 163
 2009 Skipjack Financial Services
Skipjack Integration Guide
Transaction Responses for the Echo Utility
You must submit an Authorization transaction request to the URL above with the name-value pairs
described in the “Authorize and AuthorizeAPI Methods” section.
Response Example: Authorize using the Debugging Utility
This utility will echo back the name-value pairs submitted as shown in the example below.
serialnumber=000123456789&orderstring=112~Test~1.99~3~N~||&ordernumber=1147099539956&sjna
me=JustinTime&email=jut@home.com&streetaddress=123mainst&city=Bev
Hills&state=CA&zipcode=90210&transactionamount=5.97&accountnumber=4003000123456781&month=
06&year=0006&shiptoname=Justin Time&shiptostreetaddress=123mainst&shiptocity=Bev
Hills&shiptostate=CA&shiptozipcode=90210&shiptophone=1234567890&comment=Test
comment&country=&shiptocountry=&approvalcode=&cvv2=123
Page 164
 2009 Skipjack Financial Services
Skipjack Integration Guide
Debugging Utility
The Debugging Utility allows the HTTPS POST of an Authorize transaction with receipt (echo) back
from the Skipjack Transaction Network server of the name-value pairs and Authorizing the
transaction.
When Used
The Debugging Utility is useful when you need to Authorize a transaction and receive an immediate
echo of the request variables sent in an Authorization request for troubleshooting and debugging
purposes.
Details for Submitting a Debugging Utility Request
Development Server
https://developer.skipjackic.com/scripts/evolvcc.dll?AUTHORIZEDEBUG
Production Server
https://www.skipjackic.com/scripts/evolvcc.dll?AUTHORIZEDEBUG
Development Server Host Name
developer.skipjackic.com
Production Server Host Name
www.skipjackic.com
Server Port
443
HTTP Type
1.0 Compliant
NOTE: Requests submitted without a secure connection will be refused.
Transaction Requests for Debugging Utility
You must submit an Authorization transaction request to the URL above with the name-value pairs
described in the “Authorize and AuthorizeAPI Methods” section.
Transaction Responses for Debugging Utility
Response Example: Authorize using the Debugging Utility
This utility will echo back the name-value pairs submitted as shown in the example below.
serialnumber=000111222333&ordernumber=910039948222&sjname=Transactive&shiptoname=Jack
Rinley&streetaddress=4 Test Drive&city=Houston&state=TX&zipcode=30329
&country=USA&accountnumber=4003000123456781&month=08&year=2009&cvv2=123&phone=3452223345
&shiptophone=8889990000&fax=9988885959&transactionamount=3.11&orderstring=002~Processing
Fee~0.11~1~N~||&comment=jrinley&email=jack
<!--AUTHCODE=000058--><!--szSerialNumber=000111222333--><!--szTransactionAmount=311-->
<!--szAuthorizationDeclinedMessage=--><!--szAVSResponseCode=Y-->
<!--szAVSResponseMessage=Card authorized, exact address match with 5 digit zip code.-->
<!--szOrderNumber=910039948222--><!--szAuthorizationResponseCode=000058-->
<!--szIsApproved=1--><!--szCVV2ResponseCode=M--><!--szCVV2ResponseMessage=Match-->
<!--szReturnCode=1--><!--szTransactionFileName=9802852159963.022-->
<!--szCAVVResponseCode=-->
Page 165
 2009 Skipjack Financial Services
Skipjack Integration Guide
Authorization Logic and Appropriate Failsafe Mechanisms
This section illustrates and describes the recommended logic and exception handling for transactions
processed by the Skipjack Transaction Network. Please implement this logic in your application in
order to avoid duplicate transactions from being created to ensure that Customers are not charged
more than once for a single transaction.
1. An Authorization request is submitted to the Skipjack Transaction Network for Approval
resulting in one of four status conditions:
a. Transaction Validation Failure
If a Transaction Validation Failure occurs for an Authorization request the transaction
will not be processed further. Examine the returned szReturnCode (Error Code) to
determine the reason for the Validation failure. For example determine if a credit card
number was incorrectly entered.
Once the likely cause of the Validation failure is determined resubmit the transaction for
Authorization, assuming the Customer (or Merchant) has not already done so.
Subsequent actions described for this example are used to determine whether or not
Page 166
 2009 Skipjack Financial Services
Skipjack Integration Guide
the Customer or Merchant has resubmitted the transaction resulting in duplicate orders
being created.
b. Transaction Timeout – Requires further action
A transaction timeout during an Authorization request indicates a failure at the network
level and/or a problem with network connectivity. This failure can be within any network
node within the Internet, or within the internal networks of the Processor, Issuing Bank,
or the Skipjack Transaction Network.
As a failsafe and/or excepting handling mechanism, perform a Get Transaction Status
using the OrderNumber on transactions which time-out to determine if the original
transaction Authorization request has been Processed. This checking mechanism will
prevent duplicate orders being generated in error.
c. Transaction Decline
For a Transaction Decline response, examine the returned transaction data to
determine the likely reason for the Decline. This will dictate the appropriate steps to
perform next.
If the Decline is a result of AVS or CVV checking/filtering, then resubmitting the
transaction data with appropriate changes in AVS or CVV settings can result in a
successful Approval being obtained.
If the Decline is a result of unavailable headroom (credit) on the credit card, submit a
new transaction with a new (different) credit card that has the available credit.
For Declined transactions, no further processing is required to determine if Duplicates
transactions exist.
d. Approved transactions require no further processing. These transactions can be
subsequently processed using any other transaction methods, as appropriate to the
situation.
2. Transaction Approval
a. When a Transaction Timeout occurs, your application’s logic should invoke a routine for
exception handling which includes performing a Get Transaction Status method
(specifying the OrderNumber) on the original transaction request.
b. If the Get Transaction Status method determines that the Transaction was Declined,
no duplicate order should exist for that original transaction unless the Customer or
Merchant has resubmitted the transaction. Resubmission of the transaction should only
be done after the reason for the Decline is determined and is corrected.
Page 167
 2009 Skipjack Financial Services
Skipjack Integration Guide
c. If the Get Transaction Status returns a No Records Found message, then the original
transaction did not Authorize and therefore will not impact Settlement. No further action
is required. You can resubmit the transaction with appropriate changes in the
transaction data, if appropriate or desired.
d. If the Get Transaction Status continues to Time-Out or you receive a Socket Closed
error message, continue to perform retries of the Get Transaction Status until a
successful response is returned, or else abort the processing.
If the transaction is aborted, you must later perform a Get Transaction Status method
on the transaction specifying Order Number to determine the original transaction status
and ensure that a duplicate transaction has not been inadvertently created.
If a duplicate transaction exists, then it must be appropriately Deleted or Credited to
ensure that the Customer is not billed more than once.
3. The appropriate next step for transactions reaching this stage depends upon how quickly after
the timeout condition you process the Get Transaction Status method above.
a. If the Get Transaction Status method is performed within a relatively short time after
the original Authorization request was submitted, the transaction will very likely still be in
the Approved state, since the Settlement Batch is unlikely to have been processed. In
this case, if the Get Transaction Status method determines that the transaction was
processed and is a duplicate, a Change Transaction Status – Delete can be
performed to Delete the duplicate transaction. This can only be done on a transaction
that has not yet Settled.
If the transaction was Approved and there is no duplicate to Delete, then any
appropriate subsequent transaction methods can be applied to the transaction.
b. If the Get Transaction Status method performed in step 3a determines that the original
transaction has already been Settled, and this is an inadvertent duplicate transaction,
then the Change Transaction Status – Credit method should be used to credit the
Customer’s card for the original amount of the transaction to eliminate the redundant
charge on the Customer’s credit card.
See Also
For more information about the methods described in this logic diagram see the following transaction
methods for more detail:
•
•
•
“Authorize and AuthorizeAPI Methods”
“Get Transaction Status Method”
“Change Transaction Status Method”
Page 168
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenarios
This section contains scenarios to illustrate typical real-life transaction tasks associated with the
methods described previously in this documentation. The scenarios in this section are based on
request and response messaging on the Skipjack Transaction Network, shown below.
Scenario 1: Split Authorization Scenario
In this scenario an order has been placed by the Customer but it must be separated into three
separate transactions (for example when goods must be back-ordered). The Customer's credit card is
authorized when the order is taken for the total transaction amount of $30.00. However, using the
Change Status: Authorize Additional method you will reauthorize the $30 as 3 transactions ($12.00,
$10.00 and $8.00) and then void the initial authorization for $30. Finally you use Change Status:
Settle on each transaction to submit the transactions for Settlement.
NOTE 1: That the Skipjack Merchant Account is set to Manual Settlement.
NOTE 2: Your Payment Processor may downgrade the transaction rate from a swiped to a nonswiped (keyed) transaction if the original transaction was swiped and you subsequently use the
Authorize Additional method. This is because the swipe card data is not stored in the Skipjack
Transaction Network and cannot be applied to AuthorizeAdditional transaction.
Page 169
 2009 Skipjack Financial Services
Skipjack Integration Guide
1. Use the Authorize Method to Submit the Original Transaction
When the order was received, the original transaction is submitted for Authorization with Ordernumber=000123.
The Authorization is Successful and returns the szTransactionFileName variable that in all subsequent
transactions this variable is called the TransactionId.
Authorize Request
Serial Number=000111222333, Sjname=John Doe, Email=jdoe@headoffice.com, City=Beverly Hills, State=CA,
Zipcode=90210, Shiptophone=1011011001, Accountnumber=41111111111111, Month=09, Year=2009,
Ordernumber=000123, Transactionamount=3000
Authorize Response
AUTHCODE=654321, szSerialNumber=000111222333, szTransactionAmount=3000,
szAuthorizationResponseCode=T12345, szReturnCode=1, szIsApproved=1, szAuthorizationDeclinedMessage=,
szAVSResponseCode=N, szAVSResponseMessage=,No Match, szOrderNumber=000123, szCVV2ResponseCode=,
szCVV2ResponseMessage=, szTransactionFileName=987654321.005, szCAVVResponseCode=
2. Get Transaction Status Method - Specifying Order Number
Perform a Get Transaction Status method to determine the TransactionId and Status of the original
Authorization for OrderNumber 000123 prior to shipping the order. This returns the Transaction ID which can
be used in step 3, below.
NOTE: The Transaction Status Code 12 denotes an Authorized Pending Settlement status. If performing a Get
Status within 30 seconds of the original authorization, you may see a 14 status, denoting Pending
Authorization status.
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 1
HTML SerialNumber=000111222333, Transaction Amount=3000, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:15:45,
TransactionId=987654321.005, Approval Code=123456, Batch Number=999888777666
Page 170
 2009 Skipjack Financial Services
Skipjack Integration Guide
3. Change Transaction Status Method 1: Authorize Additional Specifying Transaction ID
A Change Transaction Status:AUTHORIZEADDITIONAL specifying the Order Number is done for the first
portion of the order. In this step we can use either the Order Number or Transaction ID. However, in all
subsequent Change Transaction Status requests you specify the TransactionId of the original authorization.
Change Transaction Status Request 1
szSerialNumber=000111222333, szOrderNumber=000123, szTransactionId=,
szDesiredStatus=AUTHORIZEADDITIONAL, szAmount=1200, szForceSettlement=0
Change Transaction Status Response 1
SerialNumber=000111222333, szTransactionAmount=1200, Desired Status=AUTHORIZEADDITIONAL,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=222333444.007
4. Get Transaction Status Method
Perform a Get Transaction Status method specifying the OrderNumber to obtain the Transaction ID for the
original transaction (Authorization).
Get Transaction Status Request 2
szSerial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 2
Serial Number=000111222333, Transaction Amount=3000, Transaction Status Code=80,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:15:45,
szTransactionId=987654321.005, Approval Code=123456, Batch Number=999888777666
HTMLSerialNumber=000111222333, Transaction Amount=1200, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:16:45,
TransactionId=555666777.007, Approval Code=123456, Batch Number=999888777666
5. Change Transaction Status Method: Change Status 2
Perform a Change Transaction Status: Authorize Additional for the $10.00.
NOTE: You can use the szNewOrderNumber in this request.
Change Transaction Status Request 2
szSerialNumber=000111222333, szOrderNumber=, TransactionId=987654321.005,
szDesiredStatus=AUTHORIZEADDITIONAL, szAmount=1000, szForceSettlement=0
Change Transaction Status Response 2
SerialNumber=000111222333, szTransactionAmount=1000, Desired Status=AUTHORIZEADDITIONAL,
Status Response=Successful, Status Response Message=, szOrderNumber=000789, TransactionId=999888777.022
Page 171
 2009 Skipjack Financial Services
Skipjack Integration Guide
6. Get Transaction Status Method
The final item for the Order Number 000123 is located and the final shipment is ready. Perform a Get Transaction
Status method specifying the Transaction ID that is required for the Change Transaction Status:Authorize
Additional.
Get Transaction Status Request 3
szSerial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 3
Serial Number=000111222333, Transaction Amount=3000, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:15:45,
TransactionId=987654321.005, Approval Code=123456, Batch Number=999888777666
HTMLSerialNumber=000111222333, Transaction Amount=1200, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:16:45,
TransactionId=123456789.005, Approval Code=123456, Batch Number=999888777666
HTMLSerialNumber=000111222333, Transaction Amount=1000, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/31/06 09:05:05,
TransactionId=123456009.022, Approval Code=123456, Batch Number=999888777666
7. Change Transaction Status Method 3
The order is now ready for shipment. Perform a Change Transaction Status for the final amount (partial amount
of $8.00). You must use the Transaction ID associated with the Transaction Status Code=80 from step 6, above,
otherwise you will receive an error response.
Change Transaction Status Request 3
szSerialNumber=000111222333,szOrderNumber=000123, TransactionId=987654321.005,
szDesiredStatus=AUTHORIZEADDITIONAL, szAmount=800, szForceSettlement=0
Change Transaction Status Response 3
SerialNumber=000111222333, szTransactionAmount=800, Desired Status=AUTHORIZEADDITIONAL,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=12346007.014
8. Delete Original Authorization
You should now Delete (Void) the original Authorization for the $30 to tidy up any unneeded transactions in the
Skipjack Transaction Network.
Change Transaction Status Request 4
szSerialNumber=000111222333,szOrderNumber=000123, TransactionId=987654321.005,
szDesiredStatus=DELETE, szAmount=3000, szForceSettlement=0
Change Transaction Status Response 3
SerialNumber=000111222333, szTransactionAmount=800, Desired Status=DELETE,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=12346007.014
Page 172
 2009 Skipjack Financial Services
Skipjack Integration Guide
9. Settle Each Original Authorization
Finally, use the Change Status: SETTLE method to settle each transaction amount. In this example we show the
Change Status: Settle for one of the three transactions, for simplicity.
Change Transaction Status Request 5
szSerialNumber=000111222333,szOrderNumber=000123, TransactionId=987654321.005,
szDesiredStatus=SETTLE, szAmount=1200, szForceSettlement=0
Change Transaction Status Response 5
SerialNumber=000111222333, szTransactionAmount=1200, Desired Status=SETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=12346007.011
Page 173
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 2: Refunds and Voids Scenario
In this scenario a Customer is purchases goods to be delivered totaling $100.00. Shortly after the
original order is placed and the transaction is Authorized, the Customer calls back asking for
additional items for $50.00 above the original transaction amount. When the order arrives, the
Customer inspects the order and finds a missing item and calls the Merchant for a Credit (Refund) for
the undelivered item, valued at $30.00.
1. Use the Authorize Method to Submit the Original Transaction
The original transaction request is submitted for an Authorization for Ordernumber=000123 for $100.00 and is
promised for shipment in five days. The Authorization is Successful and returns the szTransactionFileName
variable. Note that in all subsequent transactions this variable is called the TransactionID.
Authorize Request
Serial Number=000111222333, Sjname=Jane Doe, Email=jane@work.ca, City=Toronto, State=ON, Zipcode=123456,
Shiptophone=9022223333, Accountnumber=5222333444666, Month=06, Year=2010, Ordernumber=000123,
Transactionamount=100.00
Authorize Response
AUTHCODE=12345D, szSerialNumber=000111222333, szTransactionAmount=100.00,
szAuthorizationResponseCode=T12345, szReturnCode=1, szIsApproved=1, szAuthorizationDeclinedMessage=,
szAVSResponseCode=, szAVSResponseMessage=, szOrderNumber=000123, szCVV2ResponseCode=,
szCVV2ResponseMessage=, szTransactionFileName=987654321.005, szCAVVResponseCode=
2. Authorize Additional Amount - Get Transaction Status to Determine Order Details
A few days later the Customer calls the Merchant, before the order is shipped, stating that they want another
item included in their original order. Perform a Get Transaction Status specifying Order Number to display the
transaction details, shown below .
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=222333444555, szOrderNumber=000123, szDate=
Get Transaction Status Response 1
SerialNumber=100200300400, Transaction Amount=150.00, Transaction Status Code=30
Transaction Status Message=, Order Number=000123, Transaction Date=01/15/06 12:00:00,
TransactionId=987654321.005, Approval Code=123456, Batch Number=900000000
3. Authorize Additional Amount for the Additional Items
Note that the original transaction has already Settled, as indicated by the Transaction Status Code of 30 in step
2. A new Order Number (optional variable) is specified as part of the Change Status:Authorize Additional
request to help identify the new order details.
Change Transaction Status - AUTHORIZE ADDITIONAL
szSerialNumber=000111222333, szOrderNumber=000123, szNewOrderNumber=000456,
szTransactionId=987654321.005, szDesiredStatus=AUTHORIZEADDITIONAL, szAmount=50.00,
szForceSettlement=0
Change Transaction Status - AUTHORIZE ADDITIONAL
SerialNumber=000111222333, szTransactionAmount=5000, Desired Status=SPLITSETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000456, TransactionId=123456790.007
Page 174
 2009 Skipjack Financial Services
Skipjack Integration Guide
4. Credit (Refund) Requested - Get Transaction Status to Determine Order Details
After the order is delivered to the Customer, the Merchant receives a call that one of the products in the order is
missing. Perform a Get Transaction Status specifying the Order Number to display the transaction details of the
newly updated order, Order Number 000456.
Get Transaction Status Request 2
Serial Number=000111222333, szDeveloperSerialNumber=222333444555, szOrderNumber=000456, szDate=
Get Transaction Status Response 2
SerialNumber=100200300400, Transaction Amount=150.00, Transaction Status Code=30
Transaction Status Message=, Order Number=000456, Transaction Date=01/17/06 18:10:15,
TransactionId=6665554441.014, Approval Code=123456, Batch Number=900000825
5. Change Transaction Status Method - Credit value of Undelivered Goods
Use the Change Transaction Status: CREDIT to refund to the cardholder the value of the missing item.
Note that in order to perform a CREDIT, the Status of the transaction must be Settled (Transaction Status
Code=30 denotes Settled, Idle in the Get Transaction Status from Step 4).
Change Transaction Status Request - CREDIT
szSerialNumber=000111222333, szOrderNumber=000456, szNewOrderNumber=000789,
szTransactionId=987654321.005, szDesiredStatus=CREDIT, szAmount=3000, szForceSettlement=0
Change Transaction Status Response - CREDIT
SerialNumber=000111222333, szTransactionAmount=3000, Desired Status=CREDIT,
Status Response=Successful, Status Response Message=, szOrderNumber=000789, TransactionId=987654321.015
Page 175
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 3: Recurring Payments Scenario
In this scenario an original transaction is Authorized for $39.95 for a service. Later the Customer
decides to change to a scheduled payment (Recurring Payment) with a monthly recurring charge for
the original amount for a one year subscription to the service. Two months (2 Recurring Payments)
into this payment schedule the Customer decides to upgrade the service to a more expensive version
of the service. This requires a change of the Recurring Payments amount to $59.95 for the remaining
(scheduled) Recurring Payments. Finally, the Customer decides to cancel the subscription and there
are two payments outstanding, requiring a Deletion of the final 2 payments.
1. Use the Authorize Method to Submit the Original Transaction
The (original) transaction is submitted for Authorization with Ordernumber=000123. The Authorization is
Successful and returns the szTransactionFileName variable which in all subsequent transactions this variable
is called the TransactionID.
Authorize Request
Serial Number=100200300400, Sjname=John Doe, Email=john@home.com, City=Toledo, State=OH, Zipcode=12345,
Shiptophone=1011011001, Accountnumber=41111111111111, Month=09, Year=2009, Ordernumber=000123,
Transactionamount=39.95
Authorize Response
AUTHCODE=987654, szSerialNumber=100200300400, szTransactionAmount=39.95,
szAuthorizationResponseCode=T12345, szReturnCode=1, szIsApproved=1, szAuthorizationDeclinedMessage=,
szAVSResponseCode=, szAVSResponseMessage=, szOrderNumber=000123, szCVV2ResponseCode=,
szCVV2ResponseMessage=, szTransactionFileName=987654321.005, szCAVVResponseCode=
2. Add Recurring Payment Method
The following month the Customer calls and requests scheduled payments be established for a full year's
worth of Basic Service. This requires the use of Add Recurring Payment method (monthly) for the transaction
amount previously Authorized.
Add Recurring Payment Request
szSerialNumber=100200300400, szDeveloperSerialNumber=123456789000, rtOrdernNumber=999123,
rtName=John Doe, rtCity=Toledo rtState=OH, rtPostalCode=123456, rtAccountNumber=4000100020003000,
rtExpMonth=08, rtExpYear=2009, rtItemNumber=5005, rtAmount=39.95, rtStartingDate=02/15/2006,
rtFrequency=3, rtTotalTransactions=11
Add Recurring Payment Response
SerialNumber=100200300400, Response Code=0,Number of Records=1,Recurring Payment ID=R01234567890.005
Page 176
 2009 Skipjack Financial Services
Skipjack Integration Guide
3. Get Recurring Payment Method
Two months later, because the Customer has requested an upgrade to a more expensive service, the Recurring
Payment amount must be changed to 59.95 for all subsequent scheduled payments. This requires 2 steps
(Steps 4 and 5 below. First perform a Get Recurring Payment method to display the transaction details for the
Recurring Payment.
Get Recurring Payment Information Request
szSerial Number=000111222333, szDeveloperSerialNumber=123456789000, szPaymentId=R01234567890.000,
szTransactionDate=
Get Recurring Payment Information Response
Serial Number=000111222333, Developer Serial Number=123456789000,
Recurring Payment ID=R01234567890.005, Customer Name=John Doe, Recurring Amount=39.9500,
Payment Frequency=3, Transaction Date=01/01/2006 13:15:45, First Payment=02/15/2006, Total Transactions=11,
Remaining Transactions=9, Customer Email Address=john@home.com, Customer Address1=, Customer Address2=,
Customer Address 3=, Customer Address4=, Customer Billing City=, Customer Billing State=,
Customer Postal Code=, Customer Country=, Customer Phone=, Customer Fax Number=, Customer Credit Card
Number=03000, Customer Billing Expiration Month=, Customer Billing Year=, Item Number=Basic Service, Comment=,
Order Number=000123
4. Edit Recurring Payment Method
Using the Recurring Payment ID and the Payment Date obtained in step 4, above, you can now change the
Recurring Payment Amount for the remaining (8) payments for the Premium Service amount of $59.95.
Edit Recurring Payment Request
szSerialNumber=000111222333, szDeveloperSerialNumber=12345689000, szPaymentId=R01234567890.005,
szTransactionDate=, rtName=John Doe, rtEmail=john@home.com, rtAddress1=, rtAddress2=, rtAddress3=,
rtAddress4=, rtCity=Toledo, rtState=OH,rtPostalCode=12345, rtCountry=, rtPhone=8881112222, rtFax=,
rtAccountNumber=, rtExpMonth=09, rtExpYear=2009, rtItemNumber=12345, rtItemDescription=Premium Service,
rtComment=, rtOrderNumber=999456, rtAmount=59.95
Edit Recurring Payment Response
SerialNumber=000111222333, Response Code=0
5. Get Recurring Payment Method
Several months later the Customer requests that the service be cancelled. Therefore, you must Delete the
Recurring Payments that are remaining to avoid charging the Customer's card. First, you must perform a Get
Recurring Payment method to retrieve the details of the Order Number 000123.
Get Recurring Payment Information Request 2
szSerial Number=000111222333, szDeveloperSerialNumber=123456789000, szPaymentId=, szTransactionDate=
Get Recurring Payment Information Response 2
Serial Number=000111222333, Developer Serial Number=123456789000,
Recurring Payment ID=R01234567890.005, Customer Name=John Doe, Recurring Amount=59.9500, Payment
Frequency=3, Transaction Date=01/15/06 13:15:45, First Payment=02/15/2006, Total Transactions=11,
Remaining Transactions=2, Customer E-mail Address=john@home.com, Customer Address1=, Customer Address2=,
Customer Address 3=,Customer Address4=, Customer Billing City=, Customer Billing State=,
Customer Postal Code=, Customer Country=, Customer Phone=, Customer Fax Number=,
Customer Credit Card Number=03000, Customer Billing Expiration Month=, Customer Billing Year=,
Item Number=Premium Service, Comment=, Order Number=000456
Page 177
 2009 Skipjack Financial Services
Skipjack Integration Guide
6. Delete Recurring Payment Method
You can then specify either the szPaymentID or the szTransactionID in your Delete Recurring Payments request
depending upon the desired deletion results. Specifying only the szPaymentID will delete all remaining
scheduled Recurring Payments, which is desired here.
Delete Recurring Payment Request
szSerial Number=000111222333, szDeveloperSerialNumber=123456789000, szPaymentId=R01234567890.005,
szTransactionDate=
Delete Recurring Payment Response
Serial Number=000111222333, Response Code=0
Page 178
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 4: Batch Settlement Scenario
In this scenario a Merchant has a Skipjack Merchant Account configured for Manual Settlement. The
steps below illustrate the steps required to obtain a Batch Number for the current open Batch and
subsequently close the open Settlement Batch.
1. Use the Get Batch Settlement Status to Obtain a Batch Number
Use the Get Batch Settlement Status specifying the Dates only (szDateFrom and szDateThru) to obtain the
Batch Number for a Merchant Account. Note that the Header Record is included in this example.
Get Batch Settlement Status
szSerialNumber=000111222333, szDeveloperSerialNumber=222333444555, szSkipjackBatchNumber=,
szDateFrom=02/18/2006, szDateThru=02/18/2006, szShowDeletedClosed=N
Get Batch Settlement Status
"000111222333","0","1" (Status Record)
SerialNumber=000111222333, Batch Number=100250125, Batch Status=2, Status=0, Opened Date=01/01/1970
00:00:00, Closed Date=01/01/1970 00:00:00, Processed Date=01/01/1970 00:00:00, Completed Date=01/01/1970
00:00:00, Total Transactions Processed=0, Net Amount Processed=0.000000
2. Use the Close Current Batch Method to Close a Manual Settlement Batch
Use the Close Current Batch method to mark transactions to close. The Status Code=0 indicates the Success of
the Batch Settlement.
Close Current Open Batch
Serial Number=000111222333, szDeveloperSerialNumber=222333444555
Close Current Open Batch
SerialNumber=000111222333, Status Code=0 (Status Record)
3. Use the Get Batch Settlement Status to Determine the Settlement Status of the Batch
Again, use this method to determine the Batch Settlement information for a specified date. Note the Header
Record (Status Record) is included in the Get Batch Settlement Status in this example.
Get Batch Settlement Status
szSerialNumber=000111222333, szDeveloperSerialNumber=222333444555, szSkipjackBatchNumber=100250125,
szDateFrom=02/18/2006, szDateThru=02/18/2006, szShowDeletedClosed=Y
Get Batch Settlement Status
"000111222333","0","1" (Status Record)
SerialNumber=000111222333, Batch Number=100250125, Batch Status=2, Status=0, Opened Date=01/17/2006
12:00:00, Closed Date=01/18/2006 11:00:59, Processed Date=01/18/06 12:03:06, Completed Date=01/18/2006
12:03:48, Total Transactions Processed=102, Net Amount Processed=11002.180000
Page 179
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 5: Batch File Upload Scenario
In this scenario you are required to perform a Batch Upload of an Authorization File for offline
processing. You must be sure to follow all the steps illustrated below to successfully upload, process,
and download the processed Batch File.
1. Assemble and Format the Batch Upload File
A Batch Authorization Upload is submitted to the Skipjack Transaction Network.
Authorize Request
sjname=Person1&email=transaction@skipjack.com&streetaddress=none&city=none&state=OH&zipcode=55555&acco
untnumber=4445999922225&month=12&year=03&transactionamount=150.01&shiptophone=5555555555&ordernumb
er=testbatch1&orderstring=itemnum1~itemdesc1~1~150.01~N~||
sjname=Person2&email=transaction@skipjack.com&streetaddress=none&city=none&state=OH&zipcode=85284&acco
untnumber=4445999922225&month=12&year=03&transactionamount=1.64&shiptophone=5555555555&ordernumber
=testbatch2&orderstring=itemnum2~itemdesc2~1~1.64~N~||&shoesize=8mens
sjname=Person3&email=transaction@skipjack.com&streetaddress=8320&city=none&state=OH&zipcode=85284&acco
untnumber=4445999922225&month=12&year=03&transactionamount=1.75&shiptophone=5555555555&ordernumber
=testbatch3&orderstring=itemnum2~itemdesc2~1~1.75~N~||&favoritecolor=blue
2. Upload the Batch Upload File
Upload the Batch File to the correct URL. A simple response is returned for a successful upload and illustrated
below.
3. Confirm Batch Upload File was Uploaded Successfully using Check Batch File method.
Perform a Check Batch File Response specifying the szUploadDateFrom and szUploadDateThru dates to obtain
the Batch ID required for Step 4, below.
Check Batch File Method
szSerialNumber=000111222333, szOrderNumber=000123, szBatchId=, szUploadDateFrom=06/12/2006,
szUploadDateThru=06/12/2006, szShowDeleted=1
Check Batch File Response
SerialNumber=000111222333, Developer Serial Number=987654321000, Batch ID=123456789012, File Type=1,
Uploaded Date=06/12/2006 12:15:45, Started Date=06/12/2006 12:18:01, Completed Date=06/12/2006 12:21:01,
Status, Status Message=, Total Failed=0, Total Processed=3, Total Requests=3
Page 180
 2009 Skipjack Financial Services
Skipjack Integration Guide
4. Download the Batch Upload File Response using Get Batch File Response method
Perform a Get Batch File Response specifying the Batch ID obtained in step 3 to determine the status of the
Batch File.
Get Batch File Response Method
szSerialNumber=000111222333, szOrderNumber=000123, szBatchId=123456789012
Get Batch File Response Method
"000111222333","0","3,"","","","","","","","",""
"000067", "000111222333", "15001", "", "N", "Card authorized, exact address match with 5 digit zip code.", "1", "1", "",
"", "1", "10138083786558.009","", "Authcode", "szSerialNumber",
"000069, "000111222333", "164", "", "N", "Card authorized, exact address match with 5 digit zip code.", "1", "1", "", "",
"1", "10138083786958.010""
"000078,"000111222333","175","","N","Card authorized, exact address match with 5 digit zip code.", "1", "1", "", "", "1",
"10138083090958.016""
5. Parse/Process the File according to your needs.
Once the Batch Files has been downloaded, you can process/parse the results as appropriate to your
application's needs.
Page 181
 2009 Skipjack Financial Services
Skipjack Integration Guide
Re-Authorization Scenarios
The scenarios in this section illustrate the options available to handle when a Merchant wants to
change the transaction amount of a previously authorized transaction after the original transaction
has been Approved.
There are 3 methods that may be applied to address this circumstance. Each scenario described in
this section provides a context and the advantages and disadvantages associated with using
approach.
Usage Notes Regarding the Following Scenarios:
•
It is a good practice to inform the Customer of the requirement to change the transaction
amount and state a reason for doing so. You should also notify the Customer of the new
amount when that amount is determined, for example by sending an e-mail notification of the
adjusted transaction amount when it is determined. Doing this will minimize the likelihood of a
chargeback by customers who might dispute or not recognize a different transaction amount
on their card statement.
•
To Settle an amount above the original amount the Skipjack Account configuration setting
Allow settlement above original amount option must be enabled on your Skipjack Account.
Contact Skipjack Financial Services Support to enable this setting on your Skipjack Account, if
this function is required.
•
Depending on the method chosen there may be an impact (a higher fee and additional charges
levied) by your Bank for settling an amount different than the original transaction amount. You
should contact your bank prior to using these options to ensure you receive the most favorable
rate and lowest fees.
•
See the section “Change Transaction Status Method” for more details about proper usage of
the Change Status methods options described in this section.
•
For these scenarios to apply, it is assumed the Skipjack Merchant Account Settlement
configuration option is set to Manual/None.
Page 182
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 6A – Authorize Original Amount, Settle Different Amount
In this scenario, the Merchant will Authorize one amount and use the ChangeStatus:SETTLE
method to Settle for a different amount.
Advantages
•
Simplest approach, this method should be used whenever possible. However, please check
with the Acquiring Bank to see what, if any, limitations exist regarding its usage.
Disadvantages
•
If the difference between the two amounts submitted exceeds a threshold value (typically 15%)
then the Bank may downgrade the rate applied to the transaction. Merchants are encouraged
to speak with their Bank and determine the costs associated with (if any) using this approach.
•
A higher risk of chargeback requests by Customers if the Customer disputes the higher Settled
amount if they do not recognize this charge on their bill.
In this scenario, an authorization is obtained for a transaction amount of $30.00 but the Merchant
wishes to Settle for a higher amount, $45.00, to cover shipping costs determined on the final weight
of the product immediately before shipping.
1. Use the Authorize Method to Submit the Original Transaction
The original transaction is submitted for Authorization with Ordernumber=000123. The Authorization is
Successful and returns the szTransactionFileName variable that in all subsequent transactions this variable is
called the TransactionID.
Authorize Request
Serial Number=000111222333, Sjname=John Doe, Email=jdoe@headoffice.com, City=BeverlyHills, State=CA,
Zipcode=90210, Shiptophone=1011011001, Accountnumber=41111111111111, Month=09, Year=2009,
Ordernumber=000123, Transactionamount=3000,
Authorize Response
AUTHCODE=654321, szSerialNumber=000111222333, szTransactionAmount=3000,
szAuthorizationResponseCode=T12345, szReturnCode=1, szIsApproved=1, szAuthorizationDeclinedMessage=,
szAVSResponseCode=, szAVSResponseMessage=, szOrderNumber=000123, szCVV2ResponseCode=,
szCVV2ResponseMessage=, szTransactionFileName=987654321.005, szCAVVResponseCode=
Page 183
 2009 Skipjack Financial Services
Skipjack Integration Guide
2. Get Transaction Status Method - Specifying Order Number
Later, just prior to shipping, the additional charge is determined and warehouse personnel perform a Get
Transaction Status method to determine the TransactionID and Status of the original Authorization for
OrderNumber 000123 prior to shipping the order. This returns the Transaction ID which can be used in step 3,
below.
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 1
HTML SerialNumber=000111222333, Transaction Amount=3000, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:15:45,
TransactionId=987654321.005, Approval Code=123456, Batch Number=999888777666
3. Change Transaction Status Method:SETTLE specifying new (different) szAmount
A Change Transaction Status:SETTLE is performed specifying the Order Number. The Settled amount is for the
full amount of the original transaction ($30.00) plus the new Shipping Charges ($15.00) for a total amount of
$45.00. In this step we can use either the Order Number or Transaction ID.
Change Transaction Status Request 1
szSerialNumber=000111222333, szOrderNumber=000123, szTransactionId=, szDesiredStatus=SETTLE,
szAmount=4500, szForceSettlement=0
Change Transaction Status Response 1
SerialNumber=000111222333, szTransactionAmount=4500, Desired Status=SETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=987654321.005
NOTE: To Settle an amount above the original amount the Skipjack Account configuration
setting Allow settlement above original amount option must be enabled on your Skipjack
Account. Contact Skipjack Financial Services Support to enable this setting on your Skipjack
Account, if this function is required.
Page 184
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 6B – Authorize Original Amount, Change Status Authorize
Additional
In this scenario, the Merchant will Authorize an original transaction ($30.00) and subsequently use
the ChangeStatus:AUTHORIZEADDITIONAL to authorize an additional amount for the shipping
charges ($15.00).
Advantages
This method creates a second transaction without affecting the first transaction, so in the event of
a Decline on the AUTHORIZEADDITIONAL transaction, the original amount still can be Settled.
NOTE: Ensure that your Customer is aware of the two charges and that they are identified
on the Customer statement to reduce the risk of chargebacks.
Disadvantages
•
The amount specified (szTransactionAmount) in the AUTHORIZEADDITIONAL will affect the
headroom on the credit card in the event of a Decline (or multiple Declines). This may mean
that you will be unable to obtain an Approval for the transaction until the credit limit on the card
has been reset. This may take 5 business days or longer, depending on the Issuing Bank.
In this scenario, an authorization is obtained for a transaction amount of $30.00, however the
Merchant wishes to use the ChangeStatus:AUTHORIZEADDITIONAL for an amount of $15.00 (to
make up the total amount, $45.00) to cover final shipping costs determined by the final weight of the
product. Finally, both transactions (original Authorization and AUTHORIZEADDITIONAL transactions)
are Settled manually and the Settlement Batch closed and submitted for processing.
1. Use the Authorize Method to Submit the Original Transaction
The original transaction is submitted for Authorization with Ordernumber=000123. The Authorization is
Successful and returns the szTransactionFileName variable that in all subsequent transactions this variable is
called the TransactionID.
Authorize Request
Serial Number=000111222333, Sjname=John Doe, Email=jdoe@headoffice.com, City=BeverlyHills, State=CA,
Zipcode=90210, Shiptophone=1011011001, Accountnumber=41111111111111, Month=09, Year=2009,
Ordernumber=000123, Transactionamount=3000,
Authorize Response
AUTHCODE=654321, szSerialNumber=000111222333, szTransactionAmount=3000,
szAuthorizationResponseCode=T12345, szReturnCode=1, szIsApproved=1, szAuthorizationDeclinedMessage=,
szAVSResponseCode=, szAVSResponseMessage=, szOrderNumber=000123, szCVV2ResponseCode=,
szCVV2ResponseMessage=, szTransactionFileName=987654321.005, szCAVVResponseCode=
Page 185
 2009 Skipjack Financial Services
Skipjack Integration Guide
2. Get Transaction Status Method - Specifying Order Number
Later, just prior to shipping, the additional charge is determined and warehouse personnel perform a Get
Transaction Status method to determine the TransactionID and Status of the original Authorization for
OrderNumber 000123 prior to shipping the order. This returns the Transaction ID which can be used in step 3,
below.
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 1
HTML SerialNumber=000111222333, Transaction Amount=3000, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:15:45,
TransactionId=987654321.005, Approval Code=123456, Batch Number=999888777666
3. Change Transaction Status Method:AUTHORIZEADDITIONAL specifying new (different)
szAmount
A Change Transaction Status:AUTHORIZEADDITIONAL is performed specifying the a New Order Number. The
amount submitted is new Shipping Charges ($15.00) only. In this step we send both New Order Number and
Transaction ID.
Change Transaction Status Request 1
szSerialNumber=000111222333, szNewOrderNumber=000124, szTransactionId=987654321.005
szDesiredStatus=AUTHORIZEADDITIONAL, szAmount=1500, szForceSettlement=0
Change Transaction Status Response 1
SerialNumber=000111222333, szTransactionAmount=1500, Desired Status=SETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000124, TransactionId=987654322.001
4. Get Transaction Status Method - Specifying Order Number
Preform a Get Transaction Status method to determine the final status of the OrderNumber 000124 prior to
shipping the order to confirm that the transaction has been approved.
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000124, szDate=
Get Transaction Status Response 1
HTML SerialNumber=000111222333, Transaction Amount=1500, Transaction Status Code=14,
Transaction Status Message=, Order Number=000124, Transaction Date and Time=11/29/06 15:05:12,
TransactionId=987654321.009, Approval Code=654321, Batch Number=999888777666
Page 186
 2009 Skipjack Financial Services
Skipjack Integration Guide
5. Change Transaction Status Method:SETTLE original transaction szAmount ($30.00)
Use the Change Transaction Status:SETTLE specifying the transaction number for the original transaction to
settle the original transaction.
Change Transaction Status Request 2
szSerialNumber=000111222333, szOrderNumber=000123, szTransactionId=987654321.005
szDesiredStatus=SETTLE, szAmount=3000, szForceSettlement=0
Change Transaction Status Response 2
SerialNumber=000111222333, szTransactionAmount=3000, Desired Status=SETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=987654321.005
6. Change Transaction Status Method:SETTLE for the additional amount
(AUTHORIZEADDITIONAL) transaction ($15.00)
Use the Change Transaction Status:SETTLE specifying the transaction number from the
AUTHORIZEADDITIONAL transaction to Settle the original transaction. Set the szForceSettlement to 1 on this
transaction to close the Settlement batch and submit the Batch for Settlement.
Change Transaction Status Request 2
szSerialNumber=000111222333, szOrderNumber=000124, szTransactionId=987654322.001
szDesiredStatus=SETTLE, szAmount=1500, szForceSettlement=1
Change Transaction Status Response 2
SerialNumber=000111222333, szTransactionAmount=1500, Desired Status=SETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000124, TransactionId=987654322.001
Page 187
 2009 Skipjack Financial Services
Skipjack Integration Guide
Scenario 6C – Authorize Original Amount, Change Status: Authorize
In this scenario, the Merchant will Authorize an original transaction and subsequently use the
ChangeStatus: AUTHORIZE to replace the original transaction. Using this approach you must
specify the original amount plus the additional costs of the shipping charges for the transaction
amount (szTransactionAmount). This method creates a new transaction that replaces the original
transaction that was Authorized previously.
Advantages
•
•
•
The transaction amount can be higher or less than the original amount.
Only a single transaction will exist and need to be Settled.
Authorized transaction amount and Settled amounts match, reducing the risk of chargebacks.
Disadvantages
•
The amount submitted for the transaction is deducted from the available credit (headroom) on
the credit card for Declines. Therefore, especially for large transaction amounts, this may
mean that you will be unable to obtain an Approval for the transaction until the credit limit on
the card has been reset. This may take 5 business days or longer, depending on the Issuing
Bank.
In this scenario, an authorization is obtained for an original transaction amount of $30.00. Once
shipping charges of $15.00 are determined, however, the Merchant wishes to use the
ChangeStatus:AUTHORIZE method to reauthorize the transaction for the total amount of $45.00 to
cover the original transaction amount plus the final shipping costs.
1. Use the Authorize Method to Submit the Original Transaction
The original transaction is submitted for Authorization with Ordernumber=000123. The Authorization is
Successful and returns the szTransactionFileName variable that in all subsequent transactions this variable is
called the TransactionID.
Authorize Request
Serial Number=000111222333, Sjname=John Doe, Email=jdoe@headoffice.com, City=BeverlyHills, State=CA,
Zipcode=90210, Shiptophone=1011011001, Accountnumber=41111111111111, Month=09, Year=2009,
Ordernumber=000123, Transactionamount=3000,
Authorize Response
AUTHCODE=654321, szSerialNumber=000111222333, szTransactionAmount=3000,
szAuthorizationResponseCode=T12345, szReturnCode=1, szIsApproved=1, szAuthorizationDeclinedMessage=,
szAVSResponseCode=, szAVSResponseMessage=, szOrderNumber=000123, szCVV2ResponseCode=,
szCVV2ResponseMessage=, szTransactionFileName=987654321.005, szCAVVResponseCode=
Page 188
 2009 Skipjack Financial Services
Skipjack Integration Guide
2. Get Transaction Status Method - Specifying Order Number
Later, just prior to shipping, the additional charge is determined and warehouse personnel perform a
Get Transaction Status method to determine the TransactionID and Status of the original Authorization for
OrderNumber 000123 prior to shipping the order. This returns the Transaction ID which can be used in step 3,
below.
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 1
HTML SerialNumber=000111222333, Transaction Amount=3000, Transaction Status Code=12,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 13:15:45,
TransactionId=987654321.005, Approval Code=123456, Batch Number=999888777666
3. Change Transaction Status Method:AUTHORIZE specifying new (different) szAmount
A Change Transaction Status:AUTHORIZEADDITIONAL is performed with the amount submitted as the new
Shipping Charges ($15.00) only using the Transaction ID determined above.
Change Transaction Status Request 1
szSerialNumber=000111222333, szOrderNumber=000123, szTransactionId=987654321.005
szDesiredStatus=AUTHORIZE, szAmount=1500, szForceSettlement=0
Change Transaction Status Response 1
SerialNumber=000111222333, szTransactionAmount=1500, Desired Status=SETTLE,
Status Response=Successful, Status Response Message=, szOrderNumber=000123, TransactionId=987654321.005
4. Get Transaction Status Method - Specifying Order Number
Perform a Get Transaction Status method to determine the final status of the OrderNumber 000123 prior to
shipping the order to confirm that the transaction has been Approved.
Get Transaction Status Request 1
Serial Number=000111222333, szDeveloperSerialNumber=123456789000, szOrderNumber=000123, szDate=
Get Transaction Status Response 1
HTML SerialNumber=000111222333, Transaction Amount=1500, Transaction Status Code=14,
Transaction Status Message=, Order Number=000123, Transaction Date and Time=11/29/06 15:05:12,
TransactionId=987654321.009, Approval Code=654321, Batch Number=999888777666
Page 189
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix A: Permitted Country Code Values
This section lists the Country Codes that can be specified for the Country, rtCountry, and
ShipToCountry variable fields. You may specify the following values for a specific country in the
Country, rtCountry, and ShipToCountry variable fields in Authorize/AuthorizeAPI, Add Recurring
Payments, and Edit Recurring Payments and Change Status fields for most Payment Processors.
Skipjack Financial Services supports ISO 3166-1 alpha-2, alpha-3 and numeric codes, as listed
below. For information about the ISO Country codes see the International Organizations for
Standards (ISO) Website at http://www.iso.org/iso/country_codes/iso_3166faqs/iso_3166_faqs_general.htm .
NOTE 1: The Country and rtCountry variables are Required variables for
Authorize/AuthorizeAPI method when using Paymentech Salem as your Payment Processor.
For more information see the “Appendix J: Using Soft Indicators” section for more details.
NOTE 2: When using Paymentech Salem or First Data Nashville as your Payment Processor
use only the 2 Character Alphabetic code values for Country, rtCountry and ShipToCountry
variable values.
NOTE 3: When using TSYS as your Payment Processor use only the 3 character numeric code
values for Country, rtCountry and ShipToCountry variable values.
Country Name
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
AFGHANISTAN
AF
AFG
004
ALBANIA
AL
ALB
008
ALGERIA
DZ
DZA
012
AMERICAN SAMOA
AS
ASM
016
ANDORRA
AD
AND
020
ANGOLA
AO
AGO
024
ANGUILLA
AI
AIA
660
ANTARCTICA
AQ
ATA
010
ANTIGUA AND BARBUDA
AG
ATG
028
ARGENTINA
AR
ARG
032
ARMENIA
AM
ARM
051
ARUBA
AW
ABW
533
AUSTRALIA
AU
AUS
036
AUSTRIA
AT
AUT
040
AZERBAIJAN
AZ
AZE
031
BAHAMAS
BS
BHS
044
BAHRAIN
BH
BHR
048
BANGLADESH
BD
BGD
050
BARBADOS
BB
BRB
052
Page 190
 2009 Skipjack Financial Services
Country Name
Skipjack Integration Guide
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
BELARUS
BY
BLR
112
BELGIUM
BE
BEL
056
BELIZE
BZ
BLZ
084
BENIN
BJ
BEN
204
BERMUDA
BM
BMU
060
BHUTAN
BT
BTN
064
BOLIVIA
BO
BOL
068
BOSNIA AND
HERZEGOWINA
BA
BIH
070
BOTSWANA
BW
BWA
072
BOUVET ISLAND
BV
BVT
074
BRAZIL
BR
BRA
076
BRITISH INDIAN OCEAN
TERRITORY
IO
IOT
086
BRUNEI DARUSSALAM
BN
BRN
096
BULGARIA
BG
BGR
100
BURKINA FASO
BF
BFA
854
BURUNDI
BI
BDI
108
CAMBODIA
KH
KHM
116
CAMEROON
CM
CMR
120
CANADA
CA
CAN
124
CAPE VERDE
CV
CPV
132
CAYMAN ISLANDS
KY
CYM
136
CENTRAL AFRICAN
REPUBLIC
CF
CAF
140
CHAD
TD
TCD
148
CHILE
CL
CHL
152
CHINA
CN
CHN
156
CHRISTMAS ISLAND
CX
CXR
162
COCOS (KEELING)
ISLANDS
CC
CCK
166
COLOMBIA
CO
COL
170
COMOROS
KM
COM
174
CONGO, Democratic
Republic of (was Zaire)
CD
COD
180
CONGO, People's Republic
of
CG
COG
178
COOK ISLANDS
CK
COK
184
COSTA RICA
CR
CRI
188
COTE D'IVOIRE
CI
CIV
384
Page 191
 2009 Skipjack Financial Services
Country Name
Skipjack Integration Guide
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
CROATIA
(local name: Hrvatska)
HR
HRV
191
CUBA
CU
CUB
192
CYPRUS
CY
CYP
196
CZECH REPUBLIC
CZ
CZE
203
DENMARK
DK
DNK
208
DJIBOUTI
DJ
DJI
262
DOMINICA
DM
DMA
212
DOMINICAN REPUBLIC
DO
DOM
214
EAST TIMOR
TL
TLS
626
ECUADOR
EC
ECU
218
EGYPT
EG
EGY
818
EL SALVADOR
SV
SLV
222
EQUATORIAL GUINEA
GQ
GNQ
226
ERITREA
ER
ERI
232
ESTONIA
EE
EST
233
ETHIOPIA
ET
ETH
231
FALKLAND ISLANDS
(MALVINAS)
FK
FLK
238
FAROE ISLANDS
FO
FRO
234
FIJI
FJ
FJI
242
FINLAND
FI
FIN
246
FRANCE
FR
FRA
250
FRANCE,
METROPOLITAN
FX
FXX
249
FRENCH GUIANA
GF
GUF
254
FRENCH POLYNESIA
PF
PYF
258
FRENCH SOUTHERN
TERRITORIES
TF
ATF
260
GABON
GA
GAB
266
GAMBIA
GM
GMB
270
GEORGIA
GE
GEO
268
GERMANY
DE
DEU
276
GHANA
GH
GHA
288
GIBRALTAR
GI
GIB
292
GREECE
GR
GRC
300
GREENLAND
GL
GRL
304
GRENADA
GD
GRD
308
GUADELOUPE
GP
GLP
312
GUAM
GU
GUM
316
Page 192
 2009 Skipjack Financial Services
Country Name
Skipjack Integration Guide
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
GUATEMALA
GT
GTM
320
GUINEA
GN
GIN
324
GUINEA-BISSAU
GW
GNB
624
GUYANA
GY
GUY
328
HAITI
HT
HTI
332
HEARD AND MC DONALD
ISLANDS
HM
HMD
334
HONDURAS
HN
HND
340
HONG KONG
HK
HKG
344
HUNGARY
HU
HUN
348
ICELAND
IS
ISL
352
INDIA
IN
IND
356
INDONESIA
ID
IDN
360
IRAN (ISLAMIC REPUBLIC
OF)
IR
IRN
364
IRAQ
IQ
IRQ
368
IRELAND
IE
IRL
372
ISRAEL
IL
ISR
376
ITALY
IT
ITA
380
JAMAICA
JM
JAM
388
JAPAN
JP
JPN
392
JORDAN
JO
JOR
400
KAZAKHSTAN
KZ
KAZ
398
KENYA
KE
KEN
404
KIRIBATI
KI
KIR
296
KOREA, DEMOCRATIC
PEOPLE'S REPUBLIC OF
KP
PRK
408
KOREA, REPUBLIC OF
KR
KOR
410
KUWAIT
KW
KWT
414
KYRGYZSTAN
KG
KGZ
417
LAO PEOPLE'S
DEMOCRATIC REPUBLIC
LA
LAO
418
LATVIA
LV
LVA
428
LEBANON
LB
LBN
422
LESOTHO
LS
LSO
426
LIBERIA
LR
LBR
430
LIBYAN ARAB
JAMAHIRIYA
LY
LBY
434
LIECHTENSTEIN
LI
LIE
438
LITHUANIA
LT
LTU
440
Page 193
 2009 Skipjack Financial Services
Skipjack Integration Guide
Country Name
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
LUXEMBOURG
LU
LUX
442
MACAU
MO
MAC
446
MACEDONIA, THE
FORMER YUGOSLAV
REPUBLIC OF
MK
MKD
807
MADAGASCAR
MG
MDG
450
MALAWI
MW
MWI
454
MALAYSIA
MY
MYS
458
MALDIVES
MV
MDV
462
MALI
ML
MLI
466
MALTA
MT
MLT
470
MARSHALL ISLANDS
MH
MHL
584
MARTINIQUE
MQ
MTQ
474
MAURITANIA
MR
MRT
478
MAURITIUS
MU
MUS
480
MAYOTTE
YT
MYT
175
MEXICO
MX
MEX
484
MICRONESIA,
FEDERATED STATES OF
FM
FSM
583
MOLDOVA, REPUBLIC OF
MD
MDA
498
MONACO
MC
MCO
492
MONGOLIA
MN
MNG
496
MONTSERRAT
MS
MSR
500
MOROCCO
MA
MAR
504
MOZAMBIQUE
MZ
MOZ
508
MYANMAR
MM
MMR
104
NAMIBIA
NA
NAM
516
NAURU
NR
NRU
520
NEPAL
NP
NPL
524
NETHERLANDS
NL
NLD
528
NETHERLANDS
ANTILLES
AN
ANT
530
NEW CALEDONIA
NC
NCL
540
NEW ZEALAND
NZ
NZL
554
NICARAGUA
NI
NIC
558
NIGER
NE
NER
562
NIGERIA
NG
NGA
566
NIUE
NU
NIU
570
NORFOLK ISLAND
NF
NFK
574
NORTHERN MARIANA
MP
MNP
580
Page 194
 2009 Skipjack Financial Services
Country Name
Skipjack Integration Guide
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
NORWAY
NO
NOR
578
OMAN
OM
OMN
512
PAKISTAN
PK
PAK
586
PALAU
PW
PLW
585
PALESTINIAN
TERRITORY, Occupied
PS
PSE
275
PANAMA
PA
PAN
591
PAPUA NEW GUINEA
PG
PNG
598
PARAGUAY
PY
PRY
600
PERU
PE
PER
604
PHILIPPINES
PH
PHL
608
PITCAIRN
PN
PCN
612
POLAND
PL
POL
616
PORTUGAL
PT
PRT
620
PUERTO RICO
PR
PRI
630
QATAR
QA
QAT
634
REUNION
RE
REU
638
ROMANIA
RO
ROU
642
RUSSIAN FEDERATION
RU
RUS
643
RWANDA
RW
RWA
646
SAINT KITTS AND NEVIS
KN
KNA
659
SAINT LUCIA
LC
LCA
662
SAINT VINCENT AND THE
GRENADINES
VC
VCT
670
SAMOA
WS
WSM
882
SAN MARINO
SM
SMR
674
SAO TOME AND
PRINCIPE
ST
STP
678
SAUDI ARABIA
SA
SAU
682
SENEGAL
SN
SEN
686
SEYCHELLES
SC
SYC
690
SIERRA LEONE
SL
SLE
694
SINGAPORE
SG
SGP
702
SLOVAKIA (Slovak
Republic)
SK
SVK
703
SLOVENIA
SI
SVN
705
SOLOMON ISLANDS
SB
SLB
090
SOMALIA
SO
SOM
706
SOUTH AFRICA
ZA
ZAF
710
ISLANDS
Page 195
 2009 Skipjack Financial Services
Country Name
Skipjack Integration Guide
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
SOUTH GEORGIA AND
THE SOUTH SANDWICH
ISLANDS
GS
SGS
239
SPAIN
ES
ESP
724
SRI LANKA
LK
LKA
144
ST. HELENA
SH
SHN
654
ST. PIERRE AND
MIQUELON
PM
SPM
666
SUDAN
SD
SDN
736
SURINAME
SR
SUR
740
SVALBARD AND JAN
MAYEN ISLANDS
SJ
SJM
744
SWAZILAND
SZ
SWZ
748
SWEDEN
SE
SWE
752
SWITZERLAND
CH
CHE
756
SYRIAN ARAB REPUBLIC
SY
SYR
760
TAIWAN
TW
TWN
158
TAJIKISTAN
TJ
TJK
762
TANZANIA, UNITED
REPUBLIC OF
TZ
TZA
834
THAILAND
TH
THA
764
TOGO
TG
TGO
768
TOKELAU
TK
TKL
772
TONGA
TO
TON
776
TRINIDAD AND TOBAGO
TT
TTO
780
TUNISIA
TN
TUN
788
TURKEY
TR
TUR
792
TURKMENISTAN
TM
TKM
795
TURKS AND CAICOS
ISLANDS
TC
TCA
796
TUVALU
TV
TUV
798
UGANDA
UG
UGA
800
UKRAINE
UA
UKR
804
UNITED ARAB EMIRATES
AE
ARE
784
UNITED KINGDOM
GB
GBR
826
UNITED STATES
US
USA
840
UNITED STATES MINOR
OUTLYING ISLANDS
UM
UMI
581
URUGUAY
UY
URY
858
UZBEKISTAN
UZ
UZB
860
VANUATU
VU
VUT
548
Page 196
 2009 Skipjack Financial Services
Country Name
Skipjack Integration Guide
2 Character Alpha Code
3 Character Alpha Code
3 Character Numeric Code
VATICAN CITY STATE
(HOLY SEE)
VA
VAT
336
VENEZUELA
VE
VEN
862
VIET NAM
VN
VNM
704
VIRGIN ISLANDS
(BRITISH)
VG
VGB
092
VIRGIN ISLANDS (U.S.)
VI
VIR
850
WALLIS AND FUTUNA
ISLANDS
WF
WLF
876
WESTERN SAHARA
EH
ESH
732
YEMEN
YE
YEM
887
YUGOSLAVIA
YU
YUG
891
ZAMBIA
ZM
ZMB
894
ZIMBABWE
ZW
ZWE
716
Page 197
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix B: Address Verification System (AVS) Checking
The Address Verification System (AVS) is a service provided by credit card Issuers intended to
authenticate the Purchaser (Customer) as the authorized cardholder. AVS checking is performed by
matching the numerical address information provided at the time of a purchase (such as in a shipping
address field) with that numerical address information held on record for the authorized cardholder.
This information is included with the order and transmitted to the Skipjack Transaction Network and
the Issuers networks for scrutiny.
It is important to understand that AVS checking only compares the numeric portion of the cardholder's
street address and the 5 or 9-digit zip code/postal code to that held on record for the cardholder. AVS
return codes are returned based on how well this data matches and the level of matching required
can be configured for each Merchant Account. By default, AVS filtering is disabled within Skipjack
Transaction Network.
AVS does not examine the text portion of the address, such as street names or city names. As a
result, AVS is a basic method of fraud prevention only and helps to prevent the use of counterfeit
(computer generated) credit card numbers not associated with a legitimate cardholder.
AVS use is not required in all transactions by the card Issuers and Processors. However, submitting
AVS data with every transaction can help ensure that Merchants receive improved transaction rates
from Processors and Issuers. For these reasons the use of AVS checking is highly
recommended by Skipjack.
AVS Filtering within the Skipjack Transaction Network
The AVS verification is performed by the credit card Issuer and an AVS response code and message
are returned to the Processor and to the Skipjack Transaction Network. The values of this AVS match
are carried in the szAVSResponseCode and szAVSResponseMessage return variables. These
return variables indicate the level of matching obtained in the AVS check.
The Skipjack Transaction Network permits AVS filtering options to be set on the Merchant Account.
The levels of AVS matching configured are independent of and in addition to the AVS checking done
by the Issuer. The Skipjack Transaction Network AVS filters are applied after the Issuer performs its
AVS checking.
If the Skipjack AVS filtering option is enabled and configured to require a high level of matching for
transactions, AVS filtering is performed on each transaction on a particular Merchant Account. The
default setting for this feature is that no AVS filtering will be applied.
The AVS filters can also be configured to handle Domestic and International transactions differently.
See Also
• For more information about how to configure using the Merchant Interface, see the AVS
section in the Skipjack Merchant Services Guide.
• For more information about the development considerations when configuring International
and Domestic AVS handling see the AVS section of the Skipjack Integration Overview Guide.
Page 198
 2009 Skipjack Financial Services
Skipjack Integration Guide
Development Notes for AVS and AVS Filtering
Consider the following when applying AVS and AVS filtering in your application development.
•
AVS is not supported for Declined transactions. No further processing is done on transactions
Declined by the Issuing Bank.
•
When Skipjack AVS is configured to require a high AVS matching threshold, the transaction
can be Declined by the Skipjack Transaction Network despite the transaction being Approved
by the credit card Issuer. The Issuer never declines based on AVS values, they simply pass
this information through their networks to Skipjack Financial Services.
•
If AVS filtering leads to a transaction Decline, the available credit (headroom) on the card is
decreased by the transaction amount submitted. For subsequent transactions the headroom
on the card is decreased by this transaction amount for a period of 7 days (normally).
This creates a problem when the headroom is nearing its limit on the card and the transaction
is resubmitted for a second Authorization attempt. This can lead to another Decline with further
decreases in headroom being made on the card.
In these instances, the Merchant must call the card Issuer to reverse the reserved amount(s)
from the transaction(s) that were previously Declined. The Merchant can then resubmit the
transaction. The Merchant can then receive a transaction Approval, assuming the AVS
threshold was sufficiently lowered from the original settings or the correct address information
is sent. The presence of an AUTHCODE value when the szIsApproved=0 is the true indicator
of the status of the transaction in these cases.
Page 199
 2009 Skipjack Financial Services
Skipjack Integration Guide
AVS Codes by Card Type
Summary
AVS Response Code Description
X
Match
Street address and 9-digit ZIP code both
match
Y
Match
Street address and 5-digit ZIP code both
match.
X
A
Partial Match
Street address matches, but both 5-digit
and 9-digit ZIP Code do not match.
X
W
Partial Match
Street address does not match, but 9digit ZIP code matches.
Z
Partial Match
Street address does not match, but 5digit ZIP code matches.
X
X
X
X
N
No Match
Street address, 5-digit ZIP code, and 9digit ZIP code all do not match.
X
X
X
X
U
System Unavailable
Address information unavailable.
Returned if non-US.
AVS is not available or if the AVS in a
U.S. bank is not functioning properly.
X
X
X
X
R
System Unavailable
Retry - Issuer's System Unavailable or
Timed Out.
X
X
X
E
Invalid
AVS data is invalid.
X
S
Not Supported
USA issuing bank does not support AVS.
X
X
X
Not Supported
Non-USA issuing bank does not support
AVS.
X
Return
Code
G
Visa
MC
AMEX
DISCOVER
X
X
X
X
X
X
X
X
X
NOTE: By default, the Skipjack AVS filtering configuration is set to NOT DECLINE any transactions based on
AVS settings. Increasing the filter configuration matching requirements can lead to more transactions being
declined.
Page 200
 2009 Skipjack Financial Services
Skipjack Integration Guide
AVS Response Codes for International and Domestic Credit Cards
When sending a transaction with AVS checking required the Issuing Bank will return one of the
following AVS response codes. The table below breaks down the responses returned by credit card
type.
Code
Summary
Description
D
Match
Street Address and Postal Code match for International Transaction.
M
Match
Street Address and Postal Code match for International Transaction.
B
Partial Match
Street Address Match for International Transaction. Postal Code not verified due to
incompatible formats.
P
Partial Match
Postal Codes match for International Transaction but street address not verified due to
incompatible formats.
C
No Match
Street Address and Postal Code not verified for International Transaction due to
incompatible formats.
I
No Match
Address Information not verified by International issuer.
O
Not Supported
USA Issuer does not participate.
G
Not Supported
Non-USA issuing bank does not support AVS.
AVS Code Handling for International and Domestic Transactions
The Merchant Interface allows the configuration of different matching criteria for AVS checks
performed on Domestic and International transactions. In this context, Domestic is always defined as
from the country where the Originating Bank/Issuer is located.
This means that for Originating Banks (Card Issuers) based in the United States of America (USA),
Domestic will always means USA-based transactions and International will always be any transaction
to cardholders with Issuers located outside the USA.
NOTE: For Canadian Merchant Accounts handling Canadian transactions some Merchants
might see different handling of the AVS codes than is described here.
Use of Canadian Postal Codes in AVS Checks
For Canadian Merchant Accounts with a Canadian Originating Bank/Issuer with AVS checking
enabled for Domestic transactions, the Zip Code variable (ZipCode) is used with a Postal Code value
for AVS checking purposes.
For American Originating Banks/Issuers that have AVS checking enabled for International
transactions, the Postal Code is used in the Zip Code variable (ZipCode) in the AVS matching
process.
See Also
• For more information about how to configure the Skipjack Merchant Account through the
Merchant Services interface see the applicable section in the Skipjack Merchant Services
Guide.
Page 201
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix C: CVV and Interpreting CVV Return Codes
Card Verification Values (CVV) codes are proprietary three or four-digit codes used by credit card
Issuers as an anti-fraud mechanism for credit card transactions. CVV checking is used most
commonly in card-not-present transaction situations, however, CVVs may also be used in cardpresent transactions to run the cryptographic authentication check of the CVV code to determine
whether the card is legitimate or a counterfeit card.
CVV codes appear only on the card itself and are not included on bank statements, receipts, or
encoded in the trackdata information on the back of the card. Therefore, successful submission of
CVV confirms that the purchaser is in physical possession of the credit card. CVV code checking in
transactions is not mandatory by all Processors and Issuers, however use of CVV in transactions is
highly recommended by Skipjack.
How CVV Code Checking is Used in Transactions
The Merchant requests the CVV code from the purchaser at the time of purchase. (Actual code
names and locations are proprietary and vary by Card Type and Issuer, see the table below.) The
CVV value is input along with other transaction details at the time of purchase.
When the CVV code is sent to the Skipjack Transaction Server it is passed to the Processor and
Issuer’s systems for scrutiny. A return code is issued by the Processor/Issuer and sent back to the
Skipjack Transaction Network. The szCVVResponseCode and the szCVVResponseMessage
return variables and values are used to determine the outcome of the CVV match.
The Skipjack Merchant Interface allows the Merchant Account to be configured to require the use of
CVV matching for every transaction. Enabling this feature (Mandatory CVV Matching) ensures that
CVV values must be included for every transaction.
To enable Skipjack Transaction Server to require CVV checking for every transaction:
1. Login to the Merchant Account.
2. Click on the Edit Account button located in the bottom section of the Account Summary
page.
3. Scroll to the bottom of the page and select the check-box beside Make CVV a required
field. The new feature is toggled on when a check mark is displayed in this box.
4. Scroll to the bottom of the page and select the Submit button. The feature is now enabled
and a message is displayed to indicate that these account changes were successful.
5. Use the Back button on the Web browser to return to the previous screen.
6. Select the Exit link at the top of the page to log out of the Merchant Account.
The table below lists the card types by Issuer and related information about each proprietary code by
card type.
Page 202
 2009 Skipjack Financial Services
Skipjack Integration Guide
CVV Code Locations by Card Type
Card Type
Name
Location on Card and Notes
Visa
Card Verification Value (CVV2)
Three digits to the right of the credit card number in the
signature area on back of the card.
MasterCard/Eurocard
Card Verification Code (CVC2)
Three digits to the right of the credit card number in the
signature area on back of the card.
Discover
Card Identification Number (CID)
Three digits to the right of the credit card number in the
signature area on back of the card.
Does not return a CVV return code.
American Express
Card Identification Number (CID)
Four digits printed (not embossed) on the right front of
the card above the credit card number.
Does not return a CVV return code.
CVV Response Codes for Visa and MasterCard/Eurocard
CVV Response Code
Description
M
CVV Match
N
CVV No Match
P
Not Processed
S
Issuer indicates that CVV2 data should be present on the card, but the Merchant has
indicated data is not present on the card.
U
Issuer has not certified for CVV2 or Issuer has not provided Visa with the CVV2 encryption
keys.
Empty
Transaction failed because incorrect CVV2 number was entered or no CVV2 number was
entered.
NOTE: If you have questions about how your application must be designed to use the CVV
data or CVV requirements for your Processor you should contact your Processor(s) directly.
Page 203
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix D: Avoiding Duplicate Transactions
Duplicate transactions submitted in error to the Skipjack Transaction Server for a single purchase
may result in the credit cardholder (Customer) being billed multiple times for a single purchase.
This is a rare occurrence under normal circumstances and users can configure the Skipjack
Transaction Network to reject duplicate transactions, as described below.
Development Notes on Avoiding Duplicate Transactions
1. Ensure that your application generates and uses a unique Order Number for each transaction.
Using a unique Order Number will help prevent duplicate orders from being posted to the
Skipjack Transaction Network.
The OrderNumber variable is a Merchant-generated return value that uses syntax useful to
the Merchant’s application. If a duplicate OrderNumber did occur, then the szTransactionId
return variable associated with the transaction can be used to differentiate transactions.
However, the Customer could still be charged more than once, if the Merchant Account
settings are set to Settle immediately.
Unique OrderNumber values are retained within the Skipjack Transaction Network while the
transaction is in the Approved state. If a transaction is in another state, for example Deleted or
Settled states, the Skipjack Transaction Server will not reject orders with that same Order
Number if the Reject based on OrderNumber feature is enabled, as described below.
NOTE: Duplicate transactions will return the szReturnCode = -84 only when the Reject
duplicate transactions based on Order Number feature is enabled as described
previously. See the “Appendix I: Unique Order Numbers” section for more information.
2. In special circumstances, such as very high-volume transaction environments, or also when an
order form Submit button is rapidly pressed in quick succession, duplicate transactions might
occur. These duplicates may not be prevented by enabling the Reject duplicate transactions
based on Order Number.
This situation occurs because the transactions are received by the Skipjack Transaction
Network within milliseconds (more or less simultaneously) of each other and have not been
written to the database when the duplicate OrderNumber arrives and is also written to the
database. Although this is a rare occurrence this could occur under special circumstances.
To prevent duplicate transactions in these circumstances Skipjack recommends that you use
an appropriate script in your order form to ensure that duplicate transactions are not generated
by rapidly pressing the Submit button.
Skipjack Financial Services provides sample scripts that can be used for this purpose,
available at from the Skipjack Financial Services Website.
Page 204
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix E: Configuring Level II Transaction Data
This section describes the transaction variables and values that must be used for all Level II (and
subsequently Level III) transactions when submitting authorization requests using Skipjack Financial
Services.
NOTE: Skipjack Financial Services passes Level II transaction data to the Payment Processors
and handing of this data outside of the Skipjack Transaction Network is beyond Skipjack
Financial Services’ control. Skipjack Financial Services cannot control or guarantee that the
Level II transaction rates will be obtained, since this depends on many external factors. The
information in this section of the guide therefore is intended to serve as the best practices to
follow when processing Level II data to ensure Skipjack Financial Services requirements for
Level II data processing are fulfilled.
Card Type
Variables and Values
Visa
Customer Code = Required Value, may be passed as a “dummy value”.
Purchase Order Number = Required, cannot be alphabetic characters.
Customer Tax = Required, must have a value between 0.1 and 22.00.
MasterCard
Customer Code = Required Value, may be passed as a “dummy value”.
Purchase Order Number = Required, populated with valid value, may be “dummy value”.
Customer Tax = Required, must have a value between 0.0 and 30.00, may be “dummy value”.
Development Notes for Level II Data
•
To process Level II transactions, you require a Level II Skipjack account set to allow Level II
transaction processing. Contact Skipjack Financial Services Customer Support if you require
this functionality.
•
Level II transaction data is submitted in the Authorization request but not processed until the
transaction is Settled.
•
Payment Processors may change the requirements for processing Level II transactions at their
discretion. If you have questions regarding processing Level II transactions or experience a
change in how Level II transactions are being handled or qualified, please contact your
Payment Processor to ensure that they have not changed the submission requirements for
processing Level II transactions. If this does not resolve the issue then contact Skipjack
Financial Services Customer Support to work through the issue in collaboration with your
Merchant Account Provider.
•
If you have read the information in all relevant sections of the Skipjack Guides and you have
questions about processing Level II transactions or are unclear about the Level II transaction
processing requirements, contact Skipjack Financial Services for guidance.
•
Level II transaction variables that are required for Level II transaction processing are also
required variables for processing Level III transactions.
Page 205
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix F: TSYS PIN-based Debit Transactions Information
The following table lists and describes the required and optional request variables used for the
TSYS PIN-based Debit Service. Your application must use the following variables in properly
formatted and fully-formed name-value pairs for each transaction request.
NOTE: Variables in red are new variables introduced by this service.
For more information about these variables including formatting and values see the “Request
Variables for Authorize and AuthorizeAPI Methods” section for details.
Details
Debit (Purchase)
Credit
Reversal
A transaction amount
with a positive value
is made to the
Skipjack Transaction
Network and this
amount is debited
from the customer’s
bank account.
A transaction amount with a
negative value is made to
Skipjack Transaction Network and
this amount is credited to the
customer’s bank account.
Reversal can be used to reverse either a
Debit or a Credit. A transaction amount with
a negative value is made to the Skipjack
Transaction Network and this amount will be
reversed from the customer’s bank account.
The Credit transaction will appear
as a distinct transaction on the
customer’s bank record.
No record of this transaction will appear on
the customer’s bank account record.
A record of the
transaction will
appear on the
customer’s bank
record if not credited.
A Credit can be applied to an
existing transaction record after
60 minutes have elapsed from the
original transaction was
authorized.
Reversals must be submitted by using the
Unqtransactionid variable to identify the
original transaction and be submitted within
60 minutes of the original transaction
otherwise a Credit must be performed.
Required
Request
Variables
PINBlock
TransactionAmount
SerialNumber
OrderNumber
SJName
StreetAddress
City
State
Zipcode
Country
E-mail
ShiptoPhone
OrderString
PINBlock
TransactionAmount
SerialNumber
OrderNumber
SJName
StreetAddress
City
State
Zipcode
Country
E-mail
ShiptoPhone
OrderString
Unqtransactionid
TransactionAmount
SerialNumber
OrderNumber
SJName
Street address
City
State
Zipcode
Country
E-mail
ShiptoPhone
OrderString
Accountnumber
Month
Year
Optional
Request
Variables
CashbackAmount
None
None
Page 206
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example Code Snippets
Request Variables
NOTE: In the code snippet below, the new variables used for this service are highlighted in red text.
<head>
<title>Tsys Pin Debit</title>
</head>
<body>
<h1>Tsys Pin Debit</h1>
<form action="https://developer.skipjackic.com/scripts/evolvcc.dll?AuthorizeAPI"
method="post">
purchase or credit or reversal
<br /><br />
serial number <input type="text" name="serialnumber" value=""><br />
order number <input type="text" name="ordernumber" value=""/><br />
sjname <input type="text" name="sjname" value=""><br />
street address <input type="text" name="streetaddress" value="" /><br />
city <input type="text" name="city" value=""/><br />
state <input type="text" name="state" value="" /><br />
zip code <input type="text" name="zipcode" value="" /><br />
country <input type="text" name="country" value="" /><br />
email <input type="text" name="email" value="” /><br />
phone <input type="text" name="shiptophone" value="" /><br />
orderstring <input type="text" name="orderstring" size="40" value="" /><br />
amount <input type="text" name="transactionamount" value="" /><br />
cash back (optional) <input type="text" name="cashbackamount" value="" /><br />
<br />
purchase or credit
<br /><br />
track data <input type="text" name="trackdata" size="120" value=”” /><br />
pin block <input type="text" name="pinblock" size="40" value=" " /><br />
<br />
reversal
<br /><br />
transaction id <input type="text" size="40" name="unqtransactionid" value="" /><br />
account number <input type="text" size="40 name="accountnumber" value="" /><br />
expiry month <input type="text" name="month" value="" /><br />
expiry year <input type="text" name="year" value="" /><br />
<br />
<input type="submit" value="submit" />
</form>
</body>
</html>
Page 207
 2009 Skipjack Financial Services
Skipjack Integration Guide
Example Response String
The example below illustrates a typical Authorization response for the TSYS PIN-based debit service.
NOTE: The szCAVVResponseCode value returned denotes the settlement date for the transaction in
MonthMonthDayDay format. For Reversals, the szCAVVResponseCode value returned denotes the settlement
time of the original transaction.
Response Example: Authorize
"<!--AUTHCODE=VITAL5--><!--szSerialNumber=111222333444--><!--szTransactionAmount=1900-><!--szAuthorizationDeclinedMessage=--><!--szAVSResponseCode=N--><!-szAVSResponseMessage=Card authorized, no address or zip code match.--><!-szOrderNumber=1--><!--szAuthorizationResponseCode=000067--><!--szReturnCode=1--><!-szCVV2ResponseCode=--><!--szCVV2ResponseMessage=--><!--szIsApproved=1--><!-szTransactionFileName=9802850951761.009--><!--szCAVVResponseCode=1225-->
Development Notes for the TSYS PIN-based Debit Service
The following development guidelines apply:
•
The PINBlock is 32 characters long and must be formatted in following way:
AAAAAAAAAAAAAAAAKKKKKKKSSSSSSSSSS, where A represents Expanded
Encrypted PIN Block Data (16 characters), K (6 characters) represents Key Set Identifier
(KSID), and the S (10 characters) is the Expanded TRSM ID (PIN Pad Serial Number).
•
The PINBlock is encrypted and is not stored within the Skipjack Transaction Network.
•
When reversing a Debit transaction using Reversals the Unqtransactionid is used to uniquely
identify the original transaction to be reversed, not the OrderNumber.
•
The TransactionAmount used for a Credit or a Reversal may not exceed the original
TransactionAmount, otherwise a szReturnCode = -57 error will be returned.
•
In the case of a Credit Reversal, the szCAVVResponseCode will contain the date in DDMM
format of the original transaction authorization.
•
Credits require that a negative value is submitted for TransactionAmount.
•
When the (optional) feature is used the TransactionAmount contains the sum of the product
or service purchased plus the amount of cash disbursed as the Cashback amount.
•
For Reversals of transactions where the original transaction included a CashbackAmount, the
Customer must return the Cashback money and the CashbackAmount and
TransactionAmount value from the original transactions must be applied to the Reversal.
•
For additional information, including Skipjack Financial Services Certification Test Cases and
other details see the Skipjack TSYS PIN-based Debit Services Guide.
Page 208
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix G: Blind Credits
A Blind Credit is a Credit (Refund) applied to a transaction for which a record is not currently held
within the Merchant Register (Skipjack Transaction Network database).
A Blind Credit may be required when a Merchant moves their business from another payment
gateway to Skipjack Financial Services and a customer requests a Credit to be applied to
transactions previously processed by the other payment gateway.
When submitting a Blind Credit using the “Authorize and AuthorizeAPI Methods”, a negative
TransactionAmount is specified in the Transaction Amount variable. To perform a Blind Credit the
Merchant must obtain all credit card information from the customer (Account Number, Name, Expiry,
CVV code, etc.) in order to complete the Blind Credit.
Prerequisites and Requirements for Performing Blind Credits
To use Blind Credits on a specific Merchant Account the following must be enabled and supported:
•
Blind Credits must be supported both by your Financial Institution’s Merchant Account.
•
The Allow Blind Credit option must be enabled on your Skipjack Merchant Account.
Please contact Skipjack Customer Support or your Skipjack Authorized Reseller to enable this
feature on your Merchant Account if you do not have the necessary account permissions to set
this option yourself.
Page 209
 2009 Skipjack Financial Services
Skipjack Integration Guide
szReturnCode Error Messages Associated with Blind Credits
szReturnCode Value
Error Name/Type
Description
-93
Blind Credits Request
Refused
Blind credit attempt failed.
Enable Allow Blind Credits option on the Skipjack account and
resubmit the transaction.
See the “Configuring the Skipjack Merchant Account to Permit Blind
Credits” section for details.
-94
Blind Credits Failed
option on the Skipjack account and resubmit the transaction.
See the “Configuring the Skipjack Merchant Account to Permit Blind
Credits” section for details.
Blind Credits versus Change Status: Credit
The Change Status method (see “Change Transaction Status Method”) can be used, by specifying
the szDesiredStatus=Credit variable, for crediting transactions where the Merchant does not have
all credit card information available and/or they want to provide a Credit (refund) to the customer
where the transaction was originally submitted through the Skipjack Transaction Network. When
using the Change Transaction Status method, the Merchant does not need to submit the any
credit card information to perform the Credit.
Blind Credits are used in situations where the original transaction was processed using a competitor’s
payment gateway. Therefore, it is necessary to re-enter all credit card information or swipe the
credit card to complete the Blind Credit transaction. You would use the Authorize/AuthorizeAPI
(see “Authorize and AuthorizeAPI Methods” section) specifying a TransactionAmount with a
negative value to complete a Blind Credit.
Page 210
 2009 Skipjack Financial Services
Skipjack Integration Guide
Configuring the Skipjack Merchant Account to Permit Blind Credits
By default the Skipjack Merchant Account is configured to not permit blind credits. Depending on
your Skipjack Merchant Account permissions, you may be able to change these configuration options
to allow Blind Credits for a specific Skipjack Merchant Account.
NOTE: If you are not able to access the Account Setup Page for your Skipjack account this means you do not
have the required account permissions to make the required Skipjack account changes. Contact Skipjack
Financial Services Customer Support and request these configuration changes be applied to your Skipjack
Merchant Account and/or request the access privileges to configure these account options.
To display and set the Skipjack Merchant Account settings for the Allow Blind Credit option:
1. Login to the Merchant Account at https://secure.skipjack.com using your account credentials
supplied by Skipjack Financial Services.
2. Click on the Edit Account button located in the bottom section of the Account Summary
page.
3. Scroll down the page to locate the Allow Blind Credits section, as shown below.
4. Select the check-box beside the Allow Blind Credits to enable this configuration option on
the Skipjack Merchant Account.
5. Click the Submit button to make the changes to the configuration settings.
Page 211
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix H: Using Trackdata Details in Transactions
The Skipjack Transaction Network is compatible with Track 1 and Track 2 data encoded in the
magnetic stripe on the reverse side (back) of all credit cards. This section provides details about
usage of Trackdata information in the Skipjack Transaction Network.
Recommended Trackdata Hardware
Trackdata Hardware Devices supported by the Skipjack Transaction Network:
•
•
•
•
Magtek Magnetic Swipe Card Reader, Mini USB
Magtek Magstripe Swipe Card Reader, Mini Wedge
Magtek MICR PLUS (Combo Reader for Swipe Check and Swipe Card)
Magtek MICR (Check Reader)
For more information about these devices, visit http://www.magtek.com.
Trackdata Information and Examples
Skipjack
Variable
Format
Required/Optional
Example
Trackdata
Track 1
and
Track 2
Required
B4003000123456781^GLOBAL PAYMENTS TEST
CARD/^090850254321987123456789012345 (Track 1 only)
;4003000123456781=09085025432198712345 (Track 2 only)
B4003000123456781^GLOBAL PAYMENTS TEST
CARD/^090850254321987123456789012345?;4003000123456
781=09085025432198712345? (Track 1 and 2 only)
Account Number
Numeric
Conditional – Do
not send if
Trackdata is
passed.
4003000123456781
Month
Numeric
Conditional – Do
not send if
Trackdata is
passed.
12
Year
Numeric
Conditional – Do
not send if
Trackdata is
passed.
10 or 2010
Page 212
 2009 Skipjack Financial Services
Skipjack Integration Guide
Trackdata Capture, Formatting and Usage Notes
NOTE 1: If trackdata is not sent, or the incorrect Track is sent as specified by your Payment Processor (Track 2
instead of Track 1), or if the trackdata data are malformed (corrupted), the transaction may be downgraded to a
less favorable interchange rate. This will result in increased costs to the Merchant depending on your Payment
Processor’s transaction processing guidelines and rules.
NOTE 2: Please ensure that the location (State and Zipcode fields) setting on the Skipjack Account’s Vendor
Preferences screen is correct otherwise swiped transactions may be Declined.
The Decline is caused by the cardholders issuing bank scrutinizing the merchant location information for an
authorization attempt. If the location information is not correct, it can make the transaction appear to the issuing
bank as a potentially fraudulent transaction. As such, the issuing bank declines the transaction.
See the “Payment Processors Supported by Skipjack Financial Services” section to determine if your
Payment Processor supports Trackdata.
•
To use a supported swipe device, the Merchant’s Skipjack Account must first be configured
with the Electronic Commerce Indicator (ECI) flag turned off.
•
Skipjack-compliant trackdata cannot contain the percentage symbols ("%") otherwise this will
cause URL encoding which will break the data string. Please remove percentage symbols from
the start of the trackdata.
•
The Skipjack Transaction Network can handle most of the usual delimiters, such as an equal
sign (=), at the end of the second occurrence of the card number.
•
The Skipjack Transaction Network automatically interprets the second occurrence of the credit
card number as the start of Track 2.
•
Some Processors, such as TSYS, require an upper case letter B at the start of the Track Data.
Do not use lower case, b.
•
When using TSYS as your Payment Processor, only Track 2 data is supported.
•
When sending Trackdata, Skipjack Financial Services suggests sending both Track 1 and
Track 2 data, unless you are directed otherwise by your Payment Processor.
•
If using Global Payments as the Processor trackdata can be transmitted as Track 1 only or
Track 1 and Track 2.
•
Please ensure that you test your trackdata with Live transactions to confirm that the expected
transaction rate is applied to swiped transactions in the Settled transactions.
•
When using the ChangeStatus methods with Authorize, AuthorizeAdditional, AuthorizeEx or
AuthorizeAdditionalEx and the original transaction was swiped, the ChangeStatus transaction
will be handled as a non-swiped (keyed) transaction.
Page 213
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix I: Unique Order Numbers
The Order Number assigned to each transaction must be generated by your application. The
OrderNumber variable is a required transaction variable for many Core and Supplementary
transaction methods (see the “Supplementary Methods” section for a listing of these methods).
Except in rare circumstances and for application testing, the OrderNumber assigned to each
transaction should be unique to prevent duplicate records with the same Order Number in the
Merchant Registry. In terms of the Skipjack Transaction Network database, Duplicate Order Numbers
are those Order Numbers submitted within a 24 hour period that use the same Order Number value
as a previously submitted.
If the Order Number matches any Approved or Pending Credit transaction records (duplicates) in the
Merchant Register an error code is returned if the Reject Duplicate Order Numbers configuration
option is set in the Skipjack Merchant Account. The szReturnCode Value=-84 (error code) is also
returned from the Skipjack Transaction Network and the transaction is Declined.
NOTE 1: The Order Number variable can be a maximum of 22 characters for those using
Paymentech as their Payment Processor. In these cases the Order Number must be unique
per Settlement Batch.
NOTE 2: By default the Skipjack Merchant Account does not prevent your application from
submitting a duplicate Order Number. (The Reject Duplicate Order Numbers option is off).
How to Identify Transactions When Duplicate Order Numbers Exist
The Transaction ID (szTransactionId) generated by the Skipjack Transaction Network can be used to
differentiate and identify transactions that do have duplicate Order Number within the Merchant
registry.
To differentiate between transactions with duplicate Order Numbers:
1. Use the Get Transaction Status method and specify the transaction date to retrieve the
szTransactionId associated with the transaction you wish to perform any subsequent action
on, such as a Change Transaction Status method.
For information about the use of the Get Transaction Status method see also the “Get
Transaction Status Method” section.
2. Use the Transaction ID, obtained in step 1 above, to identify the transaction you wish to
change.
Page 214
 2009 Skipjack Financial Services
Skipjack Integration Guide
Other Transaction Methods Using Order Number as a Required Variable
The Order Number variable is Required and used in the following transaction methods:
•
•
•
•
“Get Transaction Status Method” (szOrderNumber)
“Change Transaction Status Method” (szOrderNumber)
“Add Recurring Payment Method” (rtOrderNumber)
“Edit Recurring Payments Method” (rtOrderNumber)
Configuring the Reject Duplicate Order Numbers Option for a Merchant Account
By default the Skipjack Merchant Account is configured to permit duplicate Order Numbers for a
Skipjack Merchant Account. Typically this configuration is not problematic and is actually preferred for
testing certain application behaviors in a Development environment. However, rejecting transactions
based on duplicate order numbers is recommended for Skipjack Merchant Accounts that are
processing Live transactions.
Depending on your Skipjack Merchant Account permissions, your Skipjack Merchant Account settings
may allow or reject transactions based on Order Number duplicates.
To set the Reject duplicate transactions based on order number settings Merchant Account
options:
1. Login to the Skipjack Merchant Account at https://secure.skipjack.com.
2. Select the Edit Account button in the bottom section of the Account Summary page to
display the Account Setup Page.
NOTE: If you are not able to access Account Setup Page, you do not have the required account
permissions. Contact the Skipjack Financial Services Customer Support to have this configuration
change applied to your Skipjack Merchant Account.
3. Scroll down to the Reject duplicate transactions based on order number section as
shown below and select the check-box beside the option shown.
Page 215
 2009 Skipjack Financial Services
Skipjack Integration Guide
4. Select the Submit button to invoke the changes.
5. Use your Web browser’s Back button to return to previous pages to continue working or
select the Exit link to log out of the Merchant Register.
Page 216
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix J: Using Soft Indicators with Paymentech and TSYS
Presently only Paymentech Salem and TSYS support Soft Indicator functionality and therefore this
section applies only to Skipjack Merchant Accounts that are using Paymentech Salem or TSYS as
their Payment Processor.
The Soft Indicator is a dynamic descriptor of a transaction that appears on the Customer’s credit card
statement. The use of Soft Indicators may help reduce the incidence of disputed charges by
Customers because the descriptor helps to more clearly identify transactions that appear on the
Customer’s credit card statement.
Soft Indicator Implementation Guidelines
•
Soft Indicators are currently supported only by Paymentech Salem and TSYS for credit card
transactions only.
•
The OrderDescription variable is an Optional transaction request variable that carries the Soft
Indicator data. The OrderDescription may be a maximum of 22 alphanumeric characters
(instead of 20 characters supported for other Payment Processors). See “Transaction
Requests for Authorize and AuthorizeAPI” section for a detailed description of the
OrderDescription variable.
•
The proper functioning of the Soft Indicator for Credits (using Change Transaction Status:
Credit) and can only be tested using a Live credit card and obtaining the credit card statement
to confirm the Soft Indicator is properly displayed.
•
The Country variable is a required variable and must be included in all Authorize/AuthorizeAPI
requests.
Setting Merchant Services Vendor Preferences to Support Soft
Indicators
Some Skipjack Merchant Account details are also included as part of the Soft Indicator on the
Customer’s card statement. These fields are described below. Suggested configuration options are
indicated for each applicable field. These fields are found on the Vendor Preferences screen in the
Merchant Register.
Business Type
Recommended Skipjack Merchant Account Configuration Setting
Retail
City (City where store is located, displayed in the Vendor Information section)
Direct Marketing or
E-commerce
Customer Service Phone
NOTE: Not setting this configuration setting as indicated above may result in higher
rates paid by the Merchant to Paymentech.
Ecommerce
URL or Email Address
Page 217
 2009 Skipjack Financial Services
Skipjack Integration Guide
To view or change the Skipjack Merchant Account settings using the online Merchant Register:
1. Login to the Merchant Account at https://secure.skipjack.com using your account credentials
supplied by Skipjack Financial Services.
2. Click on the Preferences link to display the Vendor Preferences screen.
3. Set the values according to the table above appropriately for your business type.
Page 218
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix K: Orderstring Variables
The table below provides expanded descriptions, values, and examples for the Orderstring variables
introduced in the “Transaction Requests for Authorize and AuthorizeAPI” section.
Variable Name
Variable Description
Required /
Optional
Variable
Type
Min /
Max
Length
Data
Example
Level
Applies to Level I, Level II, and Level III transactions only and are included in the OrderString variable as described in
the “Transaction Requests for Authorize and AuthorizeAPI” section of this guide.
1
ItemNumber
SKU / Item Number
Required
Level I & III
AlphaNumeric
1/20
1
A102, 10MJ9OL0,
THX1138
Required
Level I & III
AlphaNumeric
and
comma
(,) and
dash (-)
1/120
1
Widget, 11LX
Widget
Do not use
"~`!@#$%^&*()_-+=
2
ItemDescription
Product Name
Do not use special
characters:
"~`!@#$%^&*()_-+=
3
ItemCost
Per Item Cost
Required
Level I & III
Numeric
and "."
4/8
1
1.00 or 1000.00
4
Quantity
Item Quantity
Numeric
1/4
1
2, 10, 20
5
Taxable
Indicates to apply the tax
rate to the order detail*
Required
Level I & III
Required
Level I & III
Alpha
1/1
1
N or Y only
6
Ignore AVS Switch
This entry must be
inserted as a “1” after the
double pipe || to override
the AVS settings set on
the Skipjack Account.
The Account settings
must be set to Accept
AVS Ignore flag when
sent.
Optional
Numeric
0/1
1
1
Applies to Level III transactions only and are included in the lvl3_orderstring variable as described in the “Transaction
Requests for Authorize and AuthorizeAPI” section of this guide.
7
UnitOfMeasure
Unit of Measure
(Standard)
Required
Level 3
Alphanumeric
0/3
3
BX
8
ItemDiscount
Item Discount
Required
Level 3
Numeric
0/9
3
0.50
9
ExtendedAmount
Extended (Shipping)
Amount
Required
Level 3
Numeric
0/9
3
0.00
10
CommodityCode
Commodity Code
(Standard)
Required
Level 3
Alphanumeric
0/4
3
ABC1
11
VatTaxAmount
VAT Tax Amount
Required
Level 3
Numeric
0/9
3
0.00
Page 219
 2009 Skipjack Financial Services
12
VatTaxRate
VAT Tax Rate
13
AlternateTaxAmount
Alternate Tax Amount
14
TaxRate
Tax Rate
15
TaxType
Tax Type
16
TaxAmount
Tax Amount
Skipjack Integration Guide
Required
Level 3
Required
Level 3
Required
Level 3
Required
Level 3
Numeric
0/4
3
1.0
Numeric
0/9
3
0.00
Numeric
0/4
3
0.0
Alphanumeric
0/4
3
TAX1
Required
Level 3
Numeric
0/9
3
0.00
NOTE 1: Not all Merchants will want to pass all Required name-value pairs when making an Authorization request. To pass
"Dummy Values” for some of the required fields see “Appendix L: Naming Conventions for “Dummy Values” in Required
Variables”.
NOTE 2: Only 2000 characters (total) are supported for the Orderstring.
Example: OrderString Variable Formatting
Itemnumber~ItemDescription~ItemCost~Quantity~Taxable~unitofmeasure~itemdiscount~extendeda
mount~commodity~vattaxamount~vattaxrate~taxrate~taxtype~taxamount~||
OrderString and lvl3orderstring variable Developer Notes
•
The inclusion of the Orderstring variable is required for all Level I transactions, but you may
use Dummy Values as described in "Appendix L: Naming Conventions for “Dummy Values” in
Required Variables” section of this guide.
•
Some Payment Processors have specific requirements and rules that must be followed
regarding the lvl3_orderstring variables so that the transaction will qualify for the Level III
interchange rates. Contact your Payment Processor for details regarding how to apply the
Level III variables according to their requirements.
Page 220
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix L: Naming Conventions for “Dummy Values” in
Required Variables
Some required variables may need to be configured with “Dummy Values” to satisfy the Skipjack
Transaction Network requirements for inclusion as required variables for some transaction methods.
In these instances, Skipjack Financial Services recommends using the naming conventions below to
help minimize overhead on the Skipjack Transaction Network. This will prevent increased transaction
processing times associated with using longer, arbitrary, values for each required variable fields.
Suggested Values for “Dummy Values” for Required Variables
Variable Name
Suggested Value
SJName
NA
Email
Any valid, existing, e-mail address.
StreetAddress
None
City
None
State
XX
ZipCode
00000
ShipToPhone
0000000000
OrderString
1~None~0.00~0~N~||
Methods Using the Dummy Variables
The above mentioned Dummy Variables values can be used in the variable fields for the following
transaction methods:
•
•
•
•
Authorize
AuthorizeAPI
Recurring Payments
Batch Upload methods.
Page 221
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix M: Transaction IDs, Audit IDs and the Transaction
Lifecycle
Transaction IDs are important transaction variables which are used in several transaction methods to
identify transaction records held within the Skipjack Transaction Network.
Originally the Transaction ID and the Audit ID are the same while the transaction is pending
settlement. However, once Settled, Transaction IDs change as the status of a transaction changes
throughout its lifecycle. For example, when a transaction transitions between the Authorized Pending
Settlement status to Settled, the Transaction ID changes.
Audit IDs are first created when the original transaction ID is created, however Audit IDs remain the
same for a transaction throughout its entire lifecycle as illustrated below. Audit IDs may be
displayed using the Reports Manager GUI and selecting the Audit ID option within a given report.
Audit IDs are also returned when a Change Transaction Status method is performed on a transaction.
Normally Audit IDs are used to track a group of transactions throughout its lifecycle, for auditing
purposes.
The table below shows the relationship between Audit ID and Transaction ID values as a transaction
changes state.
Transaction State
Audit ID
Transaction ID
Authorized Pending-Settlement
1
1
Archived Settled
1
2
Settled
1
3
Pending Credit
1
4
Credited
1
5
Development Notes on Audit IDs and Transaction IDs
•
Audit IDs can be viewed using the Skipjack Report Manager. For more information about using
the Report Manager see the Skipjack Merchant Reporting Guide.
Page 222
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix N: Test Cards Used with Development Accounts
The test credit cards (virtual test cards) listed below can be used with the Skipjack Test Accounts
for the Payment Processors listed for integration testing.
NOTE 1: Skipjack Merchant Services does not support testing within PRODUCTION
ACCOUNTS using these test card numbers! Use only LIVE cards for PRODUCTION TESTING.
NOTE 2: Use the Test Cards at your own risk. Usage is governed by the Test Card usage
policies of each respective Payment Processors/Card Issuer. Do not use these Test Cards for
any other purposes than is permitted by the respective Test Card usage policies.
Test Cards for TSYS and Global as Payment Processor
Test Account Number and Expiry Date
TSYS (Vital)
Global
4445999922225 (Visa)
Expiry Date: Any Future
Date
4003000123456781 (Visa)
5499990123456781 (MasterCard)
Expiry Date: Any Future Date
341111597242000 (American Express)
Expiry Date:12/06
Test AVS Street Number and Street
Name
8320
(Do not submit Street Name)
Any 4 Digits
Test AVS Zip Code
85284
303292010
CVV
999
123
CID =UNKNOWN with AMEX
Global will not reject an invalid CVV2
on a test account, however a return
code describing the CVV2 code
comparison will be returned.
Maximum Transaction Amount
$150.00
$10.99
Any amount above this is Declined.
Usage Notes
None
Global Test Accounts are not
automatically issued by Skipjack
Financial Services. Contact Skipjack
Technical Support for special setup
requirements.
Page 223
 2009 Skipjack Financial Services
Skipjack Integration Guide
Test Cards for Fifth Third Processing Solutions (FTPS) as Payment Processor
Visa
MasterCard
American Express
Discover
JCB
4445222299990007
Expiry Date: 12/14
Amount =$1.00
Expected Response:
APPROVAL
5444009999222205
Expiry Date: 12/14
Amount =$1.00
Expected Response:
APPROVAL
341111597242000
Expiry Date: 12/14
Amount:?
622126004598744
Expiry Date: 12/14
Amount:?
3530111333300000
Expiry Date: 12/14
Amount:?
4445222299990007
Expiry Date: 12/14
Amount =$1.02
Expected Response:
DECLINE
5444009999222205
Expiry Date: 12/14
Amount =$1.02
Expected Response:
DECLINE
Test AVS
Street
Number and
Street Name
and Street
Code
4445222299990007
Expiry Date: 12/15
ZIP Code” 45201
Street Name: Any
Amount =$0.00
Expected Response:
APPROVAL with
AVS=A
?
?
?
?
Test CVV2
4445222299990007
Expiry Date: 12/13
Amount =$1.22
CVV=154
Expected Response:
APPROVAL with
CVV2=M (Match)
?
?
?
?
Test
Account
Number and
Expiry Date
Page 224
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix O: Notes for Processing Level II and Level III Data
The following application development and integration details apply to processing Level III transaction
data.
NOTE: For more information about Level II and Level III transaction processing requirements, see the reference
document Skipjack Level II and III Transaction Overview Guide.
•
Level III transaction processing requires customized Skipjack Account settings and Merchant
Account Provider Account settings. Contact Skipjack Financial Services Customer Support if
you need to set up a new or existing Skipjack Account with Level III transaction processing
privileges.
•
Be sure to contact Skipjack Financial Services and your Merchant Account Provider early in
your development process to arrange for the necessary Skipjack account configuration
settings needed to process Level II and III transactions.
•
Required Level I data must be sent in each Level II or Level III transaction.
•
Level II and III are available for Retail, E-commerce, and MOTO (Mail Order, Telephone Order)
accounts on the Skipjack Transaction Network according to the Processors supported. Please
see the “Payment Processors Supported by Skipjack Financial Services” section for more
details about supported processors.
•
In order to process American Express and Discover transactions (Level I transactions only)
you require a separate Skipjack Account setup for these card types. Level II is supported for
American Express and Discover. Level III transactions are not supported for American
Express or Discover cards.
•
If you wish to process American Express or Discover card transactions (for Level I
transactions) you require a separate Skipjack Account for this purpose. Note that Level II and
III transactions are not supported for American Express (AMEX) or Discover
•
Only the Skipjack Authorize method applies to Level II and III. (Other Skipjack transaction
processing methods described in the Skipjack Integration Guide cannot apply to Level II or III
transactions.)
•
Level III orderstring details do not appear in the Reports, therefore Skipjack Financial Services
suggest always sending the Level I orderstring in addition to the Level III orderstring.
Page 225
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix P: Usage Notes for the Enhanced TSYS Credit Card
Processing Features
The following details apply to transactions processed using the enhanced functions when using TSYS
as the Payment Processor.
The enhancements to the TSYS credit card processing platform include the following features.
Feature
Description
Balance Inquiry
Allows the remaining balance of the card to be determined, for
Stored Value (Prepaid) credit cards only.
Card Authentication
(Also known as Preauthorization, Preauth, Zero
Dollar Authorization)
Allows the validation of card without affecting available credit limit
on the card.
Soft Indicators
Provides additional information about transactions which are
printed on the cardholder’s account statement.
Transaction Reversal
Allows previously processed credit card transactions to be
reversed.
Quasi- Cash
Permits cash-like transactions or transactions that are directly
convertible to cash (such as gaming chips and tokens) to be
processed.
Setting Skipjack Merchant Account Settings
All of the enhanced functions available when using TSYS as the Payment Processor require
appropriate settings in the Skipjack Merchant Account Settings to enable these features. For new
Skipjack accounts these settings should be properly configured by Skipjack Customer Support
representative.
However, for existing Skipjack Merchant Accounts users may need to set the required settings to
enable these features using the Merchant Register. This is permitted by users with the appropriate
account permissions. If you determine that you do not have the permissions required to edit the
Skipjack Account settings, please contact Skipjack Financial Services Customer Support for
assistance.
Page 226
 2009 Skipjack Financial Services
Skipjack Integration Guide
Changing the Merchant Account Setup Options to Use TYSY
Enhanced Functions
NOTE: This procedure requires users to have access rights in the Merchant Account to edit their account
settings. Contact Skipjack Financial Services Support if you require these changes and you do not have the
appropriate permissions.
1. Login to the Skipjack Merchant Account at https://secure.skipjack.com.
2. Enter the appropriate credentials into each form field. Ensure you are using the correct login
credentials for either the Live or Developer environments.
3. Select the Live or Developer radio button, as appropriate.
4. Use the Sales Summary and/or Vendor Summary screens to navigate to and select the
account you wish to change by using the radio button beside the account you wish to edit.
5. Select the Edit Account button on the bottom of the screen.
6. Scroll down the page to the section listing the features, as shown below. Select or de-select
the appropriate check-boxes to enable or disable the features as desired.
NOTE: You cannot use Card Authentication (also referred to as Preauth or Zero Dollar Authorization),
Reversal, or Balance Inquiry features when using Quasi-Cash functionality, otherwise errors will be
returned and the transactions will not be Approved.
7. Select the Submit button to make the changes take immediate effect.
Page 227
 2009 Skipjack Financial Services
Skipjack Integration Guide
Developer Notes about the TSYS Platform Enhanced Features
The following development and usage notes apply to the TSYS Enhanced features.
•
To use the enhanced features for TSYS credit card processing requires that they must first be
properly configured (enabled) in the Skipjack Merchant Account Register as described above
in the “Changing the Merchant Account Setup Options to Use TYSY Enhanced Functions”
section.
•
All transactions must be properly formatted and submitted using the AuthorizeAPI as described
in the “Authorize and AuthorizeAPI Methods” section.
•
Reversals are submitted by specifying the Unqtransactionid variable with the value equal to
the TransactionId of the transaction to be reversed. If you submit an invalid TransactionId you
will receive a szReturnCode = -108 error.
•
For Reversals the transaction amount used for the Reversal must be identical to the original
transaction amount otherwise the szReturnCode = -57 error will be returned.
•
When Reversals are successful the Approval Code of the Reversal is the same code as the
original authorization. If the Reversal is unsuccessful, then the Approval Code will be different
than the original authorization.
•
Soft Indicator (Soft Descriptor) information is displayed on the cardholder`s statement and in
abbreviated format in the response for the transaction. Commonly this field is used to display
the Doing Business As (DBA) name of the business to better identify the transactions to
customers and mitigate chargebacks and disputed transactions. Note that the Soft Indicator
data cannot be included in Skipjack Reports.
•
Balance Inquiry can be performed for Visa and MasterCard Prepaid credit cards only and can
be used to report the balances on Stored Value (Prepaid) credit cards. The return values
received will depend on the configuration settings and account permissions set by your
Payment Processor and/or credit card issuer.
•
Quasi-Cash is only supported for Visa, MasterCard, and Diners Club credit cards.
•
Quasi-Cash transaction processing requires a separate Skipjack Account and this feature
must be properly configured in the Skipjack Merchant Account Register.
•
Preauthorization (Zero Dollar Authorizations) allows a credit card to be validated without
incurring any charges to the card or impacting the card`s credit limit.
Page 228
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix Q: Usage Guidelines for Using Paymentech as
Payment Processor
The following usage details provide additional information that applies to transaction processing when
using Paymentech as your Payment Processor.
•
Post transactions only to the appropriate URLs. The URLs for Paymentech (and other
Advanced Processors) are different than the URLs used for posting transactions for many
other Payment Processors. For posting locations see the “Post-Back Locations for Authorize
Method” section for more details. (Paymentech posting URLs are shown with yellow fill in the
table).
•
The OrderDescription may be a maximum of 22 alphanumeric characters. See “Transaction
Requests for Authorize and AuthorizeAPI” section for a detailed description of the
OrderDescription variable.
•
OrderNumber can be a maximum of 22 alphanumeric characters and must be unique per
Settlement Batch, otherwise a Decline will be returned.
•
The Country variable is a Required variable for Authorize/Authorize API when using
Paymentech as your Payment Processor. For the permitted values for the Country and
rtCountry variables, see the “Appendix A: Permitted Country Code Values” section for usage
details.
•
The rtCountry variable is a Required variable for Add or Edit Recurring Payment methods
when using Paymentech as the Payment Processor. For the permitted values for the Country
and rtCountry variables, see “Appendix A: Permitted Country Code Values” section for usage
details.
•
Batch Close Time and Batch Processing Time on the Skipjack Account must be set to at
least 1 hour apart. By default, this is automatically set on your Skipjack Account by Skipjack
Financial Services and should not be changed. However, this setting may be changed by
those users (Merchant Accounts) who have the appropriate access privileges and this may be
required in special cases. Failure to adhere to this interval restriction may result in Settlement
issues.
Page 229
 2009 Skipjack Financial Services
Skipjack Integration Guide
Setting the Batch Settlement Preferences for Paymentech Salem
The Batch Close Time and Batch Process Time must be set to at least 1 hour apart when using
Paymentech Salem as your Payment Processor. Use the steps below to configure the Batch
Settlement Preferences for the Merchant Account.
1. Login to the Merchant Account at https://secure.skipjack.com and use the Skipjack Account
credentials supplied by Skipjack Financial Services.
2. Click on the Batch Settlement Preferences button located in the bottom section of the
Account Summary to display the Batch Settlement Preferences page, displayed below.
3. Use the appropriate drop-down controls to set the Batch Close Time and Batch Process Time
to be at least 2 hours apart to prevent duplicate transaction settlement and therefore charging
the Customer twice for a single transaction.
4. Select the Submit button to make the changes active.
5. Use your Web browser’s Back button to return to previous pages to continue working or select
the Exit link to log out of the Merchant Register.
NOTE: If you are not able to access Batch Settlement Preferences page, you do not
have the required account permissions and you must contact Skipjack Financial
Services Customer Support to have this configuration change applied to your Skipjack
Merchant Account.
Page 230
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix R: Skipjack Variable Mapping
Selectable Variables
The variables listed in the Variable Name column are available for use by your application and can be
posted to the Skipjack when the transaction is processed. These variables can be included in the email response and are accessible/visible via the Skipjack Merchant Register and Reporting tool in the
manner described below.
Required Fields
Optional Fields
User-Defined Fields
Variable Name
E-mail Template
Variable
Register Display
Reporting Selection
Reporting Output
If you are injecting
this variable:
Use this variable in
your email template
to display it in the
email:
The variable will be
displayed in the
register as the
following:
Select this field in the
reporting tool to
display the variable:
The variable will be
displayed in the
reporting tool as
follows:
sjName
<BillToName>
Customer
Customer Name
Customer Name
Email
<CustomerEmail>
(Bill to) Email Address
Customer Email
Customer Email
Streetaddress
<BillToAddress>
(Bill to) Customer
Customer Address
Customer Address
City
<BillToCity>
(Bill to) Customer
Customer City
Customer City
State
<BillToState>
(Bill to) Customer
Customer State
Customer State
Zipcode
<BillToZipCode>
(Bill to) Customer
Customer Zip Code
Customer Zip Code
Accountnumber
Not Available
Card Type / VISA
Credit Card Type /
Last 5 Digits
Credit Card Type /
Last 5 Digits
Month
Not Available
Not Available
Not Available
Not Available
Year
Not Available
Not Available
Not Available
Not Available
Serialnumber
Not Available
Not Available
Not Available
Not Available
Transactionamount
<TransactionAmount
>
Amount
Transaction Amount
Transaction Amount
Orderstring
<OrderString>,
<CreditString>
Order Detail
Item String Details
Item String Details
Shiptophone
<ShipToPhone>
(Ship to) Phone
Number
Ship-to Phone
Ship-to Phone
Ordernumber
<OrderNumber>
Order Number
Order Number
Order Number
Streetaddress2
<BillToAddress2>
Not Available
Customer Address
Customer Address
Streetaddress3
<BillToAddress3>
Not Available
Customer Address
Customer Address
Streetaddress4
<BillToAddress4>
Not Available
Customer Address
Customer Address
Country
<BillToCountry>
(Bill to) Country
Customer Country
Customer Country
Phone
<BillToPhone>
(Bill to) Phone
Number
Customer Phone
Customer Phone
Page 231
 2009 Skipjack Financial Services
Skipjack Integration Guide
Fax
<BillToFax>
Not Available
Customer Fax
Customer Fax
Shiptoname
<ShipToName>
(Ship to) Customer
Ship-to Name
Ship-to Name
Shiptostreetaddress
<ShipToAddress>
(Ship to) Customer
Ship-to Address
Ship-to Address
Shiptostreetaddress2
<ShipToAddress2>
Not Available
Ship-to Address
Ship-to Address
Shiptostreetaddress3
<ShipToAddress3>
Not Available
Ship-to Address
Ship-to Address
Shiptostreetaddress4
<ShipToAddress4>
Not Available
Ship-to Address
Ship-to Address
Shiptocity
<ShipToCity>
(Ship to) Customer
Ship-to City
Ship-to City
Shiptostate
<ShipToState>
(Ship to) Customer
Ship-to State
Ship-to State
Shiptozipcode
<ShipToZipCode>
(Ship to) Customer
Ship-to Zipcode
Ship-to Zipcode
Shiptocountry
<ShipToCountry>
(Ship to) Country
Ship-to Country
Ship-to Country
Shiptofax
<ShipToFax>
Not Available
Ship-to Fax
Ship-to Fax
Cvv2
Not Available
CVV2
CVV2 Status
CVV2 Status
Comment
<Comment>
Comment
Comment
Comment
udf1-udf30
<UserDefinedFields>
UDF1-UDF30
User Defined Fields
udf1-udf30
Variables Generated During Transaction Processing
The variables listed in the Variable Name column are generated dynamically by Skipjack when the
transaction is processed. These variables can be included in the e-mail response and are
accessible/visible via the Skipjack Merchant Register and Reporting tool in the manner described
below.
Variable Name
E-mail Template
Variable
Register Display
Reporting
Selection
Reporting Output
If this variable is
generated by
Skipjack:
Use this variable in
your email template
to display it in the
email:
The variable will be
displayed in the
register as the
following:
Select this field in
the reporting tool to
display the variable:
The variable will be
displayed in the
reporting tool as
follows:
Authorization Code
<AuthorizationNumbe
r>
Auth Code
Approval Code
Approval Code
Merchant Account #
Not Available
Account
Not Available
Not Available
Date and time of
Transaction
<TransactionDate>
Transaction Date
Transaction Date
Transaction Date
IP Address of
interface user
Not Available
IP Address
From Computer IP
From Computer IP
Status of the
transaction
<AuthorizationRespo
nse>
Status
Transaction Status
Transaction Status
State of the
transaction
Not Available
Not Available
Transaction State
Transaction State
Address Verification
results
<AuthorizationRespo
nse>
AVS
AVS Status
AVS Status
Merchant Name
<MerchantName>
Not Available
Not Available
Not Available
Page 232
 2009 Skipjack Financial Services
Skipjack Integration Guide
Merchant Phone
Number
<MerchantPhone>
Not Available
Not Available
Not Available
Merchant Email
<MerchantEmail>
Not Available
Not Available
Not Available
Audit ID
Not Available
Not Available
Audit ID
Audit ID
Transaction ID
<TransId>
Not Available
Transaction ID
Transaction ID
Invoice Number
Not Available
Not Available
Invoice Number
Invoice Number
Settlement Batch
Number
Not Available
Not Available
Batch Number
Batch Number
Sales Person Number
Not Available
Not Available
Sales Person
Number
Sales Person
Number
Commercial Card
Indicator
Not Available
Not Available
Commercial Card
Indicator
Commercial Card
Indicator
Amount (Adjustment)
Not Available
Not Available
Amount
(Adjustment)
Amount
(Adjustment)
Amount (Discount)
Not Available
Not Available
Amount (Discount)
Amount (Discount)
Amount (Net)
Not Available
Not Available
Amount (Net)
Amount (Net)
Amount (Original)
Not Available
Not Available
Amount (Original)
Amount (Original)
Amount (Shipping)
Not Available
Not Available
Amount (Shipping)
Amount (Shipping)
Safe Status
Not Available
Not Available
Safe Status
Safe Status
Purchase Order
Number
Not Available
Not Available
Purchase Order
Number
Purchase Order
Number
Transaction Info
Not Available
Not Available
Transaction Info
Transaction Info
Page 233
 2009 Skipjack Financial Services
Skipjack Integration Guide
Appendix S: Master Error Code Table
This table lists the error codes returned for all transactions types submitted to the Skipjack
Transaction Network.
szReturnCode applicable to Authorize/AuthorizeAPI
Value
Issue/Error Type
Reason and Suggested Remedial Action
1
Success
Valid data received by the Skipjack Transaction Network.
Authorization request was valid and successfully processed
by the Skipjack Transaction Network.
0
Communication Failure
Error in Request and Response at IP level.
Use the Get Transaction Status method to determine the
status for the previous transaction and retry transaction
request.
-1
Error in request
Data was not received intact by the Skipjack Transaction
Network.
Use the Get Transaction Status method to determine the
status for the previous transaction and retry transaction
request.
-35
Invalid credit card number
Credit card number does not comply with the Mod10 check or
the card number not within the BIN range for the card type
and the transaction was not processed by the Skipjack
Transaction Network.
Resubmit the transaction with a valid credit card number.
-37
Merchant Processor Unavailable
Skipjack Transaction Network is unable to communicate with
the Payment Processor.
Use the Get Transaction Status method to determine the
status for the previous transaction and retry transaction
request.
-39
Length or value of HTML Serial
Number
Invalid serial number.
Check HTML Serial Number length and that it is a correct and
valid number.
Confirm you are sending your transaction request to the
correct environment (Development or Production).
The Make Developer Serial Number a required field option
is selected for the Skipjack account but the Developer Serial
Number was not sent in the transaction request. .
-51
Length or value of zip code
The value or length for billing zip code is incorrect.
-52
Length or value in shipto zip code
The value or length for shipping zip code is incorrect.
Page 234
 2009 Skipjack Financial Services
Skipjack Integration Guide
-53
Length or value in expiration date
The value or length for credit card expiration month is
incorrect.
-54
Length or value of month or year of
credit card account number
The value or length of the month or year of the credit card
account number was incorrect.
-55
Length or value in streetaddress
The value or length or billing street address is incorrect.
-56
Length or value in
shiptostreetaddress
The value or length of the shipping address is incorrect.
-57
Length or value in transactionamount
The length of the transaction amount must be at least 3 digits
long (excluding the decimal place).
For TSYS PIN-debit only this error code is returned when any
amount other than the original transaction amount is
attempted for a Reversal.
-58
Length or value in Merchant Name
Merchant Name associated with Skipjack account is
misconfigured or invalid
-59
Length or value in Merchant Address
Merchant Address associated with Skipjack account is
misconfigured or invalid
-60
Length or value in Merchant State
Merchant State associated with Skipjack account is
misconfigured or invalid
-61
Error length of value in shipto state.
The value or length for shipping state/province is empty.
-62
Error length or value in order string
The value for length orderstring is empty.
-64
Error invalid phone number
The value for the phone number is incorrect.
-65
Error empty sjname
The value or length for billing name is empty.
-66
Error empty e-mail
The value or length for billing e-mail is empty.
-67
Error empty street address
The value or length for billing street address is empty.
-68
Error empty city
The value or length for billing city is empty.
-69
Error empty state
The value or length for billing state is empty.
-70
Empty zipcode
Zip Code field is empty.
-71
Empty ordernumber
Ordernumber field is empty.
-72
Empty accountnumber
Accountnumber field is empty
-73
Empty month
Month field is empty.
-74
Empty year
Year field is empty.
-75
Empty serialnumber
Serialnumber field is empty.
-76
Empty transactionamount
Transaction amount field is empty.
-77
Empty orderstring
Orderstring field is empty.
-78
Empty shiptophone
Shiptophone field is empty.
-79
Length or value sjname
The value or length for billing name is empty.
-80
Length shipto name
Error in the length or value of shiptophone.
-81
Length or value of Customer City
Error in the length or value of the Customer City .
-82
Length or value of state
The value or length for billing state is empty.
-83
Length or value shiptophone
The value or length for shipping phone is empty.
Page 235
 2009 Skipjack Financial Services
-84
Duplicate ordernumber
Skipjack Integration Guide
There is already an existing pending transaction in the
Skipjack Register sharing the posted Order Number.
This error code is returned only when the Reject duplicate
transactions based on order number option is enabled in
the Skipjack account.
-85
Airline leg info invalid
Airline leg field value is invalid or empty.
-86
Airline ticket info invalid
Airline ticket info field is invalid or empty
-87
Point of Sale check routing number
must be 9 numeric digits
Point of Sale check routing number is invalid or empty.
-88
Point of Sale check account number
missing or invalid
Point of Sale check account number is invalid or empty.
-89
Point of Sale check MICR missing or
invalid
Point of Sale check MICR invalid or empty.
-90
Point of Sale check number missing
or invalid
Point of Sale check number invalid or empty.
-91
CVV2 Invalid or empty
Make CVV a required field option is enabled in the Merchant
Account Setup interface but no CVV code was sent in the
transaction data.
Resubmit the transaction with the CVV variable in the request
string.
-92
Approval Code Invalid
Approval Code Invalid. Approval Code is a 6 digit code.
-93
Blind Credits Request Refused
Blind credit attempt failed.
Enable Allow Blind Credits option on the Skipjack account
and resubmit the transaction.
-94
Blind Credits Failed
option on the Skipjack account and resubmit the transaction.
-95
Voice Authorization Request
Refused
Voice Authorization option must be enabled on the Skipjack
Merchant Account.
-96
Voice Authorizations Failed
option on the Skipjack account and resubmit the transaction.
-97
Fraud Rejection
Violates Velocity settings set via the Preferences screen for
the Skipjack account.
Change the Fraud Settings values and resubmit the
transaction. C
-98
Invalid Discount Amount
Discount Amount must be 0 to 12 digits and include a
decimal.
-99
Point of Sale PIN Debit Pin Block
Debit-specific
-100
Point of Sale PIN Debit Invalid Key
Serial Number
Debit-specific
-101
Invalid Authentication Data
Data for Verified by Visa/MC Secure Code is invalid.
-102
Authentication Data Not Allowed
Reserved for future use.
-103
Point of Sale Check Invalid Birth
Date
Point of Sale check dateofbirth variable contains a birth date
in an incorrect format. Use MM/DD/YYYY format for this
variable.
Page 236
 2009 Skipjack Financial Services
Skipjack Integration Guide
-104
Point of Sale Check Invalid
Identification Type
Point of Sale check identificationtype variable contains an
identification type value which is invalid. Use the single digit
value where Social Security Number=1, Drivers License=2 for
this variable.
-105
Invalid trackdata
Track Data is in invalid format.
-106
Point of Sale Check Invalid Account
Type
Expected values are 0 or 1.
-107
Point of Sale PIN Debit Invalid
Sequence Number
The invoicenumber must be 3 digits long. This error indicates
an empty string or a string of more or less than three digits
was passed.
-108
Invalid Transaction ID
For TSYS PIN-based debit and TSYS credit card transactions
the Unqtransactionid is not valid. Resubmit transaction
using the correct Unqtransactionid.
-109
Invalid From Account Type
Expected values are 1 or 2.
-110
Point of Sale Error Invalid To
Account Type
Expected values are 1 or 2.
-112
Point of Sale Error Invalid Auth
Option
Options selected for account type are incorrect (must be in
the range 1 to 8) or incorrect for the protocol type.
-113
Point of Sale Error Transaction
Failed
The transaction was not processed correctly. Please freeze
the transaction and reprocess.
-114
Point of Sale Error Invalid Incoming
ECI
The ECI value being passed to Skipjack is invalid. Expected
values are 1,2,5,6,7.
-115
Point of Sale Check Invalid Check
Type
The check type is outside of the allowable range – it must be
1 to 5.
-116
Point of Sale Check Invalid Lane
Number
Point of Sale Check lane or cash register number is invalid.
Use a valid lane or cash register number that has been
configured in the Skipjack Merchant Account.
-117
Point of Sale Check Invalid Cashier
Number
The salespersonnumber must be less than 8 and greater 0.
-118
Invalid POST URL
The URL posted to is incorrect. Confirm URL that is being
posted and resubmit the transaction.
-119
General Error
Batch upload process failed for an unspecified reason.
-120
Invalid Record Count
Reserved for future use.
-121
Invalid file boundary
The end of file boundary was not detected by the batch file
upload process. This indicates that the transmission of the
batch file was interrupted.
-122
Not Allowed
This Skipjack account does not accept batch file uploads.
C
-123
Developer Serial Number Invalid
Reserved for future use.
-124
Invalid File type
The batchType request variable for a Batch File Upload
can be either 0 (authorization) or 1 (others). Any other value
returns this error.
-125
Invalid Debit Batch Number
Reserved for future use.
Page 237
 2009 Skipjack Financial Services
Skipjack Integration Guide
-126
Point of Sale Error Card
Authentication Not Allowed
Applies to those using TSYS as the Payment Processor.
Ensure that the Card Authentication check-box is selected
in the Skipjack Merchant Account settings screen to enable
this feature.
-127
Point of Sale Error Balance Inquiry
Applies to those using TSYS as the Payment Processor.
Ensure that the Balance Inquiry check-box is selected in the
Skipjack Merchant Account settings screen to enable this
feature.
-128
Point of Sale Error Reversal Not
Allowed
Applies to those using TSYS as the Payment Processor.
Ensure that the Reversal check-box is selected in the
Skipjack Merchant Account settings screen to enable this
feature.
szErrorCode Errors applicable to Change Status Method
0
Success
Change status request was successful.
-1
Invalid Command
Bad parameter passed OR Merchant Account not active OR
change status not allowed by protocol OR invalid permissions
to perform requested action OR Merchant Account does not
allow change status to be performed.
-2
Parameter Missing
Required parameter not sent.
-3
Failed retrieving response
No transaction was found to perform a change on OR Multiple
transactions were found OR the original transaction could not
be loaded OR the original transaction is frozen or archived
OR a Split Settle request was performed on a transaction that
was the result of a previous split settle request OR something
else bad happened to the request.
-4
Invalid Status
Merchant Account does not allow change status to be
performed.
-5
Failed reading security flags
Error loading merchant information to perform change status.
-6
Developer Serial number not found
The developer serial number passed was not recognized.
-7
Invalid Serial Number
The serial number passed was not recognized.
-8
Authorization Status Unknown;
Perform Get Status
The real time authorization performed during the change
status request resulted in an unexpected error. Please
perform a Get Transaction Status request to determine the
status of the request. (Only applies to Authorize, AuthorizeEx,
AuthorizeAdditional, and AuthorizeAdditionalEx requests).
-51
Invalid Amount
<Not used>
szErrorCode Errors applicable to Get Transaction Status Method
-1
Invalid Command
Request was successful.
-2
Parameter Missing
Required parameter not sent.
-3
Failed retrieving response
Error getting transaction status.
-4
Invalid Status
<Not used>
-5
Failed reading security flags
<Not used>
-6
Developer serial number not found
The developer serial number passed was not recognized.
-7
Invalid Serial Number
The serial number passed was not recognized.
Page 238
 2009 Skipjack Financial Services
Skipjack Integration Guide
szErrorCode Errors applicable to Add Recurring Payments Method
0
Success
Request was successful.
-1
Invalid Command
Merchant does not allow recurring payments.
-2
Parameter Missing
Required parameter not sent.
-3
Failed retrieving message
Error adding recurring payment.
-4
Invalid Status
<Not used>
-5
Failed reading security flags
<Not used>
-6
Developer Serial number not found
The developer serial number passed was not recognized.
-7
Invalid serial number
The serial number passed was not recognized.
-8
Expiration year is not 4 characters
Expiration year is not 4 characters.
-9
Credit card has expired
Credit card has expired.
-10
Invalid starting date
Invalid starting date.
-11
Failed Adding Recurring Payment
Merchant does not allow recurring payments OR Failed
Adding Recurring Payment.
-12
Invalid Recurring Payment frequency
Invalid Recurring Payment frequency.
-15
Failed
<Not used>
-16
Invalid expiration month
Invalid expiration month.
szErrorCode Errors applicable to Edit Recurring Payments Method
0
Success
Request was successful.
-1
Invalid Command
Merchant does not allow recurring payments.
-2
Parameter Missing
Required parameter not sent.
-3
Failed retrieving message
Error editing recurring payment.
-4
Invalid Status
<Not used>
-5
Failed reading security flags
<Not used>
-6
Developer Serial number not found
The developer serial number passed was not recognized.
-7
Invalid serial number
The serial number passed was not recognized.
-8
Expiration year is not 4 characters
Expiration year is not 4 characters.
-9
Credit card has expired
Credit card has expired.
-10
Invalid starting date
Invalid starting date.
-14
Failed editing of Recurring Payment
Failed editing of Recurring Payment.
-16
Invalid expiration month
Invalid expiration month.
szErrorCode Errors applicable to Delete Recurring Payments
0
Success
Request was successful.
-1
Invalid Command
Merchant does not allow recurring payments.
-2
Parameter Missing
Required parameter not sent.
-3
Failed retrieving message
Error deleting recurring payment.
-4
Invalid Status
<Not used>
-5
Failed reading security flags
<Not used>
Page 239
 2009 Skipjack Financial Services
Skipjack Integration Guide
-6
Developer Serial number not found
The developer serial number passed was not recognized.
-7
Invalid serial number
The serial number passed was not recognized.
-13
Failed Delete of Recurring Payment
Failed Delete of Recurring Payment.
-15
Failed
<Not used>
Page 240