dotnet api developer guide 20100222 - st.george bank · the st george bank .net client api enables...

Internet Payment Gateway

.NET API Developer Guide

St.George Bank - A Division of Westpac Banking Corporation

API Developers Guide - .Net

Table of Contents Overview ................................................................................................................................................................. 3 Disclaimer ............................................................................................................................................................... 3 Confidentiality.......................................................................................................................................................... 3 Document Purpose / Intended Audience................................................................................................................... 3 Related Documents ................................................................................................................................................. 3

1 Introduction................................................................................................................................................................4 2 Installation .................................................................................................................................................................6

2.1 Webpay.NET Client API Dependencies......................................................................................................... 6 3 Testing your Installation............................................................................................................................................7

3.1 St. George Bank Specific Information and Files ............................................................................................. 7 3.2 The St. George Bank Base Test Program...................................................................................................... 7

3.2.1 Installing the Test Program............................................................................................................................7 3.2.2 Supplying Input to the Test Program..............................................................................................................7 3.2.3 Analysis of the Response..............................................................................................................................8 3.2.4 Troubleshooting............................................................................................................................................8 3.2.5 Network Errors..............................................................................................................................................9 3.2.6 Unexpected Errors While Testing ..................................................................................................................9

4 Additional Information.............................................................................................................................................10 4.1 Security.......................................................................................................................................................10 4.2 Performance ...............................................................................................................................................10 4.3 Connectivity ................................................................................................................................................10 4.4 Test/Live Merchant Status ...........................................................................................................................10 4.5 Session and Concurrency Issues .................................................................................................................10

5 Webpay.NET Client API Reference ..........................................................................................................................11 5.1 Configuring Your Development Environment ................................................................................................11 5.2 Error/Exception Handling .............................................................................................................................14

6 Sample Applications................................................................................................................................................15 6.1 ASP.NET Web Application...........................................................................................................................15 6.2 Windows Forms Application.........................................................................................................................17

7 Technical Support....................................................................................................................................................18 7.1 IPG Web Site....................................................................................................................................................18 7.2 Contacting St. George Bank ..............................................................................................................................18 Appendix A – Files included in this Developer Kit .....................................................................................................19



Overview

Disclaimer This document, including attachments, is not for general circulation, but for distribution to a limited number of specific corporations and individuals that are known to St. George Bank (“Company”). It is in draft form and its contents are subject to change, including changes of substance. Any person choosing to act on information contained in this document is advised to verify the information.

Confidentiality By accepting this document, the recipient agrees to keep the information contained in it permanently confidential. This document is intended for use by the recipient only and may not be copied, reproduced or distributed to others at any time without the prior written consent of the Company. It cannot be used for any purpose except that for which it is given to you i.e. as user documentation.

If you do not agree with any of the above conditions, you must return this document immediately.

Document Purpose / Intended Audience This guide is one component of the St. George Bank Transaction Server document set. It intended to act a reference point for developers seeking to implement the St. George Bank transaction functionality into merchant web applications. It provides specific technical information about the typical deployment of the St. George Bank .NET API and delivers valuable insights into more user-specific deployments.

It is assumed that the parties implementing this API will be experienced in implementing web applications in a .Net development environment, and this document is written principally toward parties with this expertise

Related Documents St. George Bank Generic API Developer Guide

o St. George Bank Win32 Developer Guide

o St. George Bank Java Developer Guide

o St. George Bank Perl Developer Guide

o St. George Bank Linux Developer Guide

o St. George Bank PHP Developer Guide



1 Introduction The St George Bank .NET API is a Windows-based dynamic link library containing methods for use with the St George Internet Payment Gateway (IPG). The St George Bank .NET Client API enables web site and application developers to efficiently add credit card transaction processing capabilities to their products.

The St George Bank .NET API can be used in Windows-based applications in using any language supported by .NET Framework 1.1. It supersedes all prior versions of the Webpay OCX and ATL controls, except for the Webpay Win32 library, which is still supported for use in unmanaged C/C++ Applications.

This document should be used in conjunction with the St. George Bank Generic API Developer Guide document, which includes details on parameters required for credit card transactions, implementation guidelines and a list of response codes.

This document also includes common configuration settings, test applications and protocols, and sample code that will assist developers in incorporating the API into their chosen application.

Communication between the St George Bank API and St George Bank Transaction Server Gateway uses SSL connectivity through server addresses and defined ports.

NOTE: If your application is located behind a firewall or proxy server, you should ensure that the relevant addresses and ports are not being filtered or blocked.

