TM Merchant/400 User's Guide Version 1.2 COPYRIGHT c 1997 I/NET, INC. Revision A Copyright c 1997 I/NET, Inc. All Rights Reserved. No part of this book may be reproduced in any form or by any means, electronic or mechanical, including photocopying without written permission from I/NET, Inc. Merchant/400 is a trademark of I/NET, Inc. Other brand and product names are trademarks or registered trademarks of their respective holders. Merchant/400 User Manual, Version 1.2 Table o Table of Contents 1. GETTING STARTED ........................................6 1.1 INSTALLATION ........................................7 1.1.1Installing Merchant/400 ...........................7 1.1.2Objects Installed .................................8 1.2 SETTING THE FEATURE ACTIVATION KEY .................10 1.3 VIEWING MERCHANT/400 DOCUMENTATION FROM A BROWSER ..11 1.3.1Accessing Document Files Directly ................11 1.3.2Accessing Documentation through Web Server/400 and Commerce Server/400 ...................................11 2. GETTING SETUP AS AN INTERNET MERCHANT .................13 2.1 GETTING SET UP AS AN INTERNET MERCHANT .............14 2.1.1So, You Want to do Business on the Internet ......14 2.1.2Partner Host Companies That Provide the Link .....14 2.2 THE PROCESSING CENTER AND YOUR BANK ................16 2.2.1The Beginning of Becoming an Internet Merchant ...16 2.2.2What You Will Need to Register With a Card Processor .............................................16 2.3 CREDIT CARD NETWORK ................................18 2.3.1A Credit Card Transaction House for the World Wide Web 18 2.3.2Credit Card Network Advertised Features and Benefits ..............................................18 2.4 HOLONET IAT ........................................20 2.4.1Transparent Processing for Credit Card Transactions20 2.5 ANACOM COMMUNICATIONS, INC. ........................21 2.5.1Payment Solutions for Internet Merchants Worldwide21 2.5.2Anacom Communications Advertised Features and Benefits ..............................................21 2.6 DATACASH LTD. ......................................23 2.6.1Multi-Currency Payment Solutions for Global Internet Merchants ....................................23 2.6.2DataCash Advertised Features and Benefits ........23 2.7 THE VIRTUAL CREDIT CARD TERMINAL ...................25 2.7.1The Connection to the Card Processor .............25 2.8 YOUR MERCHANT ID AND PASSWORD ......................26 2.8.1Your Keys to Internet Merchant Services ..........26 2.9 HOW IT ALL FITS TOGETHER ...........................27 2.9.1The Steps to Take to Become an Internet Merchant .27 2.10 USING MERCHANT/400 WITH NET.COMMERCE ...............28 2.10.1 ......................................Introduction 28 2.10.2Functionality Provided by the Merchant/400 do_payment Interface 2.10.3Configuring the Merchant/400 Objects for Use with Net.Commerce 2.10.4 Creating Your Own API - NCSAMPLE.C and NCSAMPLE2.C 33 2.11 CONFIGURING MERCHANT/400 OBJECTS FOR USE WITH NET.COMMERCE VERSION 2 ..................................35 2.11.1Activating the Customized do_payment API in Net.Commerce versio 2.11.2Activating the Customized Net.Data macros in Net.Commerce 36 Page 3 Merchant/400 User Manual, Version 1.2 Table o 2.12 CONFIGURING MERCHANT/400 OBJECTS FOR USE WITH NET.COMMERCE VERSION 3.2 ................................38 2.12.1Activating the Customized do_payment API in Net.Commerce versio 2.12.2Activating the Customized Net.Data macros in Net.Commerce 39 3. USING MERCHANT/400 ....................................42 3.1 USING THE MERCHANT/400 API .........................43 3.1.1Introduction .....................................43 3.1.2Files Provided to Aid your Development Effort ....43 3.2 WHAT IS A MERCHANT SERVER? .........................45 3.2.1A Way to do Business Over the Internet ...........45 3.2.2The Process ......................................45 3.3 USING THE MERCHANT/400 API IN AN ILE PROGRAM .......47 3.3.1Introduction .....................................47 3.3.2The ILE Call to Execute the API ..................47 3.4 USING THE MERCHANT/400 API IN AN OPM PROGRAM .......50 3.4.1Introduction .....................................50 3.4.2The OPM Program to Call to Execute the API .......50 3.5 INPUT AND OUTPUT FORMATS ...........................52 3.5.1How to Exchange Data With the API ................52 3.6 ERROR CONDITIONS ...................................63 3.6.1What to Expect in the Completion Indicator (plResultSuccess) Parameter ...........................63 3.6.2plResultSuccess Values. ..........................63 3.7 REQUIRED INFORMATION ...............................68 3.7.1Minimum Data to Send to the API ..................68 3.8 WHAT HAPPENS - TRANSMISSION METHODS ................78 3.8.1The lTransmitMethod / Transmission Method Parameter is the Key ............................................78 4. THE I/NET STORE - A SAMPLE APPLICATION ................84 4.1 THE I/NET STORE - A SAMPLE APPLICATION .............85 4.1.1Introduction .....................................85 4.1.2Store Screens ....................................85 4.2 CONFIGURATION ......................................88 4.2.1Introduction .....................................88 4.2.2Running the Sample Store (for Testing Only) ......88 4.2.3Configuring the Sample Store for a Production Environment ...........................................89 4.3 THE STORE DATABASE .................................92 4.3.1Global Configuration Physical File ...............92 4.3.2Product Description Physical File ................95 4.3.3Customer Order Physical File .....................96 4.3.4Customer Order Item Physical File ................99 4.3.5The Order Identifier Control Physical File ......100 4.3.6Net.Commerce Order Information Physical File ....100 4.4 EDITING THE STORE HEADERS AND FOOTERS .............103 4.4.1Customizing How the Store Looks .................103 4.5 THE STORE MESSAGE FILE ............................105 4.5.1Store Label Text and Messages ...................105 4.5.2Message Groups ..................................105 4.6 HOW THE API FITS IN ...............................112 Page 4 Merchant/400 User Manual, Version 1.2 Table o 4.6.1Using the API ...................................112 4.7 COOKIES ...........................................114 4.7.1What Is a Cookie? ...............................114 4.7.2Examples of Using Cookies .......................114 4.7.3Advantages and Disadvantages of Using Cookies ...115 5. INDEX ................................................116 Page 5 Merchant/400 User Manual, Version 1.2 1.0 Get 1. Getting Started Page 6 Merchant/400 User Manual, Version 1.2 1.0 Get 1.1 Installation 1.1.1 Installing Merchant/400 1.1.1.1 Important Pre-Installation Instructions Version 1.0 or greater of Commerce Server/400 (http://www.inetmi.com/products/webserv/webinfo.sht) must be installed on the system before installing Merchant/400 Version 1.0, 1.1 or 1.2. In addition, the following PTFs must also be installed: . Commerce Server/400 version 1.0C, or PTF number COM100002 (or greater) for Commerce Server/400 version 1.0, 1.0A, or 1.0B . PTF number WWW130012 for Web Server/400 version 1.3 If Merchant/400 version 1.1 was used in conjunction with Net.Commerce, special care should be taken to migrate existing data to the new format for the MCNINFP file (Net.Commerce Order Information Physical File on page 100). Since the file has changed (to include the DataCash order reference number and credit card start date / issue code fields) it is important to re-duplicate the file using the instructions on the Using Net.Commerce (Configuring the Merchant/400 Objects for Use with Net.Commerce on page 31) page. Do not forget to retain your historical data by renaming the original files (using RNMOBJ) and copying the data (using CPYF FMTOPT(*MAP *DROP)) to the newly installed and duplicated files. 1.1.1.2 Installing Merchant/400 requires the following steps: 1.Sign on to your AS/400 as QSECOFR or another user profile with a user class of *SECOFR. Special authorities are required to successfully install Merchant/400 objects (Objects Installed on page 8). 2.End all currently running Web servers with the ENDWWW command. Ensure that no product commands or menus are running. Also ensure that the Merchant/400 API is not currently being called by another job (this applies to product re-install only). Use the WRKACTJOB command to verify that there are no servers, commands, or other jobs running that may be executing the API. 3.Run the system command LODRUN to install Merchant/400 from the supplied product tape. Note: Prompt the command to change the tape device if the default is not appropriate. Page 7 Merchant/400 User Manual, Version 1.2 1.0 Get The install should take approximately 2 to 15 minutes, depending on the tape device and AS/400 model (NOTE: RISC AS/400s may take longer if not using a RISC installation tape due to the extra time it takes to convert IMPI programs to RISC programs). The install program displays a message when it is finished that the install was successful. If any problems occur during the install: 1. Check the joblog to determine the cause of the error. 2. Correct the problem, if possible. 3. Re-run the installation command. 4. If problems persist, please contact support. 1.1.2 Objects Installed The following objects were created/restored on the AS/400 by the installation program: . Merchant/400 objects were restored to the Web server's product library (WWWSERVER). . A directory named WWWServ was restored into the root of the IFS file system when Commerce Server/400 was installed. WWWServ contains many other directories and stream files that are used by Web Server/400 or Commerce Server/400. Merchant/400 publications were restored into the WWWServ/WebDocs/Shipped/Pubs/Merch400 directory. . Documents for the sample I/NET store application were restored into the /WWWServ/WebDocs/Shipped/Merchant directory. . The library WWWMRCH was restored. WWWMRCH contains the sample I/NET Store application that is used to demonstrate how the API functions. Don't forget to add this library to the list of Script Libraries (with the ADDWWWSCPL command) before attempting to run the sample application (section 4.1 on page 85). Important note: Merchant/400's sample content and publications will always be shipped in the Shipped directory. Users should not place content in this directory for it may be deleted or over-written in the future. In addition, the sample I/NET Store application will always be installed into the WWWMRCH library and the /WWWServ/WebDocs/Shipped/Merchant directory. The contents of these areas should be duplicated by the user to another library and directory for actual use, as they may be deleted or over-written in the future. Page 8 Merchant/400 User Manual, Version 1.2 1.0 Get Page 9 Merchant/400 User Manual, Version 1.2 1.0 Get 1.2 Setting the Feature Activation Key Merchant/400 uses the activation code facilities built into Commerce Server/400 to set and evaluate the special code provided for the product. If you are reading this documentation online (directly through a network drive), you may want to start the server in order to get access to the links pointed to by these documentation files. Enter the activation code provided to you by your supplier with the product tape the next time you use STRWWW to start the server. The activation code dictates which installed I/NET products can be used. As such, the code provided to you must reflect every product you intend to run when starting the servers. Please contact your supplier if you did not receive an activation code or your activation code does not work. Page 10 Merchant/400 User Manual, Version 1.2 1.0 Get 1.3 Viewing Merchant/400 Documentation from a Browser All of the documentation is written in HTML (Hyper Text Markup Language) which will allow you to view it through a Web browser in one of two ways: 1.3.1 Accessing Document Files Directly Connect to the AS/400 through a network drive and use a web browser that is written to work with Microsoft Windows or OS/2. Upon installation, the Merchant/400 user guide documentation is located in the directory /WWWServ/WebDocs/Shipped/Pubs/Merch400. Most web browsers have the ability to load and view HTML files directly from a disk. Therefore, if your browser has this ability you can load the files through this means. The Client Access/400 for Windows 3.1, Client Access/400 for Windows 95, or Client Access/400 Optimized for OS/2 software packages allow you to connect to the IFS Root file system through a network drive definition. In order to reach the necessary drive, you can either connect a drive directly to the /WWWServ/WebDocs/Shipped/Pubs/Merch400 directory or you can connect to the ROOT of the IFS file system and work your way through the path (/WWWServ/WebDocs/Shipped/Pubs/Merch400) to reach the documentation. Since the documentation is an HTML marked up document, there are many files which make up the entire documentation. The base document is named usrguide.htm. Access this file to start at the beginning of the document. 1.3.2 Accessing Documentation through Web Server/400 and Commerce Server/400 Once the server is started, the documentation is available through the server. Upon installation, the Merchant/400 user guide documentation is located in the directory /WWWServ/WebDocs/Shipped/Pubs/Merch400. If the server is started with the shipped configuration the documentation can be accessed through the following URLs: /Shipped/Pubs/Merch400/ or /Shipped/Pubs/Merch400/usrguide.htm Page 11 Merchant/400 User Manual, Version 1.2 1.0 Get Page 12 Merchant/400 User Manual, Version 1.2 2.0 Get 2. Getting Setup as an Internet Merchant Page 13 Merchant/400 User Manual, Version 1.2 2.0 Get 2.1 Getting Set Up as an Internet Merchant 2.1.1 So, You Want to do Business on the Internet Transacting business over the Internet can be straightforward and efficient, but you need to set up accounts with partner processing agencies to make it all work. As an Internet merchant, you have a number of options available to you as you approach these partner alliances. Which options you select depend upon the links you wish to make when communicating with the processing center or acquirer (section 2.2 on page 16) while executing a credit card transaction. 2.1.2 Partner Host Companies That Provide the Link Credit Card Network (section 2.3 on page 18) provides processing services for credit card transactions, both in an automated fashion via Merchant/400 and Holonet IAT, and through a manual entry program for special case transactions. Credit Card Network can also provide "one stop" registration to create your Merchant account with Credit Card Network, Holonet IAT, and a credit card processor. Anacom Communications, Inc. (section 2.5 on page 21) allows for simple, low cost credit card processing. Anacom also supports merchants who do Internet business outside of the United States. Anacom also has a referral service to assist you in setting up a merchant account with a card processor. Holonet IAT (section 2.4 on page 20) specializes in Internet communications and may be used to link to Credit Card Network, Anacom Communications, or other services. If desired, Holonet can assist with the sequential submission of transactions to multiple services when it is difficult to complete a transaction because of network or system failures. For example, Holonet may automatically submit a transaction to Anacom Communications if they are unable to connect to Credit Card Network to complete it. DataCash Ltd. (section 2.6 on page 23) allows for simple, low cost credit card processing. DataCash specializes in supporting merchants who do Internet business outside of the United States and who process transactions in multiple currencies. Each of these companies provides varying products that can assist you, the merchant, when processing a credit card transaction over the Internet. Each of them provides secure connections, using the SSL encryption method for all Page 14 Merchant/400 User Manual, Version 1.2 2.0 Get transmissions originated from Merchant/400. This is also not intended to be an all-inclusive list and I/NET does not recommend any of these companies over the others, nor over other agencies that are not yet included here. The choice of a partner agency is dependent on the features and options you wish to employ as an Internet Merchant. The topic How It All Fits Together (section 2.9 on page 27) can assist you in the steps to create the accounts necessary to do business on the Internet. Page 15 Merchant/400 User Manual, Version 1.2 2.0 Get 2.2 The Processing Center and Your Bank 2.2.1 The Beginning of Becoming an Internet Merchant The process of selecting a credit card processor (sometimes referred to as a card acquirer or acquiring bank or institution) usually begins with contacting your financial institution. It should be able to provide you with the names of two or three providers with which they are familiar and have an established business relationship. If they are unable to provide you with the names of providers, a large regional financial institution in your area should be able to do so. The actual selection should begin with your financial institution's referral. Remember that the relationship between the financial institution and the credit processor is critical to your receiving prompt and accurate deposits and detailed transaction reporting. Since this operation goes on behind the scenes, it is critical that there is no reason for your customers to feel uncomfortable with using the Internet to transact business. This behind the scenes processing must be seamless and unobtrusive to your customers. Your selection of a processor should be made with the same criteria you use to establish any professional relationship. It must "feel right," as you will be working closely with the organization in establishing the processing procedures. After the process has been established you will probably not have very much interaction with this organization except for transaction reporting. 2.2.2 What You Will Need to Register With a Card Processor The credit card processing company will need background information about your company, such as: . The business's legal name . Type of organization, i.e., corporation, etc. . Bank relationship information . How long the organization has been in business . Whether your premises are owned or leased . Credit references . Credit card refund policies . Type of products you will be selling by credit card . Ownership information They will also require a review of other background information such as recent financial statements, your marketing plan, and possibly your website (if you have one). Page 16 Merchant/400 User Manual, Version 1.2 2.0 Get They may insist on visiting your place of business and reviewing your business environment. You can expect to pay an application fee to process your application. Once it is approved you can anticipate doing business immediately. Credit card processing fees vary by the volume of business you transact and the dollar amount of these transactions. You will pay a set percentage of each sale in addition to an amount per transaction. You can elect to receive weekly or monthly statements that detail the history of your activity. Part of the process of "signing up" with a partner processing agency will be to provide them the terminal identifier (section 2.7 on page 25) for your "virtual" terminal that has been assigned by the card processor. It is important to request this identifier when working with the card processor and keep it with your processor account information for reference when contacting partner agencies. Page 17 Merchant/400 User Manual, Version 1.2 2.0 Get 2.3 Credit Card Network 2.3.1 A Credit Card Transaction House for the World Wide Web Credit Card Network is affiliated with many credit card processing centers, making it easy for you, the merchant, to do credit card authorization and transaction consummation over the Internet. You can get an account set up with Credit Card Network by completing the secure Sign-Up form (https://www.creditnet.com/merchant/ccn-inet.html) for I/NET customers at their web site or by requesting information via their Response form (https://www.creditnet.com/merchant/ccncall3.html). You will need to have information about your company, as well as your bank and credit card processor, available for entry in the form. You will also want to have some ideas for a username (merchant name) and password. Once you have a merchant account set up, Credit Card Network has support available for you to process your credit card transactions. This can be done via the Merchant/400 API or the secure Credit Card Network Manual processing screen. 2.3.2 Credit Card Network Advertised Features and Benefits . On-line realtime credit card authorizations. Processing takes less than 45 seconds in most cases . Accepts many of the major credit cards . Low transaction fee which is in addition to the bank interchange rate. . Money in your checking account in 48 hours . Manual processing screen for other orders and transactions . Daily transaction report for each merchant in password protected directory . No minimum sale. No charge to customers/cardholders. No charge for denials. . Verifone terminal not required . ICVerify software not required . CyberCash not required For questions or comments about Credit Card Network, call (206)287-1794, write to ccnetwork@creditnet.com (mailto:ccnetwork@creditnet.com), or visit their web page (http://www.creditnet.com). Page 18 Merchant/400 User Manual, Version 1.2 2.0 Get Page 19 Merchant/400 User Manual, Version 1.2 2.0 Get 2.4 Holonet IAT 2.4.1 Transparent Processing for Credit Card Transactions Holonet IAT is directly associated with Credit Card Network, Anacom Communications, and other credit card processing companies. This gives you, the merchant, the flexibility to process your transactions with one of many different organizations, depending on the circumstances of the transaction and the parameters set by your customer. Transmissions to Holonet via the Merchant/400 API are automatically routed, based on parameters you supply and your Holonet user account, to the proper destination with the transaction information securely delivered for processing. And it is all completed over the Internet. There are a couple of different ways to set up an account with Holonet IAT. Simply creating a "transparent processing" account with Credit Card Network (section 2.3 on page 18) is one. By specifying that you wish to work through Holonet, an account will automatically be created for you with the same attributes as your Credit Card Network account. Holonet IAT is also an Internet Service Provider. If you wish to make your connection to the Internet directly via them, you can set up an account by calling Holonet at (510)704-0160, or you can get additional information at their Dedicated IP Access (http://www.holonet.net/holonet/dedicated.html) page. Once you have an account set up, Holonet IAT will be almost transparent as you process your credit card transactions. For questions or comments about Holonet IAT, call (510)704- 0160, write to info@holonet.net (mailto:info@holonet.net), or visit their web page (http://www.holonet.net). Page 20 Merchant/400 User Manual, Version 1.2 2.0 Get 2.5 Anacom Communications, Inc. 2.5.1 Payment Solutions for Internet Merchants Worldwide Anacom Communications, through their Secure PayTM program, promotes Internet Commerce by providing low cost order processing and payment solutions. You can set up an account with Anacom by completing the secure Application form (https://www.anacom.com/forms/secforms/secure_f.htm?secure=s ecurepayb&application=Merchant400) at their web site or by receiving information at their Credit Card Payment Services (http://www.anacom.com/payment.htm) page. You will need to have information about your company, as well as your bank and credit card processor, available for entry in the form. You will also want to have some ideas for a username (merchant name) and password. Make sure to reference that you are a Merchant/400 user in the comments area of the application form as well. They also provide a referral service to assist you in setting up a merchant account. You can find it at their Merchant Account Enrollment (http://www.anacom.com/merchant.htm) page. Once you have a Merchant account set up, Anacom has support available for you to process your credit card transactions. This can be done via the Merchant/400 API or a secure Anacom Manual processing screen. 2.5.2 Anacom Communications Advertised Features and Benefits . Visa, MasterCard, American Express, Discover, and other cards are accepted. No software "wallet," "e-cash" or membership needed as required by other services. . Ability to charge or authorize / reserve amounts based on a "sale" or "book and ship" transaction type (Transaction Type on page 53) method. . No need to change servers or your hosting service. . Payment information is encrypted and secured through a link to Anacom's commerce server from your web pages, providing confidence to your customers to pay on-line. . E-mail containing the order information is sent to you when an order is placed, or can be retained on Anacom's server for retrieval at your convenience. . Referral resource available to assist you in arranging for a merchant account. Page 21 Merchant/400 User Manual, Version 1.2 2.0 Get For questions or comments about Anacom Communications, call (972)304-5012, write to questions@anacom.com (mailto:questions@anacom.com), or visit their web page (http://www.anacom.com). Page 22 Merchant/400 User Manual, Version 1.2 2.0 Get 2.6 DataCash Ltd. 2.6.1 Multi-Currency Payment Solutions for Global Internet Merchants The DataCash Transaction.raw plain-text process is a very simple interface to the DataCash clearing system. It is a proprietary gateway method that runs on the DataCash web server. Parameters are passed from the Merchant/400 API straight to the script without the intermediary of an HTML form. Results are returned in plain text with no formatting, ready to be parsed by Merchant/400 for return to the Merchant's application. You can set up an account with DataCash by completing the secure Application form (https://www.datacash.com/stronghold/datacash_application_fo rm.htm) at their web site or by receiving information at their Application & Software (http://www.datacash.com/stronghold/application.htm) page. You will need to have information about your company, as well as your bank and the acquiring bank you have selected, available for entry in the form. You will also want to have some ideas about the currency requirements of your application. Make sure to select I/NET in the reseller field and reference that you are a Merchant/400 user in the comments area of the application form as well. 2.6.2 DataCash Advertised Features and Benefits . Visa, MasterCard/EuroCard, American Express, JCB, Switch, Solo, and other cards are accepted. . Ability to charge or pre-authorize / reserve amounts based on a "sale" or "book and ship" transaction type (Transaction Type on page 57) method. . Officially approved by and permanently connected to many Acquiring Banks, including NatWest Streamline, Girobank, American Express, Barclays Merchant Services, Royal Bank of Scotland. All transactions are authorized, confirmed or rejected in real time. . DataCash is a Multi-Currency system. You are not only able to trade in more than 150 currencies, you are also able to have the funds credited to your account in one of 17 currencies. For questions or comments about DataCash, call (in the UK) +44 171 820 7733, write to info@datacash.com (mailto:info@datacash.com), or visit their web page (http://www.datacash.com). Page 23 Merchant/400 User Manual, Version 1.2 2.0 Get Page 24 Merchant/400 User Manual, Version 1.2 2.0 Get 2.7 The Virtual Credit Card Terminal 2.7.1 The Connection to the Card Processor You are probably already familiar with a credit card terminal - the terminal or "swipe" machine at your local restaurant, market, or hotel. This machine is a direct connection to your card processor and contains an internal serial number that uniquely identifies the terminal to the card processor when a connection is made. This identifier links the terminal, via the processor's records, to your processor account. When working in a "virtual" or computer-to-computer environment, some form of unique identification must accompany any transaction that is sent to the card processor. This, again, is how the processor knows where the transaction originated and that it is being executed for your account. You will receive other identification information from the card processor (section 2.2 on page 16) when you set up your account. These "client numbers" help to identify you to the processor, but are not the same as the terminal identification number. The reason for having both is that the client identification is usually unique to a customer and credit card type - hence, you may receive multiple client numbers, one for each credit card type that you wish to accept. At the same time, you may have more than one card terminal - one at your front desk, one in the back office, and the new virtual terminal you are creating for Internet processing. Each of these will also have a unique identifier. Part of the process of "signing up" with a partner processing agency will be to provide them the terminal identifier for your "virtual" terminal that was assigned by the card processor. It is important to request and keep this identifier with your processor account information. Page 25 Merchant/400 User Manual, Version 1.2 2.0 Get 2.8 Your Merchant ID and Password 2.8.1 Your Keys to Internet Merchant Services Now that you have created accounts with a credit card processor (section 2.2 on page 16) and partner processing agencies to link you to the card processor, you have chosen or received a merchant ID, a merchant name, and a merchant password. These are the links you need to identify your transaction and the accounts you wish to use for a Merchant/400 transmission. The merchant ID was assigned by the credit card processor and is the link to your account there. You may have received multiple merchant IDs, each relative to the credit cards that you will accept and process. This ID is used internally by the credit card processor and is not needed by the Merchant/400 API to execute a credit card transaction. The virtual terminal identification (section 2.7 on page 25), received from the card processor, will be used by the partner processing agency to link your merchant name with the merchant ID. The merchant name and password were assigned by your chosen partner processing agency. These are used to log on to their service to pass credit card transactions to the card processor. These are unique to your organization and should be kept in confidence, as they can be used not only to complete a credit card transaction, but also to make debit adjustments to your merchant account. Both entries are SSL encrypted (with the customer order and credit card information) when transmitted to the partner processing agency. Page 26 Merchant/400 User Manual, Version 1.2 2.0 Get 2.9 How It All Fits Together 2.9.1 The Steps to Take to Become an Internet Merchant 1.Get set up with a bank - you must have a savings or checking account. 2.Contact a Credit Card Processor (section 2.2 on page 16). Receive a Merchant Identification number and a virtual terminal ID to process transactions electronically. 3.Sign up with Credit Card Network (section 2.3 on page 18), Anacom Communications (section 2.5 on page 21), DataCash (section 2.6 on page 23), or another transaction processing company. Register a Merchant ID, username and password (section 2.8 on page 26) for access. They will also need to know the virtual terminal ID (section 2.7 on page 25) assigned by your card processor. 4.If necessary, register with Holonet IAT (section 2.4 on page 20) to pass transactions to the appropriate transaction processing company. This may also involve a specialized configuration for sequencing or other circumstances. 5.Program (section 3.1 on page 43) your application to use the Merchant/400 API. You may wish to use the I/NET store sample application (section 4.1 on page 85) as a beginning to your own store application. 6.Set up, connect and configure the connection to your Internet Service Provider (ISP) to communicate over the Internet. This may already have been completed to run Web Server/400 or Commerce Server/400. 7.Call the Merchant/400 API to test and run the authorization routines through the entire system path. Merchant/400 can also be used with the Net.Commerce for AS/400 (section 2.10 on page 28) product (5798-NC2) from IBM to process credit card transactions. This interface provides both mall/store functionality and credit card processing without the need for extensive CGI programming. Page 27 Merchant/400 User Manual, Version 1.2 2.0 Get 2.10 Using Merchant/400 with Net.Commerce 2.10.1 Introduction Merchant/400, being an independent credit card processing API, can be used with your own applications or your own CGI store. Special objects are included with Merchant/400 that allow you to use it with the Net.Commerce for AS/400 product (5798-NC2, 5798-NC3) from IBM. These objects replace the default behavior "do_payment" API functionality that is performed by Net.Commerce when the shopper is ready to pay for purchases and elects to process their order. Information about Net.Commerce can be found at www.ibm.com/net.commerce (http://www.ibm.com/net.commerce/). When installed, the Merchant/400 sample store (section 4.1 on page 85) is configured to call a test processing center at I/NET. As a result, when you put the Merchant/400 do_payment interface into place, you can test the credit card transaction process to insure that everything has been moved and updated correctly without actually incurring charges or fees. The test processing center will do minimal validation of the data passed to it and will either return a success or failure. The test processing center only accepts one test credit card. The credit card is: Master Card, 5499740000000032, and expires 1/2001. This is not a real credit card. 2.10.2 Functionality Provided by the Merchant/400 do_payment Interface Once registered, special Merchant/400 objects perform tasks that retrieve information from the Net.Commerce process. They then read order, shopper and merchant data from Net.Commerce and Merchant/400 sample files, and process the credit card transaction. A record is also written to the MNCINFP Merchant/400 file to store approval information about the order. 2.10.2.1 AS/400 Objects Involved in the Interface The following objects are included with the Merchant/400 product specifically to support the Net.Commerce do_payment interface: WWWMNCMA A service program that enables the interface between Net.Commerce and Merchant/400. WWWMNCMA dynamically loads WWWMNCM2 and calls the NCApiDoPayment function found there. During the execution of WWWMNCMA, the library WWWSERVER is added to the job's library list. This is Page 28 Merchant/400 User Manual, Version 1.2 2.0 Get done to facilitate service program linking with the Merchant/400 API. WWWMNCM2 The service program that is the do_payment interface between Net.Commerce and Merchant/400. WWWMNCM2 is linked with the WWWMAPI Merchant/400 service program and contains the NCApiDoPayment functionality. err_do_payment.ncimrc.d2w A Net.Data macro, located in the IFS, that delivers information to the shopper about errors that have occurred during the Merchant/400 do_payment process. orderdspp.ncimrc.d2w A Net.Data macro, located in the IFS, that displays the detail of the shopper's order and allows them to insert credit card information to process payment for the order. Special codes have been added to include the shopper identification when the do_payment API is called as a result of this macro. orderacpt.ncimrc.d2w A Net.Data macro, located in the IFS, that provides the shopper with receipt information about their purchase, including the card processor approval code. NCSAMPLE.C An ILE C source member that allows you to customize the behavior of the Merchant/400 do_payment interface. NCSAMPL2.C An ILE C source member that allows you to customize the behavior of the Merchant/400 do_payment interface. This interface is particular to circumstances when non- registered shopper purchases are desired in a Net.Commerce version 3.2 environment. NVPAIR.C and NVPAIR.H ILE C source member and header information provided originally by IBM as part of the Net.Commerce Toolbox. These source members are compiled and used with NCSAMPLE.C to customize the do_payment interface. MNCINFP A file, shipped in the library WWWMRCH, that contains information about completed credit card transactions. This information includes the order number, credit card number, and approval code associated with the order. Care should be taken to secure this file as it contains private shopper information. The Net.Commerce database user (associated with your mall database instance) is probably the only user that needs access to this file. Page 29 Merchant/400 User Manual, Version 1.2 2.0 Get MNCINFL1 A logical file, built over MNCINFP, in the WWWMRCH library that indexes the MNCINFP data by order ID. Any actions taken on MNCINFP (authority modifications, duplication, etc) should also be performed on this file. MGLOBALP The global configuration file that contains information about how the Merchant/400 sample store operates. This file can also be used by the do_payment interface to determine operational attributes, including remote processing host name, host port, and transmission method. 2.10.2.2 How the Interface Works The following steps are taken by the NCApiDoPayment functionality that is part of the interface: 1.The special orderdspp.ncimrc.d2w Net.Data macro is called to display the order detail and collect credit card information. Shopper identification information is also passed along to the WWWMNCMA program at this point. 2.Resolve to the do_payment interface service progam (WWWMNCM2) and to the NCApiDoPayment API function. 3.Execute the NCApiDoPayment function in WWWMNCM2. 4.Retrieve Name/Value Pair parameters from Net.Commerce. This includes the credit card type, number, expiration date, and shopper identification. 5.Write a record to the ORDPAYMTHD file to flag the order and identify the payment method (credit card information) for the order. 6.Read (via SQL) the ORDERS file to retrieve the external order number. 7.Read (via SQL) the SHADDR file to retrieve the shopper's name and address information for the Merchant/400 API call. 8.Read (via SQL) the MGLOBALP (Global Configuration Physical File on page 92) file to get the Merchant's login information for the Merchant/400 API call. Transmission method and transaction type information is also retrieved at this point. 9.Set up the parameters and structure values (section 3.5 on page 52) for the call to the Merchant/400 API. 10. Add the library WWWSERVER to the job's library list. This is done to allow for the linkage of Merchant/400 and Commerce Server/400 service programs when the Merchant/400 API is executed. 11. Execute (section 3.3 on page 47) the Merchant/400 WwwMrcSubmit API function. 12. Write a record to the MNCINFP (Net.Commerce Order Information Physical File on page 100) file to record the order information and the transaction approval code Page 30 Merchant/400 User Manual, Version 1.2 2.0 Get (Approval Code on page 61) - only if the transaction completed normally (approved). 13. Return the appropriate Net.Commerce response (via return codes and Name/Value Pair parameters) based on information from the Merchant/400 API. 14. Once the do_payment functionality has completed, Net.Commerce calls the appropriate Net.Data macro to present the results of the API to the shopper. If the transaction was approved, orderacpt.ncimrc.d2w is called. If an error occurred, the err_do_payment.ncimrc.d2w macro is called. 15. If orderacpt.ncimrc.d2w is called because of a successful transaction, it reads the MNCINFL1 file (via SQL) retrieving the record associated with the order being processed. It then displays receipt information, including the approval code from the file, to the shopper via HTML. 16. If err_do_payment.ncimrc.d2w is called because of an error, it retrieves the error information from the Name/Value Pairs parameter data, formats it, and displays it to the shopper for their use during problem determination. An opportunity is also provided for the shopper to "go back" to return to the previous screen to make corrections or modifications. If a Book type transaction (Transaction Type on page 53) was placed, it is the merchant's responsibility to develop and execute the appropriate programming to call the Merchant/400 API to register the corresponding Ship transaction once the order is completed. 2.10.3 Configuring the Merchant/400 Objects for Use with Net.Commerce To configure the special Merchant/400 objects for use in a Net.Commerce store environment you will need to move them to a new location and configure the Net.Commerce application to find them. You will also need to update the database to contain information that is appropriate to your online store environment. The following is a list of steps that need to be performed to prepare the Merchant/400 objects for use with Net.Commerce: 1.Copy the Merchant/400 files needed, the Net.Data macros and prepare the newly copied objects for use with your new Net.Commerce mall. The following steps detail these functions: . Copy the Net.Data macros (orderdspp.ncimrc.d2w, err_do_payment.ncimrc.d2w and ordracpt.ncimrc.d2w). These are shipped as IFS stream files in /WWWSERV/WEBDOCS/SHIPPED/MERCHANT. The default location for the Net.Commerce macros is the Page 31 Merchant/400 User Manual, Version 1.2 2.0 Get directory /QIBM/ProdData/NetCommerce/macro/Mri2924/Ncsample and you may copy them there. If the macro directory for your Net.Commerce mall instance is not /QIBM/ProdData/NetCommerce/macro/Mri2924/Ncsample then you should copy the files to the appropriate macro directory for your server. If another version of Merchant/400 is installed, the objects in /WWWSERV/WEBDOCS/SHIPPED/MERCHANT will be overwritten. The copy can be done using the CPY command. For example, to copy the orderdspp.ncimrc.d2w file, you could enter: CPY OBJ('/WWWServ/WebDocs/Shipped/Merchant/orderdspp.nci mrc.d2w') TODIR('/QIBM/ProdData/NetCommerce/macro/Mri2924/Ncsa mple') . Copy the MGLOBALP, MNCINFP and MNCINFL1 files from WWWMRCH to your mall database library that was created when you configured Net.Commerce. This will segregate your Merchant/400 mall information from other Merchant/400 sample data. In addition, if another version of Merchant/400 is installed, the objects in WWWMRCH will be overwritten. The copy can be done using the CRTDUPOBJ command. Don't forget to copy the physical files (MGLOBALP and MNCINFP) first. . Start journalling (required by the Net.Commerce mall application) on the physical file MNCINFP. The command to do this is: STRJRNPF FILE(library/MNCINFP) JRN(library/QSQJRN) IMAGES(*BOTH) OMTJRNE(*OPNCLO) Note that the CPY and CRTDUPOBJ commands will create the new objects with you as the owner and WWWUSER with *ALL object authority. This authority does not include your Net.Commerce mall database instance user (based on the collection assigned when you created the mall in Net.Commerce), so the application may not function properly. You will need to provide the read, write and execute authority needed for your mall user. This can be done using the GRTOBJAUT and CHGAUT commands. You may also wish to change the owner of these objects back to WWWUSER or to the user associated with your Net.Commerce mall. 2.Update the global configuration physical file (MGLOBALP) (Global Configuration Physical File on page 92) in your mall library. This physical file contains a single record that stores a variety of information that the application needs to run. This is also where you set many of the Merchant/400 API parameters, like host service name, transmission method, partner host name, and partner SSL port, that will be used for your credit card transactions. Update the file (using DFU or another utility of your choosing) to contain the Page 32 Merchant/400 User Manual, Version 1.2 2.0 Get parameter information that relate to your application and environment. 3.Register and activate the new objects in the Net.Commerce databases. Please refer to the instructions that relate specifically to Net.Commerce version 2 (section 2.11 on page 35) and Net.Commerce version 3.2 (section 2.12 on page 38) for assistance with this task. Don't forget to change your browser cache and proxy options. Also, the browser Back button does not work very well when using the Net.Commerce Administrator pages. 2.10.4 Creating Your Own API - NCSAMPLE.C and NCSAMPLE2.C Source is provided for you to create your own Net.Commerce - Merchant/400 interfaces. The ILE C member NCSAMPLE can be found in the file WWWSERVER/QCSRC, as well as NVPAIR. An ILE C header file member, NVPAIR, can also be found in the file WWWSERVER/H. These are provided as sample code to assist you in the understanding of the code requirements for do_payment functionality during the development of your own API. NCSAMPLE is slightly different from the WWWMNCMA and WWWMNCM2 functionality in that it performs the SQL database operations and then dynamically loads the WWWMAPI service program and executes the WwwMrcSubmit function. WWWMNCMA dynamically loads the WWWMNCM2 service program, which does the database operations and executes WwwMrcSubmit directly (WWWMAPI was linked when WWWMNCM2 was created). NCSAMPLE was created in this manner so you only have one source member to modify and compile when creating your unique API functionality. NCSAMPLE may be modified as needed to accomodate your individual merchant environment. Specifications for the CRTSQLCI and CRTSRVPGM commands are included in special build notes that can be found at the beginning of the NCSAMPLE source. The NVPAIR source (both ILE C and header) were originally provided by IBM as part of the Net.Commerce Toolbox. As such, it is not recommended that modify either of these files. Information in the Net.Commerce documentation will also be helpful in creating the module and service program objects for your API. Your NCSAMPLE service program may be registered for use by the Net.Commerce in the same manner as the Merchant/400 customized API, described earlier (Register and activate on page 33). The Net.Data macros (orderdspp.ncimrc.d2w, err_do_payment.ncimrc.d2w and ordracpt.ncimrc.d2w) that are shipped as IFS stream files in /WWWSERV/WEBDOCS/SHIPPED/MERCHANT may also be tailored to meet your individual needs to present the appropriate Page 33 Merchant/400 User Manual, Version 1.2 2.0 Get interfaces to the shoppers of your mall. If another version of Merchant/400 is installed, the objects in /WWWSERV/WEBDOCS/SHIPPED/MERCHANT will be overwritten, so it is recommended that you make modifications for your mall in a different directory. Your order display, approval and error macros may be registered for use by the Net.Commerce in the same manner as the Merchant/400 customized macros, described earlier (Register and activate on page 33). In addition, for those circumstances when non-registered shopper purchases are desired in a Net.Commerce version 3.2 environment, NCSAMPL2 and orderdspp2.ncimrc.d2w are also provided as samples to collect credit card name and address information that is needed during the purchase process. These may also be duplicated and modified to suit the individual needs of the online mall or store. Page 34 Merchant/400 User Manual, Version 1.2 2.0 Get 2.11 Configuring Merchant/400 Objects for Use with Net.Commerce version 2 To enable the special Merchant/400 objects for use in a Net.Commerce version 2 store environment, you will need to configure the Net.Commerce application to register the customized API and macros so it can find and use them. To do this, you will need to execute various Net.Commerce configuration routines to reflect the new names and references. As a result, some knowledge of the Net.Commerce browser-based configuration will be helpful for the completion of this task. 2.11.1 Activating the Customized do_payment API in Net.Commerce version 2 Perform the following steps to activate the customized do_payment API functionality that will execute credit card transactions via Merchant/400 (please refer to the Net.Commerce documentation for additional information about the assignment of API tasks and macros): 1.Ensure that you are authorized to replace the DO_PAYMENT task. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the API task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the DO_PAYMENT task name from the list. The fields automatically fill with task information. 7.Go to the API DLL/Function Assignment form by clicking Task Assignment and then API DLL/Function. 8.Enter the following in the API DLL Name and API Function Name fields on the API DLL/Function Assignment form: The API service program name and the API service program function name. For the service program name, use the format: /, or . In the last case, the name will be resolved at runtime using the library list. The API service program function name is case-sensitive and should contain the text "NCApiDoPayment". As a result, for the objects shipped with Merchant/400: . In API DLL Name type the service program name: WWWSERVER/WWWMNCMA (or WWWSERVER/NCSAMPLE for your own customized API (Creating Your Own API - NCSAMPLE.C and NCSAMPLE2.C on page 33)) . In API Function Name type the service program function name: NCApiDoPayment Page 35 Merchant/400 User Manual, Version 1.2 2.0 Get 9.Click Save. 2.11.2 Activating the Customized Net.Data macros in Net.Commerce Special Net.Data macros are included to retrieve specialized data about the order and shopper, and to deliver Merchant/400 information to the shopper about the results of their credit card transaction. Once the macro files are moved into place, you should perform the following steps to activate the customized macro for do_payment errors: 1.Ensure that you are authorized to replace the DO_PAYMENT error macro. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the API task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the DO_PAYMENT task name from the list. The fields automatically fill with task information. 7.Go to the Macro Assignment form by clicking Task Assignment and then API Error Macro.... 8.Enter the following in the Macro Filename field on the Macro Assignment form: . The Merchant/400 Net.Data macro name err_do_payment.ncimrc.d2w, or . The macro name of a do_payment error Net.Data macro that you have tailored to your individual requirements. 9.Click Save. Perform the following steps to activate the customized macro for order acceptance: 1.Ensure that you are authorized to replace the ORD_OK macro. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the ORDER task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the ORD_OK task name from the list. The fields automatically fill with task information. 7.Go to the Macro Assignment form by clicking Task Assignment. 8.Enter the following in the Macro Filename field on the Macro Assignment form: Page 36 Merchant/400 User Manual, Version 1.2 2.0 Get . The Merchant/400 Net.Data macro name orderacpt.ncimrc.d2w, or . The macro name of an order acceptance Net.Data macro that you have tailored to your individual requirements. 9.Click Save. Perform the following steps to activate the customized macro for order detail display: 1.Ensure that you are authorized to replace the ORD_DSP_PEN macro. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the ORDER task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the ORD_DSP_PEN task name from the list. The fields automatically fill with task information. 7.Go to the Macro Assignment form by clicking Task Assignment. 8.Enter the following in the Macro Filename field on the Macro Assignment form: . The Merchant/400 Net.Data macro name orderdspp.ncimrc.d2w, or . The macro name of an order acceptance Net.Data macro that you have tailored to your individual requirements. 9.Click Save. Please refer to the Net.Commerce version 2 documentation for additional information about the assignment of API tasks and macros. Page 37 Merchant/400 User Manual, Version 1.2 2.0 Get 2.12 Configuring Merchant/400 Objects for Use with Net.Commerce version 3.2 To enable the special Merchant/400 objects for use in a Net.Commerce version 3.2 store environment, you will need to configure the Net.Commerce application to register the customized API and macros so it can find and use them. To do this, you will need to modify various Net.Commerce database files to reflect the new names and references. As a result, some AS/400 database or SQL knowledge will be helpful for the completion of this task. Knowledge of the Net.Commerce browser-based configuration will also be helpful while activating the Net.Data macros. It is important to note that the Merchant/400 integration is accomplished via Process Task API Execution rather than Overridable Functions, since the functionality and configuration of each can be easily confused. Special thanks to Martin Holmes of Morpheus, Ltd. (www.morpheus.ltd.uk) for his work on this page and the API registration technique that it employs. 2.12.1 Activating the Customized do_payment API in Net.Commerce version 3.2 Perform the following steps to activate the customized do_payment process task API functionality that will execute credit card transactions via Merchant/400 (please refer to the Net.Commerce documentation for additional information about the assignment of process task APIs and macros): 1.Ensure that you are authorized to replace the DO_PAYMENT task. 2.Register the Merchant/400 Payment API in Net.Commerce. . Insert a record into the APIS database table that resides in your Net.Commerce instance library. Example values are shown in the table below: APIRFNBR APIMERNB APIDLLNAME APIFUNCNAME R 2015 Page 38 Merchant/400 User Manual, Version 1.2 2.0 Get NOTE: The reference is the MERFNBR value for your store in the MERCHANT file in your instance library. 3.Override the DO_PAYMENT process with the Merchant/400 API. . Insert a record into the TASK_MER_OF table within your instance library. Example values are shown below: TASK_RN MERCHANT_RN OF_RN SEQUENCE 2015 NOTE: The OF_RN reference is the REFNUM value for the DoPaymentProxy function in the OFS table in your instance library. 2.12.2 Activating the Customized Net.Data macros in Net.Commerce Special Net.Data macros are included to retrieve specialized data about the order and shopper, and to deliver Merchant/400 information to the shopper about the results of their credit card transaction. Once the macro files are moved into place, you should perform the following steps to activate the customized macro for do_payment errors: 1.Ensure that you are authorized to replace the DO_PAYMENT error macro. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the API task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the DO_PAYMENT task name from the list. The fields automatically fill with task information. 7.Go to the Macro Assignment form by clicking Task Assignment and then API Error Macro.... 8.Enter the following in the Macro Filename field on the Macro Assignment form: Page 39 Merchant/400 User Manual, Version 1.2 2.0 Get . The Merchant/400 Net.Data macro name err_do_payment.ncimrc.d2w, or . The macro name of a do_payment error Net.Data macro that you have tailored to your individual requirements. 9.Click Save. Perform the following steps to activate the customized macro for order acceptance: 1.Ensure that you are authorized to replace the ORD_OK macro. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the ORDER task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the ORD_OK task name from the list. The fields automatically fill with task information. 7.Go to the Macro Assignment form by clicking Task Assignment. 8.Enter the following in the Macro Filename field on the Macro Assignment form: . The Merchant/400 Net.Data macro name orderacpt.ncimrc.d2w, or . The macro name of an order acceptance Net.Data macro that you have tailored to your individual requirements. 9.Click Save. Perform the following steps to activate the customized macro for order detail display: 1.Ensure that you are authorized to replace the ORD_DSP_PEN macro. 2.Open the Net.Commerce Administrator using your browser. 3.On the task bar, click Site Manager. 4.Click Task Management to display the Task Management form. 5.Select the ORDER task type from the Select Task Type drop-down list. A list of tasks appears in the bottom frame. 6.Select the ORD_DSP_PEN task name from the list. The fields automatically fill with task information. 7.Go to the Macro Assignment form by clicking Task Assignment. 8.Enter the following in the Macro Filename field on the Macro Assignment form: . The Merchant/400 Net.Data macro name orderdspp.ncimrc.d2w, or Page 40 Merchant/400 User Manual, Version 1.2 2.0 Get . The macro name of an order acceptance Net.Data macro that you have tailored to your individual requirements. 9.Click Save. Please refer to the Net.Commerce version 3.2 documentation for additional information about the assignment of API process tasks and macros. Page 41 Merchant/400 User Manual, Version 1.2 3.0 Usi 3. Using Merchant/400 Page 42 Merchant/400 User Manual, Version 1.2 3.0 Usi 3.1 Using the Merchant/400 API 3.1.1 Introduction Merchant/400 API interfaces are provided for two different programming environments: . ILE (e.g., ILE C, ILE RPG, ILE COBOL) . OPM (e.g., RPG, COBOL, CL) An OPM interface is provided by a program in library WWWSERVER. The WWWMAPI service program in library WWWSERVER provides the ILE entry point. A bind directory named MBNDDIR in library WWWSERVER is provided to aid in developing ILE applications. 3.1.2 Files Provided to Aid your Development Effort Includes are provided to aid in developing applications in the following programming environments: ILE C Prototypes and structures are provided for ILE C applications. See the member WWWMAPI (/qsys/wwwserver/h/WWWMAPI.txt) in source file H (i.e., WWWMAPI.H) in library WWWSERVER for more information on ILE C interfaces. More information is also available in the topic that discusses calling the API from an ILE program (section 3.3 on page 47). ILE RPG Constants that define ILE API entry points for ILE RPG applications are available in member DWWWMAPI (/qsys/wwwserver/qrpglesrc/DWWWMAPI.txt) in WWWSERVER/QRPGLESRC. More information is also available in the topic that discusses calling the API from an ILE program (section 3.3 on page 47). ILE COBOL Data items that define ILE API entry points for ILE COBOL applications are available in member WWWMAPI (/qsys/wwwserver/qcbllesrc/WWWMAPI.txt) in WWWSERVER/QCBLLESRC. More information is also available in the topic that discusses calling the API from an ILE program (section 3.3 on page 47). RPG Data items that define API entry points for RPG/400 applications are available in member WWWMAPI Page 43 Merchant/400 User Manual, Version 1.2 3.0 Usi (/qsys/wwwserver/qrpgsrc/WWWMAPI.txt) in WWWSERVER/QRPGSRC. More information is also available in the topic that discusses calling the API from an OPM program (section 3.4 on page 50). COBOL Data items that define API entry points for COBOL/400 applications are available in member WWWMAPI (/qsys/wwwserver/qcblsrc/WWWMAPI.txt) in WWWSERVER/QCBLSRC. More information is also available in the topic that discusses calling the API from an OPM program (section 3.4 on page 50). The section that discusses error conditions (section 3.6 on page 63) should also be reviewed when writing programs to access the API. Page 44 Merchant/400 User Manual, Version 1.2 3.0 Usi 3.2 What is a Merchant Server? 3.2.1 A Way to do Business Over the Internet Do you know how to process a credit card? Many people think of the terminal or "swipe" machine at their local restaurant, market, or hotel. Most business applications require that you bill your customer or accept credit card information to be keyed manually before the order is filled. This can mean slower response to your customers, delayed order shipping, and special security requirements to keep your customer's credit card information safe. Not so anymore!!! With Merchant/400, used in conjunction with Commerce Server/400, you can now call a simple API (Application Programming Interface) to process business transactions over the World Wide Web. You can use your AS/400 applications to collect credit card information from the customer while the order is being placed - making the transaction easier and more secure for your customer, resulting in new marketing, public relations and customer support opportunities. 3.2.2 The Process Here's how it works. AS/400 applications collect information about an order - the customer, their credit card information, and the total amount to be charged. This is structured and sent via a call (section 3.1 on page 43) to the Merchant/400 API. Merchant/400 packages the information and sends it, via a secure SSL link, to a transaction processing center. Once received, the transaction center processes the transaction with your credit card processing center (section 2.2 on page 16). The results (approved or denied) are returned to your application - usually within 1 minute. And you can transact charges or pre-authorizations and shipments with Merchant/400 too, just by specifying a transaction type (Transaction Type on page 53). Merchant/400 means your business doesn't need to rely on someone calling for credit card approval anymore. Your customers can make purchases and pay for them - immediately. No more waiting for the "credit authorization" person to get in. No more calls to inform the customer that their credit was denied and you can not fill their order. No more fumbling with the Veriphone terminal to enter a transaction. In summary, Merchant/400 in conjunction with Commerce Server/400, gives you the following benefits: Page 45 Merchant/400 User Manual, Version 1.2 3.0 Usi . Quick authorization of charged amounts - at any time, day or night . Ability to charge or authorize/reserve amounts, depending on your business needs . Faster processing and delivery of customer orders . Use of applications to collect information - no credit card terminal necessary . More reliable completion of transactions - fewer "on account" sales Page 46 Merchant/400 User Manual, Version 1.2 3.0 Usi 3.3 Using the Merchant/400 API in an ILE Program 3.3.1 Introduction The Merchant/400 API interface provided for the ILE (Integrated Language Extensions) environment is through the service program WWWMAPI in the WWWSERVER library. Function prototypes and definitions are provided for ILE C applications in the member WWWMAPI (/qsys/wwwserver/h/WWWMAPI.txt) in source file H (i.e., WWWMAPI.H) in library WWWSERVER. Constants that define API entry points for ILE RPG applications are available in member DWWWMAPI (/qsys/wwwserver/qrpglesrc/DWWWMAPI.txt) in WWWSERVER/QRPGLESRC. Data items that define API entry points for ILE COBOL applications can be found in member WWWMAPI (/qsys/wwwserver/qcbllesrc/WWWMAPI.txt) in WWWSERVER/QCBLLESRC. A bind directory named MBNDDIR in library WWWSERVER is provided to aid in developing ILE applications. 3.3.2 The ILE Call to Execute the API The following documents the function that is available to execute the Merchant/400 API in an ILE environment. The API requires all of the parameters that are listed. More information about the minimum information needed by the API can be found in the topic on Required Information (section 3.7 on page 68). WwwMrcSubmit ILE C Prototype: void WwwMrcSubmit(char *pachRemoteHost, long lRemoteHostLen, long lRemotePort, long lTransmitMethod, long lInputFormat, void *pSubmitInputs, long lOutputFormat, void *pSubmitResults, long *plResultSuccess); where, pachRemoteHost is the buffer containing the name and domain, or IP address, of the remote processing host. This will be supplied by the partner agency. Page 47 Merchant/400 User Manual, Version 1.2 3.0 Usi lRemoteHostLen is the length of the Remote Host Name buffer. This will be calculated by your application based on the size of the entry in the pachRemoteHost parameter. lRemotePort is the socket port number used by the remote host for SSL communications. This will usually be set to 443. lTransmitMethod tells the Merchant/400 API how to transmit the data. Please refer to the topic What Happens - Transmission Methods (section 3.8 on page 78) for more information on how to set this parameter. lInputFormat tells the API what format your input data (Input Formats and Structures. on page 52) will be in. pSubmitInputs is the formatted buffer that holds the customer, order, and credit card information. lOutputFormat tells the API what format you are expecting to receive results data (Output Formats and Structures. on page 63) to be in. pSubmitResults is the formatted buffer that will hold the returned transaction information from the card processor. plResultSuccess is the code returned (section 3.6 on page 63) indicating the success of the transaction. ILE RPG or COBOL Parameters: 1. Remote Host Name Input Char(*) 2. Remote Host Name Length Input Binary(4) 3. Remote Port Number Input Binary(4) 4. Transmission Method Input Binary(4) 5. Input Data Format Input Binary(4) 6. Input Data Buffer Input Char(*) 7. Output Data Format Input Binary(4) 8. Output Data Buffer Input/Output Char(*) 9. Completion Indicator Output Binary(4) where, Remote Host Name is the buffer containing the name and domain, or IP address, of the remote processing host. This will be supplied by the partner agency. Remote Host Name Length is the length of the Remote Host Name buffer. This will be calculated by your application based on the size of the entry in the Remote Host Name parameter. Page 48 Merchant/400 User Manual, Version 1.2 3.0 Usi Remote Port Number is the socket port number used by the remote host for SSL communications. This will usually be set to 443. Transmission Method tells the Merchant/400 API how to transmit the data. Please refer to the topic What Happens - Transmission Methods (section 3.8 on page 78) for more information on how to set this parameter. Input Data Format tells the API what format your input data (Input Formats and Structures. on page 52) will be in. Input Data Buffer is the formatted buffer that holds the customer, order, and credit card information. Output Data Format tells the API what format you are expecting to receive results data (Output Formats and Structures. on page 63) to be in. Output Data Buffer is the formatted buffer that will hold the returned transaction information from the card processor. Completion Indicator is the code returned (section 3.6 on page 63) indicating the success of the transaction. Please refer to the document What Happens - Transmission Methods (section 3.8 on page 78) for a description of the processing that is performed within the API. Page 49 Merchant/400 User Manual, Version 1.2 3.0 Usi 3.4 Using the Merchant/400 API in an OPM Program 3.4.1 Introduction The Merchant/400 API interface provided for the OPM (Original Programming Model) environment is through the program WWWMRCSB in the WWWSERVER library. Constants that define API entry points for OPM RPG applications are available in member WWWMAPI (/qsys/wwwserver/qrpgsrc/WWWMAPI.txt) in WWWSERVER/QRPGSRC. Data items that define API entry points for COBOL applications can be found in member WWWMAPI (/qsys/wwwserver/qcblsrc/WWWMAPI.txt) in WWWSERVER/QCBLSRC. 3.4.2 The OPM Program to Call to Execute the API The following documents the program that is available to execute the Merchant/400 API in an OPM environment. The API requires all of the parameters that are listed. More information about the minimum information needed by the API can be found in the topic on Required Information (section 3.7 on page 68). The library WWWSERVER must be in your library list before calling the API. WWWMRCSB Parameters: 1. Remote Host Name Input Char(*) 2. Remote Host Name Length Input Binary(4) 3. Remote Port Number Input Binary(4) 4. Transmission Method Input Binary(4) 5. Input Data Format Input Binary(4) 6. Input Data Buffer Input Char(*) 7. Output Data Format Input Binary(4) 8. Output Data Buffer Input/Output Char(*) 9. Completion Indicator Output Binary(4) where, Remote Host Name is the buffer containing the name and domain, or IP address, of the remote processing host. This will be supplied by the partner agency. Remote Host Name Length is the length of the Remote Host Name buffer. This will be calculated by your application based on the size of the entry in the Remote Host Name parameter. Page 50 Merchant/400 User Manual, Version 1.2 3.0 Usi Remote Port Number is the socket port number used by the remote host for SSL communications. This will usually be set to 443. Transmission Method tells the Merchant/400 API how to transmit the data. Please refer to the topic What Happens - Transmission Methods (section 3.8 on page 78) for more information on how to set this parameter. Input Data Format tells the API what format your input data (Input Formats and Structures. on page 52) will be in. Input Data Buffer is the formatted buffer that holds the customer, order, and credit card information. Output Data Format tells the API what format you are expecting to receive results data (Output Formats and Structures. on page 63) to be in. Output Data Buffer is the formatted buffer that will hold the returned transaction information from the card processor. Completion Indicator is the code returned (section 3.6 on page 63) indicating the success of the transaction. Please refer to the document What Happens - Transmission Methods (section 3.8 on page 78) for a description of the processing that is performed within the API. Page 51 Merchant/400 User Manual, Version 1.2 3.0 Usi 3.5 Input and Output Formats 3.5.1 How to Exchange Data With the API You, the merchant, have collected order information from the customer in your application program and are now ready to send it to the Merchant/400 API to approve the purchase and complete the order. This exchange of order and result information is done via formats and structures that have been created for each of the differing styles of data being transferred. The selected input and output structures are passed to the API as parameters with format identifiers to indicate to the API which structure to use for its internal processing of the passed data. The definitions of the structures and format identifiers may be found for ILE C programs in the wwwmapi.h include member. Definitions for other ILE and OPM programs can be found in the member WWWMAPI in their respective source files (QRPGSRC, QCBLSRC, and QCBLLESRC). ILE RPG data structure definitions may be found in the DWWWMAPI member. These definitions should be copied into your program source for use in your application. 3.5.1.1 Input Formats and Structures. Customer, order, credit card, and other information is passed to the Merchant/400 API via the Input Data Buffer parameter and can take the form of the WWWMERCH_INPUT1, WWWMERCH_INPUT2 or WWWMERCH_INPUT999 structures. By specifying MERCH_INPUT1, MERCH_INPUT2 or MERCH_INPUT999 in the Input Data Format parameter, you inform the API that input data is in the WWWMERCH_INPUT1, WWWMERCH_INPUT2 or WWWMERCH_INPUT999 style structures, respectively. The data required (section 3.7 on page 68) by the host service and the transmission method (section 3.8 on page 78) desired will help determine which of these formats to choose for each transaction processed. The WWWMERCH_INPUT1 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables): Field DataType Lengt Description Name h Host binary 9,0 This entry is used to further Service determine the route processing Name for the transaction. If the transaction is to be processed through Holonet IAT, you must Page 52 Merchant/400 User Manual, Version 1.2 3.0 Usi specify the type of service you wish to utilize. You currently have three choices: 1.MERCH_INPUT1_HOLOPAY - Use the direct HoloPay service 2.MERCH_INPUT1_CCN - Use the Credit Card Network service 3.MERCH_INPUT1_ANACOM - Use the Anacom Communications service If your transaction will not be routed through Holonet, this field is ignored and can contain any of the valid choices. Transact binary 9,0 Merchant/400 includes the ion Type ability to charge an amount to a credit card via a "sale" transaction, and to request authorization for a charged amount, via a "book" transaction, reserving that amount to be charged later by a "ship" transaction. This entry is used to determine the process that will take place (sale, book, ship) for this transaction. If the transaction is to be processed through Anacom Communications, you must specify the type of transaction that this is. You currently have three choices: 1.MERCH_TRTYPE1_SALE - This is an immediate sale transaction. The amount specified in Order / Charge Amount (Order / Charge Amount on page 61) will be charged to the credit card. 2.MERCH_TRTYPE1_BOOK - This transaction will authorize the amount specified in Order / Charge Amount and reserve Page 53 Merchant/400 User Manual, Version 1.2 3.0 Usi it against the credit limit associated with the card. The authorization and reserve is valid for a thirty (30) day period before it is automatically removed by the card processor. A "ship" transaction must be sent with the Result Code, and possibly Host Reference, from this transaction to actually charge an amount to the credit card. 3.MERCH_TRTYPE1_SHIP - This transaction will complete a previously issued "book" transaction. During this transaction, the authorization and reserve are modified to match the Order / Charge Amount specified and actually charged to the credit card. When this transaction is successfully completed, the authorization and reserve are removed and the Order / Charge Amount is charged to the credit card. Approval Code (Approval Code on page 61) is required for this type of transaction. If your transaction will not be routed through Anacom or DataCash, this field is ignored and can contain any of the valid choices. Merchant character 256 This is the merchant user name Name used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account. This is not the Merchant identification number assigned Page 54 Merchant/400 User Manual, Version 1.2 3.0 Usi by your card processor. Merchant character 256 This is the merchant password Password used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account and is associated with your merchant name. Order ID character 64 A string that uniquely identifies the transaction. This is usually an order number, but can be any set of characters that allows you to track the transaction through each processing service and to your card processor. Customer character 64 The name of the customer for Name this transaction. This name must match the name found on the credit card. Customer character 128 This is the billing address Address for the customer card account. It must match the billing address for the credit card that is used for this transaction. Customer character 64 Along with the Customer City Address, this is the associated bill-to city for the customer card account. Customer character 64 The bill-to state or province State/Pr associated with the customer ovince card account. Customer character 64 The bill-to zip code or postal Zip/Post code associated with the al Code customer card account. Customer character 64 The bill-to country associated Country with the customer card account. Credit character 64 This is the number for the Card credit card being used for Number this transaction. You should Page 55 Merchant/400 User Manual, Version 1.2 3.0 Usi not insert hyphens (-) or spaces at any points in the number. Card 3,0 This is the month portion of Expirati decimal packed the credit card expiration on Month date. It is formatted in a "MM" format and must be a number from 1 to 12. Card packed 5,0 This is the year portion of Expirati decimal the credit card expiration on Year date. It is formatted in a "YYYY" format. For example, a credit card that expires in July, 1998 would have a card expiration month of 07 and a card expiration year of 1998. Order / packed 15,5 This is the amount of the Charge decimal order that is to be charged or Amount authorized to the credit card identified in the credit card number field. This amount is to be valued in the currency of the merchant account at the card processing organization. For example, if your merchant account is set in United States dollars, this amount must be in US dollars. If you typically do business in another currency, you must calculate the conversion amount based on the currency of your merchant account. Approval character 256 This entry, associated with Code the MERCH_TRTYPE1_SHIP Transaction Type (Transaction Type on page 53), links this MERCH_TRTYPE1_SHIP transaction to a previous related "book" transaction. The value of this entry emanated from the credit card processor during the original "book" transaction and must match to complete the actual charge transaction. Page 56 Merchant/400 User Manual, Version 1.2 3.0 Usi The WWWMERCH_INPUT2 structure has the following field elements (Note - The following field elements are formatted using HTML table definitions that are best viewed with a browser that supports tables): Field DataType Lengt Description Name h Host binary 9,0 This entry is used to further Service determine the route processing Name for the transaction. If the transaction is to be processed through Holonet IAT, you must specify the type of service you wish to utilize. You currently have three choices: 1.MERCH_INPUT1_HOLOPAY - Use the direct HoloPay service 2.MERCH_INPUT1_CCN - Use the Credit Card Network service 3.MERCH_INPUT1_ANACOM - Use the Anacom Communications service 4.MERCH_INPUT1_DATACASH - Use the DataCash service If your transaction will not be routed through Holonet, this field is ignored and can contain any of the valid choices. Transact binary 9,0 Merchant/400 includes the ion Type ability to charge an amount to a credit card via a "sale" transaction, and to request authorization for a charged amount, via a "book" transaction, reserving that amount to be charged later by a "ship" transaction. This entry is used to determine the process that will take place (sale, book, ship) for this transaction. If the transaction is to be processed through Anacom Communications or DataCash, you must specify the type of transaction that Page 57 Merchant/400 User Manual, Version 1.2 3.0 Usi this is. You currently have three choices: 1.MERCH_TRTYPE1_SALE - This is an immediate sale transaction. The amount specified in Order / Charge Amount (Order / Charge Amount on page 61) will be charged to the credit card. 2.MERCH_TRTYPE1_BOOK - This transaction will authorize the amount specified in Order / Charge Amount and reserve it against the credit limit associated with the card. The authorization and reserve is valid for a thirty (30) day period before it is automatically removed by the card processor. A "ship" transaction must be sent with the Result Code, and possibly Host Reference, from this transaction to actually charge an amount to the credit card. 3.MERCH_TRTYPE1_SHIP - This transaction will complete a previously issued "book" transaction. During this transaction, the authorization and reserve are modified to match the Order / Charge Amount specified and actually charged to the credit card. When this transaction is successfully completed, the authorization and reserve are removed and the Order / Charge Amount is charged to the credit card. Approval Code (Approval Code on page 61) is required for this type of transaction. Page 58 Merchant/400 User Manual, Version 1.2 3.0 Usi Order ID (Order ID on page 59) will also be used to contain the previously received Host Reference Code (Result Host Reference on page 61) when issuing the "ship" via the DataCash service. If your transaction will not be routed through Anacom or DataCash, this field is ignored and can contain any of the valid choices. Merchant character 256 This is the merchant user name Name used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account. This is not the Merchant identification number assigned by your card processor. Merchant character 256 This is the merchant password Password used during logon for transaction transfer. It is assigned by the the Internet partner agency when you created your merchant account and is associated with your merchant name. Order ID character 64 A string that uniquely identifies the transaction. This is usually an order number, but can be any set of characters that allows you to track the transaction through each processing service and to your card processor. If the book or sale transaction is to be processed via DataCash, this must contain a numeric value between 6 and 9 digits long. In the case of a MERCH_TRTYPE1_SHIP (Transaction Type on page 57) transaction processed via the Page 59 Merchant/400 User Manual, Version 1.2 3.0 Usi DataCash service, Order ID will be used to contain the previously received Host Reference Code (Result Host Reference on page 61) from the "book" transaction. Customer character 64 The name of the customer for Name this transaction. This name must match the name found on the credit card. Customer character 128 This is the billing address Address for the customer card account. It must match the billing address for the credit card that is used for this transaction. Customer character 64 Along with the Customer City Address, this is the associated bill-to city for the customer card account. Customer character 64 The bill-to state or province State/Pr associated with the customer ovince card account. Customer character 64 The bill-to zip code or postal Zip/Post code associated with the al Code customer card account. Customer character 64 The bill-to country associated Country