Secure Payments Gateway API and Reference Guide

718 Pages·2004·2.73 MB·English

Payway Direct Engine
API Reference and
Guide v1.0

Payway Direct, Incorporated
Notices

This product or documentation or any associated documentation contains proprietary information that is protected by the copyrights
of Payway Direct, Inc and/or its suppliers. The information in this manual is subject to change without notice. NO PART OF THIS
MANUAL MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS, ELECTRONIC OR
MECHANICAL, INCLUDING PHOTOCOPYING AND RECORDING, FOR ANY PURPOSE OTHER THAN THE LICENSEE'S
PERSONAL USE WITHOUT PRIOR WRITTEN PERMISSION OF PAYWAY DIRECT, INC.

Limitation of liability

IN NO EVENT WILL PAYWAY DIRECT, INC., ITS SUPPLIERS, OR OTHER THIRD PARTIES MENTIONED IN THIS
DOCUMENT BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, THOSE
RESULTING FROM LOST PROFITS, LOST DATA OR BUSINESS INTERRUPTION) ARISING OUT OF THE USE,
INABILITY TO USE, OR THE RESULTS OF USE OF THE SOFTWARE DESCRIBED HEREIN, ANY WEBSITES REFERRED
TO IN THIS DOCUMENT, OR THE MATERIALS OR INFORMATION OR SERVICES CONTAINED AT ANY OR ALL SUCH
SITES, WHETHER BASED ON WARRANTY, CONTRACT, TORT OR ANY OTHER LEGAL THEORY AND WHETHER OR
NOT PAYWAY DIRECT, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IF YOUR USE OF THE
MATERIALS, INFORMATION OR SERVICES RESULTS IN THE NEED FOR SERVICING, REPAIR OR CORRECTION OF
EQUIPMENT OR DATA, YOU ASSUME ALL COSTS THEREOF.

Copyrights

The Payway Direct® software uses Expat-XML Parser Toolkit, which is subject only to the Mozilla Public License Version 1.1 (the
"License"), and the source code is available only under the terms of the License; you may not use the Expat-XML Parser Toolkit
except in compliance with the License. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
WARRANTY OF ANY KIND, either express or implied. See the License at http://www.mozilla.org/MPL/ for the specific language
governing rights and limitations under the License. The Original Code is Expat-XML Parser Toolkit, which is available at
http://www.jclark.com/xml/expat.html The Initial Developer of the Original Code is James Clark. Portions created by James Clark are
© 1998, 1999 James Clark. All Rights Reserved.

The Microsoft Windows version of the Payway Direct® software uses the Pthreads-Win32 - POSIX 1003 Threads Library for Win32,
© 1998, subject to the GNU Library General Public License, version 2. Source code for this library and the GNU Library General
Public License are included on the CD. This library is free software; you can redistribute it and/or modify it only under the terms of
the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your
option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General
Public License for more details. You should have received a copy of the GNU Library General Public License along with this library;
if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. This library provides
an implementation of PThreads based upon the POSIX 1003.1c-1995 (POSIX.1c) standard. Contributors are listed in the file
"MAINTAINERS" located at: ftp://sources.redhat.com/pub/pthreads-win32/sources/pthreads-snap-2000-09-08/"

The Payway Direct® software uses the IBM ICU 2.4 Program Copyright © 1995-2002, International Business Machines Corporation
and others. All Rights Reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that
both the above copyright notice(s) and this permission notice appear in supporting documentation.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use
or other dealings in this Software without prior written authorization of the copyright holder. The Payway Direct® software contains
BSAFE which is licensed to Payway Direct, Inc. by RSA Data Security, Inc. © 2000 RSA Data Security, Inc. All rights reserved.

Portions of this software are copyrighted by DataDirect Technologies, 1991-2003

Portions of this software are copyrighted by ClearCommerce Corporation, 2000-2004

The Payway Direct® software contains SSL Plus which is licensed to Payway Direct, Inc. by Consensus Development Corporation. ©
1997-2000 Consensus Development Corporation. All rights reserved. Portions are © 1997-1998 Consensus Development
Corporation, a wholly owned subsidiary of Certicom Corp. All rights reserved. Contains an implementation of NR signatures,
licensed under U.S. patent 5,600,725. Protected by U.S. patents 5,787,028; 4,745,568; 5,761.305. Patents pending.
The Payway Direct® software uses Flex © 1990 The Regents of the University of California. All rights reserved. This code is derived
from software contributed to Berkeley by Vern Paxson. Flex includes software developed by the University of California, Berkeley
and its contributors. The United States Government has rights in this work pursuant to contract no. DE-AC03-76SF00098 between the
United States Department of Energy and the University of California.