It is important to note that the St. George Bank Transaction Server utilises two distinct transaction-processing environments. These environments are defined as LIVE and TEST. The LIVE environment connects directly to the live banking processing system and performs real-time transactions. The TEST environment is a simulated environment controlled within the transaction server that effectively mimics the live processing environment; TEST is principally used for integration testing and training.

Using the parameters provided by your St. George Bank representative, you must define and test your application and API integration against the TEST environment to ensure compliance.



1.1 System Requirements The following system configuration is required for implementation of the St. George Bank .NET API.

Operating System Desktop (Stand Alone) Applications – XP, 2000 & 2003 (32bit)

Batch application or non online transactions (nothing including a Website IIS not required)

Website or Client/Server Applications - 2000 Server and 2003 Server only (32bit)

(Serving ECommerce sites)

NOTE:

64bit Operating systems are not supported

Win NT/95/98/ME are not supported

Windows XP Professional is required to run ASP.NET

Microsoft Windows 2000 – SP-4 required

Microsoft Windows XP – SP-2 required

. Net Framework 1.1 or greater

Processor Pentium III

Processor Speed 800Mhz

Memory Desktop Applications: 256MB

Server Applications: 512MB

Compiler (for sample applications)

Visual Studio .NET 2003

Please note:

The .Net API has been certified for a machine built exactly as above and is not supported for any other

configurations. For support - please ensure the above requirements have been met

It is assumed that the parties implementing this API will meet the above requirements and be experienced in implementing web applications in a .Net development environment, and this document is written principally toward parties with this expertise

Please run/use the “test” application within the API before programming your own page to ensure the API is correctly configured and communicating with the bank. St George support the API working on the PC using the test examples – we do not support any additional coding

FULL Root Admin access is required to install and program the API. A “shared/reseller” environment is not supported in any way.



2 Installation Before installing the API, please check that your system meets the system requirements listed in Page 5.

Do you have connectivity to the gateway? Launch a browser session on the machine the API is installed on and type in

URL http:// www.gwipg.stgeorge.com.au:3006 for Live

URL http:// www.gwipg.stgeorge.com.au:3007 for Test

If you can see the 5 squares, you can reach the gateway.

Installation is delivered as an InstallShield program that contains all the necessary components including sample source code and supporting assembly files.

The InstallShield provides a simple point-and-click process that installs all files into the appropriately specified locations.

NOTE: The St. George Bank .NET Assembly is NOT placed in the Global Assembly Cache.

Please run/use the “test” application within the API before programming your own page to ensure the API is correctly configured and communicating with the bank. St George support the API working on the PC using the test examples – we do not support any additional coding

2.1 Webpay.NET Client API Dependencies The St. George Bank .NET Client API relies upon a .NET assembly file named Org.Mentalis.Security.dll. This assembly file should be placed in the same directory as the Webpay.dll file. Ordinarily, when you build an application using Visual Studio .NET, copies of both Webpay.dll and Org.Mentalis.Security.dll will be placed with your executable or dll in the bin directory.



3 Testing your Installation 3.1 St. George Bank Specific Information and Files Your St. George Bank representative will supply you with information and files specific to the St. George Bank Gateway you will be using. This includes:

The address of the St. George Bank Transaction Server Gateways (www.gwipg.stgeorge.com.au)

The Test (and Live) Gateway port numbers. Test (3007) and Live (3006)

NOTE: If your application is located behind a firewall or proxy server, you should ensure that the relevant addresses and ports are not being filtered or blocked.

Your St. George Bank Client ID

A St. George Bank client certificate file (e.g., “net.pfx”) appropriate for your St. George Bank gateway and the password protecting this certificate file

NOTE: For security purposes, the certificate file and the password will be provided to you separately.

You must place the St. George Bank client certificate file somewhere on your machine so that the St. George Bank client software can access it. It is recommended that you place the file in the same folder with all your other St. George Bank client files or with other files that make up your own application.

3.2 The St. George Bank Base Test Program Important: Please run/use the “test” application within the API before programming your own page to ensure the API is correctly configured and communicating with the bank. St George support the API working on the PC using the test examples – we do not support any additional coding Sample code for a basic test program is included with all API (.NET, Java, etc.) development kits. You should run this test program to ensure that:

The basic St. George Bank Client library has been installed There are no other basic connectivity problems with your machine

See the troubleshooting section of this guide for more information.

3.2.1 Installing the Test Program InstallShield will install two sample/test applications into the specified folder.

The first of these is a Windows Forms application written in VB.NET, and is called Webpay.NET-VBSample. This application can be launched via the shortcut added to the Start Menu. The source code for this application has also been provided – please see section 5 for information on the sample applications.

