External API - Development and Implementation Guideline for integration with our eCommerce payment gateway

This document is to assist developers in creating web applications that utilise the Netregistry Payment Gateway (NPG) where the application will be written in a language, other than Perl, such as PHP or C, or where the developer is not hosting the website on Netregistry's servers.

Requirements

In order to create an application as detailed below, you will need

1. An eCommerce Merchant Account.
   Merchant accounts must be with the St George Bank or the National Australia Bank
2. If you do wish to host your eCommerce Store with Netregistry, you will need a compatible eCommerce Hosting account, such as Merchant eCommerce. Otherwise, you will require your own web server.
   
3. Local development resources (if applicable)
   For security reasons no telnet, ssh, or other console mode access is allowed to our web servers. In order to develop and debug you will need access to local resources (i.e. yours) if you plan to host on our servers. These should include a cgi capable web server, a UNIX or UNIX like operating system, and server language support (for example PHP) that you wish to use. Apache users please be aware that zeus does not support apache modules, so you may need to contact us to ensure that what you intend to do will be compatible with our servers.
   Applications can be created on any operating system, using any languages you wish, as long as the language can support external https calls.

Synopsis

Unlike the native Perl API, external access is treated on an account basis. The only service provided by Netregistry is in the form of an access account. Access to the account is the responsibility of the developer.

The account consists of access to a generic CGI program that serves as an interface between the gateway and an arbitrary program on your, or our server.

From this point, this document will deal with on-site and off-site options separately.

Off Site

The process for off-site accounts is quite simple. To begin, you will need an eCommerce Merchant facility. This will get you a merchant number and a terminal ID. If you plan to put through a reasonably large number of transactions ( 100 per day or higher ) we recommend having two terminal IDs. If you plan to put through more than 1000-2000 transactions per day or higher, we recommend you have three to four terminal IDs.

Once your eCommerce Merchant number and terminal IDs have been provided to Netregistry, you will be allocated an MID ( Netregistry Merchant ID ). You will also be provided with two passwords. The first is your log password. This is used to access the log viewer. Using the log viewer, you are able to see all transaction attempts made with the bank. The log view also generates daily and monthly statistics for your account.

The second password is known as your Account Access Password. This is a long random 16 digit alphanumeric number. This number should be strictly guarded, as it would enable an outside party to generate false credit card request to your account.

A Note on Security and Responsibility

The responsibility for security of credit card details has defined beginning and end points. You, the developer, are responsible for security from the browser to your server, and from there to Netregistry's External Access Server. Your responsibility ends once the data has reached the EAS.

A Note on GET vs POST

Whichever application language you are using we HIGHLY recommend you use POST instead of GET. There has been some evidence that GETs will cause responses to cache in some situations, and instead of repeating the attempt at the same transaction, the result from the previous attempt will be used instead. Hence, you should always use POST.

On Site

On site "external" access works similarly to off site access described above, except there will be the extra step of porting your application to our servers.

Synopsis

The development process will usually consist of four stages, preparation, program creation, porting and testing and activation.

• Preparation
  Collecting the resources you will need to create the program
• Program Creation
  Actually programming the application, or conversion of an existing application
• Porting and Testing
  The process of moving the application from your local development server to our production web server, modifications to connect all required resources, and thorough testing of the application

Final

Thorough preparation will make development, testing and activation far simpler.

Account status

For the external API, there is no generic test account available for you to use. This means that you will need your Netregistry Account, and have been issued with your Account Access Password before you can write and test that section of your program. Testing can only be performed using your own account.

Server Support

You are advised to check with Netregistry before commencing development to ensure that everything you wish to do can be supported by the servers. For example, because the servers support the Frontpage extensions, they do not support ACCESS databases, even though accessing ACCESS databases is a part of the use of Frontpage extensions. Please ensure all modules, libraries etc can be used. If you are using an Apache module for the development, please check to ensure that an equivalent process exists for Zeus. Also, make sure that version compatibility exists as well, so that language changes will not cause a problem. The technical staff at Netregistry can advise you on which technologies you can or cannot use.

Development server file structure.

One factor that can make the transferal of an application more difficult is that the underlying filesystem structure may change. This is a particular issue with Apache, the most commonly used development web server platform. The difference between the two filesystems is shown below

Apache Directory Structure	Zeus Directory Structure

Note that the Apache directory structure has the root html and cgi-bin directories side by side, whereas the zeus directory structure has the cgi-bin directory underneath the main html directory.

In order to overcome this, we recommend modifying the directory structure of apache to the following.

Modified Apache Directory Structure

Making this change will ensure that you have no file system structure problems when moving your website from an Apache style web server to Zeus.

Program Creation

This section provides a general guide to the creation of your application. For specific commands, syntax, and response types.

Your properly created application will make the call to the gateway in six stages

Stage 1 - Acquire Input Data
The method you use to acquire the credit card data is up to the developer and outside the scope of this document. However, it is worth noting that the security of the payment details from the browser is the developers responsibility. The developers responsibility starts when the entry form is given to the browser, and ends when the call to the external gateway is made. The methods to ensure security, i.e. access to a secure server, are provided by Netregistry with all hosting packages that include payment processing.

Stage 2 - Data Validation
While the processing library will do some input validation, it is the primary responsibility of the developer to ensure that the data passed to the processing library is accurate and is not mis-formatted. Sufficient input validation is a requirement for application approval by Netregistry.

Stage 3 - Processing Function Call
Once the data is validated, and all library calls are successful, it is possible to proceed with the External Access Server(EAS) call. What this looks like will vary depending on the language you are using.

Stage 4 - Handling the response
The specifics of the response are handled in the EAS Response section of the Perl API Specification, but to summarise, there are several return methods available, these vary in complexity and depth, but the simplest is the short return type. This will return a single word, being one of "approved", "denied", or "failed".

Depending on the response, your application should act on the approval rejection, or failure. Sufficient response handling is a requirement for application approval by Netregistry.

Stage 5 - Actions after processing
While the actions that happen after processing are up to the developer and outside the scope of this document, we would like to add a few key points.

• Credit Card Numbers - Unless you have specific permission from the user, the credit card number should be thrown away immediately and not stored. Specifically, unless you have the specific, written, permission from Netregistry, you may not, under any circumstances, store credit card numbers on our web-servers.

A Note on testing during development
One of the nice things about the external API is that your can test the application directly with the EAS while you are developing on your own servers, and it will automatically work with on Netregistry's server, without you having to change anything.

Porting and Testing

Once you are satisfied with the state of your application on your local development server, it is time to migrate the program over to Netregistry.

Porting Issues
Please ensure that you are using UNIX style carriage returns, which is a common mistake when porting from Win32 Operating Systems. If you have not used the correct directory structure for the web server, please make all the necessary changes at this point. Only once you are confident that the application is ready should you upload.

Final Testing
Once you are satisfied with the performance of the application, you are ready to have the account activated. Until the account is activated, you should not connect the application to other sections of your website.

Related topics

• eCommerce support
• eCommerce products