The Payway Direct® software uses RegExp, which was slightly modified by Anatoly Kardash. Payway Direct, Inc. is licensed to use
RegExp, as modified, under rights granted by Henry Spencer. © 1986 by University of Toronto. Written by Henry Spencer. Not
derived from licensed software.

The Payway Direct® software uses Microsoft Data Access Components (“MDAC”) © 1991-2000 Microsoft Corporation. All rights
reserved. Microsoft Corporation also requires that Payway Direct, Inc. provide the following notices regarding MDAC: Information
in this document, including URL and other Internet Web site references, is subject to change without notice and is provided for
informational purposes only. The entire risk of the use or results of the use of this document remains with the user, and Microsoft
Corporation makes no warranties, either express or implied. Unless otherwise noted, the example companies, organizations, products,
people, and events depicted herein are fictitious, and no association with any real company, organization, product, person, or event is
intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the
rights under copyright, no part of this document may be reproduced, stored in, or introduced into a retrieval system or transmitted in
any form, or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express
written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other
intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement
from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other
intellectual property. Microsoft, MS-DOS, Windows, Windows NT, ActiveX, Visual Studio, Visual C++, Visual FoxPro, and MSDN
are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries. The names of actual
companies and products mentioned herein may be the trademarks of their respective owners.

Copyright © 2000-2001 Quova, Inc. All rights reserved. All data and documentation (whether in hard copy or electronic form) are
subject to the agreement. Any use of the data or documentation must be pursuant to the agreement or authorized by Quova, Inc.

The Payway Direct® software uses ZIPsales™ Database Jr. (sales tax tables and zip code tables), which are licensed to Payway
Direct, Inc. by DPC Computers, Inc. ©2001 DPC Computers, Inc.

Trademarks

Payway Direct® is a service mark of Payway Direct, Inc.
ClearCommerce® and FraudShield® are registered trademarks and FraudAnalyzer™ is a trademark of ClearCommerce Corporation.
Adobe® and Acrobat® are registered trademarks and PostScript™ is a trademark of Adobe Systems Incorporated.
BSAFE® is a registered trademark of RSA Data Security, Inc.
EMANATE® is a registered trademark of SNMP Research International, Inc.
SSL Plus™ is a trademark of Consensus Development Corporation.
ZIPsales™ is a trademark of DPC Computers, Inc.
American Express® and Optima® are registered trademarks of American Express Company.
BarclaysSM is a service mark of Barclays Bank PLC.
Carte Blanche™ is a trademark and Diners Club® is a registered trademark of Diners Club International Ltd.
Discover® is a registered trademark of NOVUS Services, Inc.
enRoute™ is a trademark of Air Canada Corporation.
Federal Express® and FedEx® are registered trademarks of Federal Express Corporation.
First Data Merchant Services Corporation™ and FDMS™ are trademarks of First Data Merchant Services Corporation.
JCB™ is a trademark of JCB International Credit Card Co., Ltd.
MasterCard® is a registered trademark of MasterCard International Incorporated.
Paymentech™ is a trademark of Paymentech, Inc.
Solo® and Switch® are registered trademarks of Switch Card Services Ltd.
UPS® is a registered trademark of United Parcel Service of America, Inc.
Visa® and Electron® are registered trademarks of Visa International Service Association.
Vital® is a registered trademark and VirtualNet™ is a trademark of Vital Processing Services.
Other marks cited in this document are the property of their respective owners.

Notices

Licensees Outside of the United States: Some processors or product features described in this document might not be supported in
countries outside the United States. Consult your local Payway Direct, Inc. representative for information about the processors or
product features available in your area.

Fraud Protection: Fraud protection systems, such as those offered by Payway Direct, Inc. can help a fraud case manager better focus
investigative efforts by identifying which transactions exhibit traits similar to those that have been correlated with incidences of fraud
in the past. No fraud system can definitively determine whether any given transaction is, in fact, fraudulent. Therefore, fraud
protection systems can form only one part of a comprehensive business decision-making process that involves human oversight and
investigation of each transaction in question. The responsibility to instill such a review process lies solely with each individual
merchant and commerce service provider and not with Payway Direct, Inc.

Support

Payway Direct, Inc. is committed to the ongoing support of its products as documented in the license agreement.

If you need features or functionality that are not currently offered by Payway Direct® software or if you have questions about the
product or need assistance, contact Technical Support by phone at 1-800-982-4042 or by e-mail at
[email protected] or at the Payway Direct, Inc. web site www.paywaydirect.com
Documentation

The documentation for this product is also available in softcopy format on the installation media.
The softcopy documentation is provided in .pdf format, and may be viewed or printed using Adobe Acrobat Reader. If you do
not have Adobe Acrobat Reader installed on your system, you can download the correct version for your platform from the
following Web site:
http://www.adobe.com/prodindex/acrobat/readstep.html
Install Acrobat Reader 4.0 or later for best viewing results and print to a PostScript Level 2 (or higher) printer for best printing
results.
Refer to the Release Notes for late additions, corrections, and revisions to the documentation.

