21. Payment Systems

21.1. Overview

Payment systems are used by Kartris to accept payment (or in some cases, a promise of payment) through the store.
Kartris supports a number of different payment systems and has a flexible open plugin architecture that allows more to be added in future. There are four broad types:

Remote – e.g. RBS Worldpay, SagePay VSP Form – these redirect customers to a secure page at the payment gateway's site, with the successful payment being communicated back to Kartris via some kind of 'callback'.
Local – e.g. SagePay VSP Direct – the customer enters card details directly into Kartris and Kartris then communicates with the payment system server-to-server. Since card details are entered through Kartris itself, SSL is obligatory.
Alternative Checkout – e.g. Google Checkout – the customer is routed to the payment system's web at the start of the checkout and stays there for the entire process, with information such as pricing and shipping options, as well as payment success/failure communicated between the payment system and Kartris using server-to-server communication. Although the card details are not entered directly into Kartris, Google Checkout still requires that all communication between Kartris and the payment system be done under SSL.
Special – this typically describes certain payment methods through Kartris that don't require a third party payment system. For example, payment by 'PO' (purchase order – to take an order where actual payment will be invoiced or made offline).

21.1.1. Payment Gateway - Common Settings

There are some settings which are common to most payment systems in Kartris.

21.1.1.1. Status

This lets you switch the operation of the payment system as follows:

ON – the payment system is active and is available for customers to select for payment
OFF – the payment system is disabled
TEST – the payment system is set in test mode; it will only be visible at checkout if you are logged in as a store admin. Orders will be passed with a 'test' flag so cards will not be billed.
FAKE – an additional test setting; this simulates an order callback without sending anything to the payment gateway. It is a useful way to test the settings and see what happens with successful orders but without having to repeatedly go through the payment stage on the remote site.

21.1.1.2. Process currency

Most payment systems have a process currency. If you leave this blank, Kartris will pass orders to the payment system in whatever currency the user selects on your site. For that to work, your payment system provider must support multiple currencies, and your account with them must permit orders in all the currencies available on your site.

You should set the process currency from blank, if:

Your payment system account only supports one currency
Your store offers customers a choice of at least one currency that your payment system account does not support
Your payment system provider provides very poor currency conversion rates, so you prefer to pass all orders in a single currency as customers will get better conversion rates from their credit card providers.

The process currency (if not blank) should be a three-letter ISO code for the appropriate currency.

Customers will be alerted at the last step of the checkout that the actual amount they will pay will be converted, and they will be shown the converted amount in that currency, as well as the order total in their preferred currency. This conversion will be done at the rate in your currency settings.

21.1.1.3. Encrypting the settings file

The settings for each payment system is stored in an XML file. This is given a .config extension so that the file contents can not be read across the web if the exact path to the file is typed into a browser. For additional security, it is advisable to encrypt this file using the checkbox provided once your site is going live.

21.1.2. Installing Further Payment Systems

Kartris is designed to allow new payment systems to be added without changing code or making changes to the database.

Unzip the files and copy the folder for the payment system to the 'Plugins' folder in the Kartris web. Then go to 'Configuration > Payment and Shipping Gateways'.

Click the 'Refresh' link and Kartris should find the new payment system. Once in the list, you can click 'Edit' to change its settings. Each payment system has its own settings, which vary from system to system. This information is not stored in the database; instead it is stored as XML within the payment system itself. This makes installation simpler since you don't need to add new database records for each new payment system.

If you receive an error when you try to save changes to the settings of a payment system, it is most likely caused by there not being 'write' permission to the 'Plugins' folder. You will need to adjust this from the 'properties' dialog in Windows Explorer, or (if on shared hosting) contact your host's technical support team.

21.2. 2Checkout

2Checkout is a popular online payment service. Its primary feature is that it is easy and quick to setup an account and start receiving orders, and that it is available to companies and individuals in most countries.

21.2.1. Setup within Kartris

Go to Configuration > Payment and Shipping Gateways and click to edit 2Checkout.
For 'friendly name', you can enter '2Checkout', or just simply 'Credit Card'. This is just the name of the payment method that customers will get to choose on the web site during checkout if you have multiple payment methods.
Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' invokes a demo order, allowing you to test the full integration and pass multiple orders at zero cost without needing to do refunds. 'FAKE' means that Kartris will skip the 2Checkout site and instead format a post back itself to the callback page of Kartris. This is useful for testing that the callback process works, triggers the appropriate emails and so on without keep having to keep going through the 2Checkout payment process.
Set your 'SID', which is the vendor number assigned to you by 2Checkout.

21.2.2. Setup within 2Checkout

In order to ensure that 2Checkout calls back your Kartris site to notify it that a payment for a particular order was made so that confirmation mails can be sent and the order can be tagged as 'paid', you need to set up a few things within your 2Checkout account.

Login to 2Checkout and go to Account > Site Management.
The 'Approved URL' will be http://www.mysite.xyz/Callback-2checkout.aspx and the 'Direct Return' should be set to 'Immediately return to my web site'.

2Checkout should now be set up and working. We would advise that you always test a site in live mode when you first open it (status = 'ON') even if all the test modes checked out ok. This confirms that everything is working with Kartris and that your account with 2Checkout is live and working. The best way is to create a low value product of a dollar which you can purchase.