The second is an ASP.NET Web Application written in C#, demonstrates how to implement the Webpay.NET Client API in a web application, and includes all necessary transaction status checking logic. Also included is the user session tracking logic that is essential for preventing duplicated transactions and ensuring that a response will be available to the user if a page fails to load due to network or other issues.

3.2.2 Supplying Input to the Test Program As stated earlier, one test program is a Windows Forms Application written in Visual Basic. The screenshot on the following page shows the program’s main interface, consisting of 3 groups of input boxes, and a text area that will display the results of the transactions. In order to process a transaction, you will need to set:

Connection Settings – i.e. - “Servers” = www.gwipg.stgeorge.com.au & Port = Test (3007) and Live (3006)

Identification Settings – i.e. – Client ID = your 100XXXXX Number; Certificate = net.pfx path (press select) & Password = password supplied for Net.pfx

to values specified by your Service Provider. The default values in the Transaction Parameters section should be sufficient to test basic setup and connectivity.



NOTE: The test may take some time to establish the first SSL connection but subsequent transactions should complete more quickly.

After completing a transaction, output similar to the following should appear in the “Results” window:

3.2.3 Analysis of the Response Response Code A two-digit code used to determine success or failure. The code number matches the

response text field. “00”, “08” generally designates an Approved transaction, although this may vary between service providers. Response codes are contained in the Creditcard Transactions Specifications document.

Response Text A meaningful text message that explains the response code Error Message Any errors received Transaction Reference A unique reference number generated for each transaction.

3.2.4 Troubleshooting If your output fails any of the tests above, please review the steps you have taken so far. The following questions may assist in determining common connection problems:

Is the Webpay.dll assembly file in the same directory as your executable?

Is the Org.Mentalis.Security.dll file in the same directory as your executable?

Is the right location of the client certificate file specified? You may need to specify the file’s full path.

Is the password correct for the client certificate?

Is the correct address and test port number specified for the St. George Bank gateway? You may want to use “nslookup” or “dig (domain information groper)” to ensure that the address resolves correctly.

Are you behind a firewall? You may need to contact your Security Administrator to ensure the appropriate ports have been defined through the firewall.

If you still can’t identify the problem, call your St. George Bank representative. Be prepared to e-mail the output of the test program.



3.2.5 Network Errors Commercial and freeware tools can be found on the Internet to assist you in testing your network connectivity to the St. George Bank Secure Transaction Servers.

3.2.6 Unexpected Errors While Testing In some cases, the system may return errors when you are expecting an approved or other code during testing. Please check the response code you receive against those contained in the IPG Response Code Table document.

Some response codes may be generated at any time and this behaviour is perfectly normal. For example, the System may return the code A6 for Server Busy if several other merchants are conducting load tests at the same time.

Before reporting errors, ensure that you are able to replicate them, so that our support team can diagnose properly.



4 Additional Information 4.1 Security The St. George Bank Transaction Server maintains secure transactions through the use of SSL (Secure Sockets Layer). The SSL Handshake Protocol was originally developed by Netscape Communications Corporation to provide security and privacy over the Internet. Using SSL, we can provide client and server authentication, and ensure 128-bit encryption of all transaction details.

4.2 Performance The St. George Bank Transaction Servers are replicated to provide high availability, fail-over, and fast processing under load. The average time taken to complete a transaction is 6-7 seconds, but merchants may experience faster or slower transaction completion times due to a number of factors, including: the “distance” (or number of hops) between the merchant’s server and the St. George Bank environment, the type and speed of connection, general Internet congestion, high server load, etc. The API’s automatically manage transaction and connection timeouts.

4.3 Connectivity Depending upon the implementation, a number of gateways may be utilised for communication with the Client APIs. This implementation ensures maximum connection and system failover. The API may be directed to all gateways, and if the first is unavailable, the next gateway in sequence will be contacted. This is defined by including each gateway address separated by a comma.

4.4 Test/Live Merchant Status St. George Bank provides a Test and a Live system for merchant use. The Test system is a mirror of the Live system, with the exception that it sends the requests to a simulated banking environment.

Initially, you will need to develop and test your code using the test system. When you believe you are ready to “Go Live”, you must contact the St. George Bank Support Team to begin the accreditation process.

The St. George Bank Servers produce a wide range of transactional responses. Within the testing regime, these responses are controllable through the allocation of the cents component in the amount value. To fully test your system’s ability to handle and control varying responses, you should test all cents values between 00 and 99.

A complete list of all Creditcard response codes is contained in the IPG Response Code document.

