spi - general civil aviation authority publications/airworthiness notices... · following piece of...
TRANSCRIPT
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
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 3
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
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 4
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 5
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 6
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 7
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 8
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 9
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 10
After clicking „Create Web Config‟ button, a dialog will show up with output xml as shown below.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 11
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 12
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> <!--Address of IPG server e.g. Demo IPG, IPG Production-->
<add key="IPG_Connection_Address" value="demo-ipg.comtrust.ae"/>
<!-- path of certificate --> <add key="IPG_Connection_Certificate_Path"
value="D:\projects\IPG\Code\SPISample\Certificates\Demo Merchant.pfx"/> <!-- encrypted password of certificate -->
<add key="IPG_Connection_Certificate_Password" value=""/>
<!-- SSL or non-SSL --> <add key="IPG_Connection_IsSecure" value="True"/>
<!-- IPG Connection port --> <add key="IPG_Connection_Port" value="2443"/>
<!-- IPG Connection Timeout value --> <add key="IPG_Connection_TimeOut" value="120"/>
<!-- (Optional) ipg customer name-->
<add key="IPG_Customer" value="Demo Merchant"/> <!-- (Optional) ipg store -->
<add key="IPG_Store" value=""/> <!-- (Optional) ipg terminal -->
<add key="IPG_Terminal" value=""/>
<!-- (Optional) ipg language --> <add key="IPG_Language" value="en"/>
<!-- (Optional) ipg channel--> <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
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 13
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
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 14
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 15
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 16
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
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 17
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 18
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.
Etisalat – SPI .NET Version: 1.0
Integration Guide to Store Payment Interface
Confidential Etisalat, 2008 Page 19
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.