SPI - General Civil Aviation Authority Publications/Airworthiness Notices... · Following piece of code creates a SPI.Connection object and then assigns that connection to a properly

SPI .NET

Integration Guide Version 1.0

Awais Bin Khalid

Etisalat – SPI .NET Version: 1.0

Integration Guide to Store Payment Interface

Confidential Etisalat, 2008 Page 2

Revision History Date Version Description Author

10/28/2007 1.0 Initial document Awais Bin Khalid

12/4/2007 1.1 Addition for integration with asp.net 1.1 Awais Bin

Khalid




Table of Contents

1. Introduction 4

2. Installation Prerequisites 5

2.1 Required Items 5

3. Configuration Utility 6

3.1 Testing Connections 6 3.2 Test Configuration Data 7 3.3 Saving Configuration Data 9 3.4 Using „SPI .NET‟ 11

3.4.1 Add reference to SPI.net 11 3.4.2 Setting Connection Configuration in code. 12 Required fields 12

3.5 Error Handling 13 3.5.1 Error Codes of SPI .NET 13

4. SPI Sample 19




Integration Guide

1. Introduction

The purpose of this document is to describe the details of SPI .NET and procedures required to configure and use SPI.NET with any application.

The following document assumes that the person installing the setup is a qualified .NET developer, with extensive knowledge of web and windows development environment. Familiarity

with C# language is minimum requirement to understand this document.




2. Installation Prerequisites

SPI .NET is currently supported both for .net 1.1 and .net 2.0. To be able to use either of them, you need

appropriate version of dotNet installed on your machine.

2.1 Required Items

1. .NET Framework version 1.1 is a prerequisite for SPI.net for dotNet 1.1. (download it here.)

2. .NET Framework version 2.0 is a prerequisite for SPI.net for dotNet 2.0. (download it here.)

NOTE: To use SPI.net with .NET version 1.0. Please contact IPG Customer support for SPIx, which

supports development with older version of .NET.

http://www.microsoft.com/downloads/details.aspx?FamilyId=262D25E3-F589-4842-8157-034D1E7CF3A3&displaylang=en

http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en




3. Configuration Utility

1. Configuration utility helps your configure SPI .NET for your application.

NOTE: To Test SPI .NET properly, you need to run SPI Configuration Utility with user credentials

of application that will use it. For example, if your application runs with „Application_User‟, Press Shift and Right click „Configuration Utility‟ and click „Run as‟ and select that user to run the

configuration Utility.

3.1 Testing Connections

First test for IPG Integration is to check connectivity with IPG Server.

There are two IPG address i) IPG Demo

ii) IPG Production

Click on „Test Connections‟ button to test connectivity with IPG Servers. i) It will first try to resolve IPG addresses. In case issue happens at this stage, this clearly

implies „DNS Server‟ error. Please make your server have connectivity with DNS machine. ii) It will try to open connection with IPG machine port specific ports. In case of failure, it will

display error. Error at this stage usually happens because of firewall issues.




3.2 Test Configuration Data

To configure for sample testing, you need to specify following details. i) IPG Server - demo or production

ii) Port of IPG Server - Secure port = 2443, Insecure port = 2080(available on demo only) iii) Card Number – Sample Card = 999 000 000 000 003

iv) Expiry month – Select any

v) Expiry year – Select any vi) Currency – AED

vii) Language – English or Arabic or Technical viii) Customer – „Demo Merchant‟

Clicking on „Test‟ Button allows you to test complete cycle of „Authorization‟ request to IPG. Failure in such attempt, will allow „Merchant‟ to figure out pending issues to be resolved.




Any issues with connectivity or success will be shown as Messages at bottom of utility, whereas, any

issue with Configuration and Data, will be shown in detail as RequestCode and RequestClass.




3.3 Saving Configuration Data

Once merchant successfully tests settings, they can generate Xml settings for configuration file. This configuration can be merged in their application configuration file, or web configuration file, to be loaded

by SPI .net.




After clicking „Create Web Config‟ button, a dialog will show up with output xml as shown below.




3.4 Using ‘SPI .NET’

To add SPI.net to a project, following steps are to taken. Please note that only “.NET 2.0” or above