Contact the St. George Bank Support team for the current Server parameters required when using the Test and Live systems.

4.5 Session and Concurrency Issues When implementing the St. George Bank .NET API, it is important to consider the effect of multiple users accessing your application concurrently. A new transaction context should be created for every transaction, to provide a mechanism for maintaining a user’s session, which will allow each transaction instance to be processed only once.

The sample ASP.NET web application shows one possible way of managing user sessions to prevent lost or duplicate transactions.



5 Webpay.NET Client API Reference Detailed documentation on the classes, functions, methods and methods that the St. George Bank .NET Client API provides is installed on your system in both HTML and Compiled HTML Help (CHM) formats. The Compiled HTML Help document can be viewed in the standard Microsoft Windows Help Viewer by clicking the link installed on your Start menu. This document is located in the St. George Bank .NET Installation folder and is called Documentation.chm.

If the computer you installed the St. George Bank .NET Client API to has Internet Information Services installed, you will also be able to view the HTML help through your web browser by going to:

http://localhost/Webpay.NET-CSharpSample/docs/index.html

For information on Credit Card transactions and parameters, see the separate IPG Response Code document.

5.1 Configuring Your Development Environment As stated earlier the webpay.dll file is not deployed to the Global Assembly Cache (GAC). Consequently, in order to utilise the St. George Bank .NET Client API, you will need to add a reference to it in your Visual Studio project. Follow the steps below to add a reference to the webpay.dll file:

NOTE: This has task already been performed for both Sample Applications

1. Within the project you are adding the reference to, right click on “References” and select “Add Reference”



2. Click the “Browse” Button, and locate the webpay.dll file in your installation directory. The file will appear in the “Selected Components” section.



3. Click “OK” to close the “Add Reference” Window. If you expand the “References” node of your project in the Solution Explorer, you will see a new reference called “webpay”.



5.2 Error/Exception Handling The St. George Bank .NET API handles all errors internally. Any errors encountered during processing cause the transaction to fail. Error messages are viewed by investigating the ERROR field.

If a transaction attempt fails and a Transaction Reference has been returned by the St. George Bank Servers, the execute method will automatically query the status up to three more times. Beyond this, execute fails, and the transaction reference is available to the application. The merchant’s application should be enabled to query the status of such a transaction, and be able to do so at any time. Both sample applications provided include status-checking logic.

The following diagram depicts the transaction protocol implemented.

ClientWebpay

TransactionGateway

Transaction Request Message

Response with Transaction Reference

Reply with Confirmation of Transaction Reference

Status Request /Responses

Transaction Reply containg results of the Transaction

Transaction Protocol



6 Sample Applications The samples included here illustrate two common implementation types using the most basic scenarios possible and contain several hard-coded values. They are intended only to demonstrate the basic concepts involved in using the St. George Bank .NET Client API in a manner that is relevant to the ways in which the API is normally used. Your production application will need to collect user or other input, and log the transaction responses to a database and/or display them to users.

Two sample Visual Studio .NET Projects have been grouped in a VS.NET Solution, which can be loaded by clicking the link on the Start Menu. The first of these applications is an ASP.NET Web Application; the second is the Windows Forms Test application described in Section 3 of this document. The sections below describe these applications further.

6.1 ASP.NET Web Application This application, written in C#, demonstrates how to implement the St. George Bank .NET Client API in a web application, and includes all necessary transaction status checking logic. Also included is the user session tracking logic that is essential for preventing duplicated transactions and ensuring that a response will be available to the user if a page fails to load due to network or other issues.

If you are running Microsoft Internet Information Services (IIS) on the computer you have installed the development kit on, the application is automatically installed as a virtual directory in IIS, and will be accessible when you open the “Webpay.NET Samples” Solution file. If you do not have IIS installed, you will need to copy the Project Folder from the installation directory to a computer, which does have IIS installed, and re-add the project to the solution. Please consult the Visual Studio Documentation for instructions on how to add an existing Web Project.

The project consists of a basic HTML start page, which has links to the Payments Page, and to the installed API documentation in HTML format, and three ASP.NET pages used for processing and display.

The C# code has been implemented with the aim of being as straightforward as possible, and as such contains many hard-coded parameters, which your application should load either from a .NET XML configuration file or a database, depending on how flexible an application you require. These parameters include the Service Provider’s server address and port settings, certificate location and password, and your Client ID.



NOTE: The connection and authentication settings are located in the PaymentPage.aspx.cs file. Default values are used to test basic setup and connectivity (Client ID = 100xxxxx; Host = www.gwipg.stgeorge.com.au; Port = 3007). To change these values to your site-specific values, you must edit this file and recompile the project.