Payway Direct Engine API Reference and Guide

Contents

About This Manual xxi
Audience xxi
Contents xxi
Highlighting and Notes xxiv
Product Documentation xxv
Chapter 1. The Payway Direct Engine and the Document Hierarchy 1
Payway Direct Engine Overview 1
Digital Certificates and Encryption 2
User Authentication 2
Document Hierarchy Overview 4
Data Types 5
Document Types 6
EngineDocList and EngineDoc 7
ConfigDoc 9
OrderFormDoc 9
ReportDoc 10
Document Routing 10
Chapter 2. Payway Direct Engine API 13
C Payway Direct Engine API 14
Java Payway Direct Engine API 15
Differences between the C and Java APIs 15
Code Samples 16
Chapter 3. Payment Overview 17
Order Life Cycles 17
Credit Cards 18
Checks 19
Payway Direct Engine API Reference and Guide vii
Payer Authentication Support 19
Transaction Types 20
Primary 20
Secondary 21
Settlement 22
Miscellaneous 23
Transaction Statuses 23
Payment-Related Transaction Status 24
Settlement Transaction Status 25
Chapter 4. Implementing OrderFormDocs 29
Structure of Input Pre Auth and Auth Transactions 29
Minimum Pre Auth for Credit Cards 30
Minimum Pre Auth and Auth for Checks 33
FNMS ACH 33
Chase ACH 34
Paymentech Salem 36
PreAuth with Payer Authentication 36
CCPA Support 40
Periodic Billing Support 42
Partial Shipment Support 43
Delayed Delivery and Declined Transactions Support 43
Example Document 43
PreAuth with Address Verification Service 44
PreAuth with Card Verification Methods 45
PreAuth with an Order Item List 48
PreAuth with Level II Information 52
PreAuth with Level III Information 53
FDMS South Visa 54
FDMS South MasterCard 55
Output Fields 56
ID and Timestamp Fields 57
Calculated Fields 58
Payment Processor Responses 59
AVS and AAV+ Responses 59
CVM Responses 59
Processor Codes and Messages Fields 60
CPS and ICP Fields 62
viii Payway Direct Engine API Reference and Guide
Structure of Other Primary Transactions 62
Credit (Independent or New Transaction) 63
ForceInsertPreAuth and ForceInsertAuth 63
Structure of Secondary Transactions 64
PostAuth 65
Partial Shipment 66
Partial Reversal 66
Credit (Existing Transaction) 67
Void 67
RePreAuth and ReAuth 68
ForceUpdatePreAuth and ForceUpdateAuth 69
Structure of Settlement Transactions 69
Settle 70
RequestForResponse 73
UnlockSettlement 74 Structure of
Miscellaneous Transactions 74
PrePurchase 74
Chargeback 75
ReviewPendingUpdate 75
ReleaseIdPool 76
OrderFormDoc Code Samples 77
Auth C Code Sample 78
Auth Java Code Sample 82
PostAuth C Code Sample 86
PostAuth Java Code Sample 88
Void C Code Sample 90
Void Java Code Sample 92
Chapter 5. Periodic Billing 95
Externally-Managed Orders 96
Internally-Managed Orders 97
Periodic Billing Errors 99
Cancelling Periodic Billing Orders 99
Chapter 6. Fraud Detection 101
GuardianShield 101
FraudStop 104
Velocity Checks 105
Payway Direct Engine API Reference and Guide
Experian 105
Level 1 Billing and Level 2 Billing Fields 106
Level 1 Shipping and Level 2 Shipping Fields 108
Credit Card Verification 108
Chapter 7. Experian Risk Service 111
Experian Level 1 and Level 2 Billing Fields 112
Level 1 Shipping and Level 2 Shipping Fields 114
Credit Card Verification 116
Experian Results 117
Chapter 8. Digital Receipts 121
Digital Receipt E-mail Templates 122
Template Variables 124
Syntax 128
Using Digital Receipts 129
Chapter 9. Shipping Calculator 131
Carrier Characteristics 131
Shipping Zones 132
Freight Algorithms 132
OrderFormDoc Structure 133
Chapter 10. Tax Calculator 135
Taxing an Entire Order 135
Taxing Individual Items 137
Implementation Notes 139
Code Samples 139
C Code Sample 140
Java Code Sample 143
Chapter 11. Using ConfigDocs 147
Required Fields 148
Add 148
Update 149
Get 150
Delete 152
Routing Information 152
Payway Direct Engine API Reference and Guide