application can use SPI.net.

3.4.1 Add reference to SPI.net

By right clicking, website in Solution-Explorer and clicking on „Add reference‟, browse and select SPI.dll;

this will copy the SPI.dll to „Bin‟ of ASP.NET web site.




3.4.2 Setting Connection Configuration in code.

SPI.net allows you to load configuration from two sources i) Configuration file

ii) In code

3.4.2.1 Configuration File

Required fields

<?xml version="1.0" encoding="utf-8" ?> <configuration>

<appSettings> 

<add key="IPG_Connection_Address" value="demo-ipg.comtrust.ae"/>

 <add key="IPG_Connection_Certificate_Path"

value="D:\projects\IPG\Code\SPISample\Certificates\Demo Merchant.pfx"/> 

<add key="IPG_Connection_Certificate_Password" value=""/>

 <add key="IPG_Connection_IsSecure" value="True"/>

 <add key="IPG_Connection_Port" value="2443"/>

 <add key="IPG_Connection_TimeOut" value="120"/>



<add key="IPG_Customer" value="Demo Merchant"/> 

<add key="IPG_Store" value=""/> 

<add key="IPG_Terminal" value=""/>

 <add key="IPG_Language" value="en"/>

 <add key="IPG_Channel" value="Web"/>

</appSettings>

</configuration>

NOTE: Above mentioned configuration is a sample. Please modify it as per your configuration.

No. Field Description

1. IPG_Connection_Address Address of IPG server e.g. Demo IPG, IPG Production

2. IPG_Connection_Port Port of IPG Server

3. IPG_Connection_IsSecure State of SSL connection. Setting it, will make SPI to connect with IPG on secure socket.

4. IPG_Connection_TimeOut Timeout of connection to IPG Server. Please note that this

timeout can‟t be less than or equal to 5 seconds.

5. IPG_Connection_Certificate_Path Path to certificate file.

6. IPG_Connection_Certificate_Password Password of certificate file. Please note that this password

is encrypted. This password is generated by „SPI Configuration utility‟. Specifying plane text password will

result in error.

7. IPG_Customer OPTIONAL : Customer name




8. IPG_Store OPTIONAL : Customer store

9. IPG_Terminal OPTIONAL : Customer store terminal

10. IPG_Language OPTIONAL : language of error output

11. IPG_Channel OPTIONAL : channel of customer e.g. Web, USSD etc

3.4.2.2 In Code

Following piece of code creates a SPI.Connection object and then assigns that connection to a properly assigned SPI.Payment object.

SPI.Connection conn = new SPI.Connection(); conn.Address = "demo-ipg.comtrust.ae"; // address of IPG

conn.Port = 2443; // port of IPG conn.CertificatePath = "C:\\Certificate\\Demo Merchant.pfx"; // path of certificate

conn.CertificatePassword = "1234"; // plain text password of certificate conn.IsSecure = true ; // sets SSL state

conn.TimeOut = 120; // in seconds

// create SPI object

SPI.Payment spi = new SPI.Payment(false); // passing 'false' will create SPI object without loading configuration

spi.Initialize(requestType, "1.0"); // initialize SPI object spi.Connection = conn; // set connection property after initialization

3.5 Error Handling

There are two places an error can occur, while using SPI.

i) On – Merchant Side SPI throws Exception with error information, whenever an improper input is specified by Merchant. This

allows Merchant to fully test their application before deploying it on production.

SPI.SPIException is the class that represents all exceptions thrown by SPI. It contains following

properties to assist handling error.

Name Description

Message Gives detail of what exactly went wrong

ErrorCode Represents ErrorCode that occurred. ErrorCode is an

enumeration, that includes all possible error cases.

3.5.1 Error Codes of SPI .NET

All error codes are represented by an enumeration „ErrorCode‟. Developer should check on „ErrorCode‟ Property of SPIException class to handle error properly.

Code Name Description

9001 PropertyValueInvalid A null or empty value can't be set as a property

value.

9002 PropertyNotSet Property being accessed is not set.

9005 ConnectionTimeout A Connection timeout occurred, while communicating with IPG. Please either increase




timeout, or make sure connection speed with IPG is

