Using Merchant/400 with Net.Commerce

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.as400.ibm.com.

When installed, the Merchant/400 sample store 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.

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.

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

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 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 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 the Merchant/400 WwwMrcSubmit API function.
  12. Write a record to the MNCINFP file to record the order information and the transaction approval code - 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 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.

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:

    2. 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) 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 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 and Net.Commerce version 3.2 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.

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.

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

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.