Using Merchant/400 with Net.Commerce
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
Information about Net.Commerce can be found at
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
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:
- 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
- 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.
- 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
- 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.
- A Net.Data macro, located in the IFS, that provides the shopper with
receipt information about their purchase, including the card processor
- An ILE C source member that allows you to customize the behavior
of the Merchant/400 do_payment interface.
- 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
- 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.
- 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.
- 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:
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.
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
- 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.
- Resolve to the do_payment interface service progam (WWWMNCM2) and to
the NCApiDoPayment API function.
- Execute the NCApiDoPayment function in WWWMNCM2.
- Retrieve Name/Value Pair parameters from Net.Commerce. This includes
the credit card type, number, expiration date, and shopper identification.
- Write a record to the ORDPAYMTHD file to flag the order and identify
the payment method (credit card information) for the order.
- Read (via SQL) the ORDERS file to retrieve the external order number.
- Read (via SQL) the SHADDR file to retrieve the shopper's name and
address information for the Merchant/400 API call.
- 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.
- Set up the parameters and structure values
for the call to the Merchant/400 API.
- 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.
- Execute the Merchant/400 WwwMrcSubmit API function.
- Write a record to the MNCINFP
file to record the order information and the transaction
approval code - only if the transaction
completed normally (approved).
- Return the appropriate Net.Commerce response (via return codes and
Name/Value Pair parameters) based on information from the Merchant/400
- 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.
- 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
- 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
The following is a list of steps that need to be performed to prepare
the Merchant/400 objects for use with Net.Commerce:
- 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 (
These are shipped as IFS stream files in
/WWWSERV/WEBDOCS/SHIPPED/MERCHANT. The default location for
the Net.Commerce macros is the directory
/QIBM/ProdData/NetCommerce/macro/Mri2924/Ncsample and you may
copy them there. If the macro directory for your Net.Commerce mall instance
/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:
- Copy the
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
- 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)
Note that the
CRTDUPOBJ commands will
create the new objects with you as the owner and
*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
CHGAUT commands. You may also wish to change the owner of
these objects back to
WWWUSER or to the user associated with your
Update the global configuration physical
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.
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.
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
WWWMNCM2 functionality in that it performs the SQL database
operations and then dynamically loads the
WWWMAPI service program
and executes the
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
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,
The Net.Data macros (
that are shipped as IFS stream files in
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
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,
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