acceptable.

9008 ConnectionUnableToReadCertificate An error occurred, while adding Customer certificate to Connection, please make sure certificate is valid,

and Root chain is available at server.

9012 ExecuteNotCalled Execute method is not called. Please make sure 'Excecute' method is called before accessing this

property.

9013 PropertyIsReadOnly Property can't be set. Properties, such as 'ResponseCode' can only be returned by IPG and

are read only.

9014 InitializeNotCalled SPI should be initialized before any other operation.

9015 SPIVersionFormatInvalid Version format not recognized. It should be #.# where '#' represents a digit.

9016 RequestNameInvalid Request Name is invalid. Please make sure it

doesn't contain whitespace and starts with a character, not digit.

9017 PropertyNameInvalid A null or empty value can't be set as a property

name. Please make sure it doesn't contain whitespace and starts with a character, not digit.

9023 MahcineKeyStoreAccessDenied User doesn't have access to machine keystore.

Please give Application User, rights to MachineKeyStore.

9024 CertificateFileNotFound Certificate file doesn't exist or user doesn't have

permission to access the certificate file.

9029 ConnectionError A generic error occurred while creating connection for IPG.

9055 ConnectionNotSet Connection property not set. Please initialize

Connection by setting Connection property of SPI object.

9056 CertificateNotActiveYet Specified certificate is not valid. It's 'NotBefore' date

is still in future.

9057 CertificateExpired Specified certificate is Expired. Please contact IPG

Customer Support to acquire new certificate.

9058 CertificatePasswordInvalid Certificate password is invalid. If SPI is loading configuration, then make sure it's properly

encrypted in configuration file. Use SPI

configuration utility, to encrypt the password and then place it in configuration file.

9070 ConnectionConfigurationError An error has occurred while loading Connection

properties from application configuration file. Please make sure that properties are specified properly.

9071 IPGUrlInvalid Url of SPI connection is not proper. Please configure

'IPG_Connection_Address' properly.

9072 IPGAccessSecurityError User doesn't have rights to open connection with

IPG. Please make sure, current user have enough

rights to open connection on Internet.

9073 ConnectionTimeOutInvalid Timeout specified to connection to IPG is invalid.

Please specify a timeout of more than 5 seconds for

proper response.




ii) On – IPG Server Side

If SPI encounters any error on IPG-Server side, it will return without throwing an exception, and will

return with a proper „ResponseCode‟ which will contain „0‟ as sign of Success, or an „ErrorCode‟ to signify error. Following are the error codes range that SPI will return to signify error. Other error ranges, relate

to error on IPG or bank side.

Code Name Description

9010 ResponseXMLError XML returned IPG is not proper. Please make sure your connection was not abrupted.

9011 ResponseParseError An error occurred while parsing XML returned by IPG.

9018 EmptyResponse IPG has returned an empty response.

9032 SendDataError A generic error has occurred, while sending data to

IPG.

9036 RecvDataError A generic error has occurred, while receiving data from

IPG.

9050 PostDataLengthOutOfRange Length of the data being posted is out of range. Please try reducing data, or give the application more memory

space.

9051 Send_ProtocolViolationError Protocol violation Exception occurred while sending data i.e TCP/IP communication was interrupted

9052 Send_WebConnectionError Exception occurred while communicating at HTTP level.

This happens when Secure data is sent over non-SSL port, or vice versa.

9061 Receive_ProtocolViolationError Protocol violation Exception occurred while receiving

data i.e. TCP/IP communication was interrupted.

9062 Receive_WebConnectionError Exception occurred while communicating at HTTP level. This happens when Secure data is sent over non-SSL

port, or vice versa.

3.5.2 Certificate Configuration For .NET 2.0, no specific configuration of certificate is required.

For .NET 1.1, certificate needs to be added to „Computer Account‟ of Certificate store. Following steps

need to be followed to add certificate,

1. Open Microsoft Management console, by opening „mmc.exe‟ from Run command. 2. Click on File menu, and then click on Add Remove Snap-in.




3. Click on „Add‟ and select ‘COMPUTER Account’ and then press Ok. 4. Go to Personal/Certifcates section of store, and right click and select „All task‟ and then select

