Who should be reading this document?

The target audience for this document is intended for partners who are willing to undertake source code modification under license from CitiXsys to pursue customisations.

This document provides a complete overview of payment processors, their integration methodology in iVend Retail as well as a guide to implementing a new payment processor.

Sample Code

Refer to the attached code for adding a new payment gateway to iVend.

What are Payment Processors?

They allow a merchant to process (authorise and capture) credit card transactions over networks in a secure manner.

A series of steps are involved in the life cycle of a payment processor where a  payment request is sent out through the iVend POS terminal to the issuing bank, verification and authorisation at the credit card  interchange network (VISA, AMEX etc.), and a response is received back at the initiator (i.e. POS) denoting success or failure of a payment.

An initial request with the customer and card details is submitted in a secure fashion to the Payment Gateway. Upon merchant account verification the request is routed to the appropriate Payment Processor.

The verified Merchant Bank Processor posts the transaction for settlement in the merchant bank account against the consumer’s credit card account. The payment is simultaneously submitted to the interchange as well.

The Credit Card Interchange is the link between credit card issuing banks and acquiring banks. This is the process by which the card is cleared and processed between all the entities participating in the transaction i.e. merchant bank processor, credit card issuers, etc. This includes the processing, clearing and settlement of credit card transactions including the assessment and collection and/or distribution of fees between parties. Interchange systems are maintained by both MasterCard and Visa.

The successful transaction is then transferred to the credit card issuing bank that verifies fund availability in the customer’s credit card account. The results are sent back through.

The credit card issuing bank passes the approved transaction results back to the Credit Card Interchange network.

The credit card interchange relays the transaction results to the Merchant Bank’s Processor.

The Merchant Bank’s Processor relays the transaction results back to the payment gateway.

A preformatted response is sent back by the Payment Gateway to the POS terminal i.e. the merchant. Transaction results are stored and displayed to the consumer.

The approved transaction amount is deposited by the Credit Card Interchange in the Merchant’s Bank account.

Types of Payment Transactions supported in iVend Retail

Card Present Transactions

Consumer must present a physical credit card when making payments for goods

The POS terminal captures the card data from the card including the card number, expiration date and counterfeit detection value to the Card Issuer for authorisation

Card data can be captured manually i.e. keyed in or electronically i.e. from authorised card readers (Magnetic Stripe Readers)

Additionally, PIN Pads are supported at POS terminals for PIN debit using PCI PTS (Pin Transaction Security) compliant hardware.

Card Not Present Transactions

A face-to-face contact with the Cardholder is not required.

Mail Orders (MO), Telephone Orders (TO) and Electronic Commerce (EC) transactions are typical examples

Two verification processes are used for these transactions:

• Card authorisation using the Cardholder billing address (AVS)

• Card authentication using the Card Verification Value 2 (CVV2 / CVC2 / CID)

Integration of Payment Processors in iVend

iVend is completely written in Microsoft .NET

The Payment Processor design and implementation is modular.

Formal tie-ups with multiple Payment Gateways / Processors - 17+ processors are integrated.

Each Processor has its own API (Application Programming Interface)

Processors based on universal payment processing standards. Differ primarily on ‘Request-Response’ payload structure.

Authentication and Authorisation processes are similar across all processors. The order and number of parameters may differ.

It is possible to add a new payment processor. However, these are based on a set of specifications.

Add a new Payment Processor

Checklist

A Visual Studio.NET 2010 license for development

A DevXpress 10.1.4 (or higher) license for development

Contractual agreement with the third party Payment Processor provider e.g. Authorize.NET

Test environment (test merchant account) for testing the developed Payment Processor

Familiarity with Micorosft.NET development language, tools and technologies

Salient steps for creating a Payment Processor

Create a new project in Visual Studio 2010 (with SP1).

Ensure that the Assembly Name and the Default Namespace starts with ‘CXS.Payments.<ProviderName>’ where <ProviderName> is the actual name of the provider e.g. AuthorizeDotNet.

Make sure that the settings of the project are similar to the details shown in the sample illustration below:

Add references to the following iVend Retail libraries:

· Add references to the following DevXpress libraries:

· Ensure that the following system libraries are already referenced:

Change the name of the default class from ‘Class1.cs’ to ‘AuthorizeDotNetPaymentSystem.cs’.  

Double click the class to open the code editor.

Ensure that the class includes the following namespaces:

using System;

using System.Text;

using System.Windows.Forms;

using System.Xml;

using CXS.Payments.Core;

using CXS.Platform.Globalization;

using CXS.Platform.Runtime;

using CXS.Platform.Xml;