Please see the below C# code extract for configurable parameters that need to be set:

"10000000", "c:\\net.pfx", "webpay" = your client ID – certificate path and certificate password

"webpaytest" = www.gwipg.stgeorge.com.au

3007 = Port number – i.e – 3007 = Test and 3006 = Live

"CLIENTID", "10000000" = your client ID

private void buyButton_Click(object sender, System.EventArgs e)

{

//Set the following values appropriately for your Bank/Service Provider

String responseURL = "";

//To avoid processing duplicate payments, for this user, check the

if ( Session.Contents[ "WEBPAYOBJECT" ] == null )

{

webpay.client.Webpay w = new webpay.client.Webpay( "10000000", "c:\\cert.pfx", "webpay" );

Session.Contents[ "WEBPAYOBJECT" ] = w;

responseURL = processPayment( w );

}

Response.Redirect( responseURL );

}

private String processPayment( webpay.client.Webpay w )

{

System.Random randObj = new System.Random( 5325 );

w.setServers( "webpaytest" );

w.setPort( 3007 );

w.setValue( "CLIENTID", "10000000" );

w.setValue( "INTERFACE", "CREDITCARD" );

w.setValue( "TRANSACTIONTYPE", "PURCHASE" );

NOTE for Windows Server 2000:

The sample application running under IIS uses the ASP.NET Machine Account. As such, read permission to the net.pfx certificate must be granted to this account. The default location of this file should be c:\net.pfx.

NOTE for Windows Server 2003:

If you are running IIS 5.0, then the ASP.NET Machine Account must be given read permission to the net.pfx file.

If you are running IIS 6.0; but in IIS 5.0 Isolation mode, the same is true.

However, is you are running IIS 6.0 in Worker Process Isolation Mode, then the IIS_WPG account must be given read access to the net.pfx file. The isolation mode is set on the Service tab of the Web Sites Properties page.



6.2 Windows Forms Application This application, written in Visual Basic .NET, demonstrates the implementation of the St. George Bank .NET Client API in a normal Windows GUI. Like the Web Application, it also contains the logic necessary for automated status checking in the event of a processing error. However, since it is a single threaded, single user application, it does not contain session management logic.

This project consists of only one Windows Form, as shown below. All parameters are driven by the user through the input boxes provided – in a normal end-user application, the connection and identification parameters would normally be loaded from a configuration file, possibly with a separate “Options” form loaded from a Menu. It would also be necessary to add logic for obtaining input from another part of the program, a database or external process and appropriately handling the transaction results.



7 Technical Support

7.1 IPG Web Site The complete suite of API documentation and software is available from https://www.ipg.stgeorge.com.au. Please visit/check this site often as any notices, upgrades, new API versions and documentation changes will be made available there.

7.2 Contacting St. George Bank Before reporting errors, ensure that you are able to replicate them, so that we are able to diagnose properly.

Be prepared to have available for the Helpdesk or e-mail the following information:

Operating system + API type (i.e. – W2003 + .Net API)

Basic Hardware description (i.e. – P3 800 + 512 meg RAM)

Debug logs & Log file containing the values of all fields in the transaction

Description of the error (when and how it happened)

Error code and Error message

The St. George Bank Technical Support Team can be contacted in the following ways:

Telephone via the St. George EFTPOS Helpdesk 1300 650 977

Email to: [email protected]

On-Line at https://www.ipg.stgeorge.com.au



Appendix A – Files included in this Developer Kit NOTE: The certificate file (eg. net.pfx) for this is not included in the kit. For security purposes, this file will be supplied separately.

Documentation

Documentation.chm Programming help.

Base libraries

Webpay.dll The .NET API Dynamic Link Library.

Org.Mentalis.Security.dll Security Dynamic Link Library.

VB.NET Test

Webpay.NET-VBSample.exe VB.NET Test Program

C:\Program Files\eFunds\Webpay .NET Client API\Webpay.NET-VBSample

VB.NET Source for Test Program

Webpay.NET-VBSample.vbproj Project file for VB.NET Test Program

C# ASP Test

http://localhost/Webpay.NET-CSharpASPSample/ C# ASP Test Program

C:\Program Files\eFunds\Webpay .NET Client API\Webpay.NET-CSharpASPSample

C# ASP Source for Sample Program

Webpay.NET-CSharpASPSample.csproj Project file for C# ASP Sample Program

Visual Studio .NET 2003

Webpay.NET Samples.sln Solution file for sample programs