„Import‟. Follow instructions to add certificate.

Certificate also needs to be added to „Local User‟ of Certificate store. Following steps need to be followed




to add certificate,

1. Open Microsoft Management console, by opening „mmc.exe‟ from Run command. 2. Click on File menu, and then click on Add Remove Snap-in.

3. Click on „Add‟ and select ‘My User Account’ and then press Ok. 4. Go to Personal/Certifcates section of store, and right click and select „All task‟ and then select

„Import‟. Follow instructions to add certificate.




4. SPI Sample (.NET 1.1)

SPI sample consists of following files.

No. File Name Description

1. bill.htm Initial page that contains sample data to be posted to IPG

2. Register.aspx Register pages, starts the registration of a sample transaction

with IPG and then redirects to IPG

3. Finalization.aspx After specifying data on IPG, IPG processes it, and redirects to this page. In case of successful transaction, it shows success

message with info.

4. Identity.aspx This page displays current user name, which is being used to run the website. This user should have access to certificate to

able to connect to IPG.

5. SPI.dll SPI.dll contains the logic for SPI

6. Demo Merchant.pfx This is a sample certificate for „Demo Merchant‟ customer,

which is used for testing purposes only.

7. Web.config It contains basic configuration of website and necessary configuration of SPI.

Following steps needs to be taken to run SPI Sample.

i) Configure SPI Sample as an ASP.NET 1.1 website on IIS 6.0 or above. ii) Change web.config to update path of certificate and its password.

iii) Add the „Demo Merchant.pfx‟ certificate to „Computer Account’ certificate store. iv) Add the „Demo Merchant.pfx‟ certificate to „Current User’ certificate store.

v) run the website and access page „Identity.aspx‟. This will display website credentials. Please

note down the credential for later reference. vi) Website account should be the user used to set the certificate in „current user certificate

store‟ and he should also have access to certificate file of „Demo Merchant.pfx‟. vii) Now, run „bill.htm‟ page (Make sure that the URL of website containing bill.htm

doesn’t have ‘localhost’ in it. Access ‘bill.htm’ using ip address or name of server.).

You should be able to be redirected to IPG Common payment page. a. Select card type „IPG‟

b. Specify card „999 000 000 000 011‟ c. Specify expiry year as 2010, month as January.

d. Proceed viii) You should be able to see „Finalization.aspx‟ page with success status.




6. SPI Sample (.NET 2.0)

SPI sample consists of following files.

No. File Name Description

1. bill.htm Initial page that contains sample data to be posted to IPG

2. Register.aspx Register pages, starts the registration of a sample transaction

with IPG and then redirects to IPG

3. Finalization.aspx After specifying data on IPG, IPG processes it, and redirects to this page. In case of successful transaction, it shows success

message with info.

4. Identity.aspx This page displays current user name, which is being used to run the website. This user should have access to certificate to

able to connect to IPG.

5. SPI.dll SPI.dll contains the logic for SPI

6. Demo Merchant.pfx This is a sample certificate for „Demo Merchant‟ customer,

which is used for testing purposes only.

7. Web.config It contains basic configuration of website and necessary configuration of SPI.

Following steps needs to be taken to run SPI Sample.

ix) Configure SPI Sample as an ASP.NET 2.0 website on IIS 6.0 or above. x) Change web.config to update path of certificate and its password.

xi) run the website and access page „Identity.aspx‟. This will display website credentials. Please note down the credential for later reference.

xii) Website account should also have access to certificate file of „Demo Merchant.pfx‟.

xiii) Now, run „bill.htm‟ page (Make sure that the URL of website containing bill.htm doesn’t have ‘localhost’ in it. Access ‘bill.htm’ using ip address or name of server.).

You should be able to be redirected to IPG Common payment page. a. Select card type „IPG‟

b. Specify card „999 000 000 000 011‟

c. Specify expiry year as 2010, month as January d. Proceed

xiv) You should be able to see „Finalization.aspx‟ page with success status.

Documents

SPI - General Civil Aviation Authority Publications/Airworthiness Notices... · Following piece of code creates a SPI.Connection object and then assigns that connection to a properly