using System.IO;

using System.Net;

using System.Collections.Specialized

Inherit the interface ‘IPaymentSystem’ and implement the interface.

Add your custom implementation logic to the interface members.

Include the sample ‘ConfigInfo.cs’ class as it is, into the project and change the namespace appropriately. This class is used by the payment processor to set required properties for the processor being implemented. (Note: The properties are defined on the basis of specifications given by the provider of the payment processor e.g. AuthorizeDotNet)

Include the sample ‘CXSPaymentsAuthorizeDotNet.global.xml’ file in your project and ensure that the XML file is included as an embedded resource as shown below:

The naming convention of the XML file is: ‘<ClassName>.global.xml’ where the class name is the name of the only implementation class in the project that inherits the ‘IPaymentSystem’ interface. For the sake of this example, the class is named ‘AuthorizeDotNetPaymentSystem’ and hence the name of this XML file is ‘AuthorizeDotNetPaymentSystem.global.xml’

Under the root element/node ‘String’ there are only two header level elements as shown below:

The ‘SetupControl’ element is a predefined/fixed name while the other element i.e. ‘AuthorizeDotNetPaymentSystem’ is named exactly as the actual implementation class.

Child elements under the ‘SetupControl’ element refer to the properties of the user control in the project representing the user interface elements. For example, assuming that the user control has the following fields defined:

The corresponding elements and their values in the ‘SetupControl’ node would be:

· Child elements under the ‘AuthorizeDotNetPaymentSystem’ element contain the error information for the specific provider. For the sample processor, the sub-elements and their values are:

You should change the element names and their values as appropriate when adding your own payment processor.

· The iVend Retail product embeds the graphical elements of each payment processor individually. This means that every payment processor must create the user interface part as well, along with the code logic of the payment processor.

This control is known throughout the product as the ‘SetupControl’ that uses the ‘XtraVerticalGrid’ control of the DevXpress Suite for building the user interface.

· The elements mentioned in the ‘AuthorizeDotNetPaymentSystem.global.xml’ file are mapped exactly to the row editor properties of the DevXpress ‘XtraVerticalGrid’ control as illustrated below.

To build a user interface for the new payment processor include the sample  ‘SetupControl.cs’ file and ensure that it inherits from the ‘BasePaymentsSetupView’ class and the ‘IGlobalizeControl’ interface.

Add program initialisation routines in the constructor and override the ‘SetupView’ method to bind the grid to the data source. Call the ‘FireDone’ method in the ‘OkButtonClickHandler’ event to raise and bind the event.

Build the project and ensure that there are no compile time errors.

Use the sample test project to configure and test the developed processor with the ‘Test Merchant Account’. Change the configuration element values in the ‘ProcessorConfig.xml’ file as shown below:

Execute the test project to bring up the ‘Test Project’ form. Enter valid card details, the transaction amount and select the appropriate ‘Transaction Type’ options to test each transaction type.

Select the ‘Debit Card’ tab and re-enter valid values when testing for a debit card type processor. Verify the results using the administration console of the test account and ensure that the transactions are PA-DSS compliant.

Deploy and configure the tested processor in iVend Retail using the Management Console. Open the setup screen by clicking on the ‘Payment Processor’ menu – go to: Administration > Retail Configuration > Payment Processor and press [F3 New] to configure a new Payment Processor in iVend.

Ensure that the assembly for the processor is copied into the ‘Install’ location of iVend Retail. 

Then in the Payment Processor setup screen, enter the following:

· Unique Code for the Payment Processor

· Enter a Description.

Check whether the Payment Processor is a Mobile Processor or not, in our example, leave this unchecked.

Select the Account Type from the drop down list.

Then select the Payment Processor from the drop down list, e.g. AuthorizeDotNet.

The Assembly Name and Class Name values will then be populated automatically by iVend based on the selection made in the Payment Processor field.

Depending on the Payment Processor type, additional configuration may be required via the [Config] button – parameters for these settings will be supplied by the Payment Processor Gateway provider and will differ depending on the provider service.

Click on the [Ok] button to complete the processor setup. Restart all iVend applications for the new processor to load and activate the configured processor.

List of Payment Processors supported in iVend

The most popular processors have already been integrated with iVend. Check the following list before embarking on creating a new Payment Processor because it may already be available – It is also recommended to check with iVend Support for the most current listing as new Payment Processors are added to the list of supported processors on a regular basis:

For updated information on the  supported payment gateways please refer to Article KB0010294.

Best Practices

iVend is PA-DSS certified. Ensure that you meet the minimum guidelines for adding a custom Payment Processor: