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).

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

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.

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.

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.

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.

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.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit 2Checkout.
  2. 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.
  3. 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.
  4. Set your 'SID', which is the vendor number assigned to you by 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.

  1. Login to 2Checkout and go to Account > Site Management.
  2. 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.

2Checkout does support multiple currencies, but its conversion rates are quite poor. Furthermore, it stores currencies in US Dollars. So a merchant based in the UK who chooses to receive payments in GBP will see these converted to USD for storage. If the merchant chooses to receive payment in GBP, the USD amount will then be converted again to GBP for the wire transfer.

To avoid losses in currency conversion, we recommend only using US Dollars for 2checkout - encourage your customers to pay in USD (their credit card company will convert at a better rate than the one 2Checkout would present to them) and have 2Checkout wire the money to you in USD, for your bank to convert to local currency.

AuthorizeNet is a leading payment system. It is primarily US-oriented. AIM stands for 'Advanced Integration Method' - it is a local-type payment gateway, where customers enter card details directly into the checkout page of your Kartris. For this reason, you must have SSL on your site.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit AuthorizeNet AIM.
  2. For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card with AuthorizeNet'.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the AuthorizeNet payment process 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 test payment process.
  4. ProcessCurrency - Typically AuthorizeNet accounts are single-currency, so you should enter this as a three-letter ISO code, for example 'USD'.
  5. Test URL - (for test orders) should be:
    https://test.authorize.net/gateway/transact.dll
  6. Post URL - (for live orders) should be:
    https://secure.authorize.net/gateway/transact.dll
  7. TransactionKey - This is the transaction key which is generated on the AuthorizeNet back end system. It is used in the generation of the MD5 hash. If this does not match the one on the back end of AuthorizeNet, transactions will not be accepted by AuthorizeNet.
  8. LoginID - Should be provided to you with your AuthorizeNet account details.
  9. TransactionType - One of the following (see AuthorizeNet documentation for further details): AUTH_CAPTURE, AUTH_ONLY, PRIOR_AUTH_CAPTURE, CAPTURE_ONLY, CREDIT, VOID

Some configuration to your account must be done at Authorize.Net's Web site (Authorize.Net will have supplied you with access details). This is referred to as Authorize.Net's Merchant Management System. Login at:

https://secure.authorize.net

Go to 'Settings and Profile', under 'Security', select 'obtain transaction key'. Enter your secret answer to obtain your key. This key must be entered in the TransactionKey setting (see {txrid:297}).

AuthorizeNet is a leading payment system. It is primarily US-oriented. SIM stands for 'Simple Integration Method' - it is a remote-type payment gateway, where customers are forwarded to a secure page on AuthorizeNet's servers to make the card payment.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit AuthorizeNet SIM.
  2. For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card with AuthorizeNet'.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the AuthorizeNet payment process 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 test payment process.
  4. ProcessCurrency - Typically AuthorizeNet accounts are single-currency, so you should enter this as a three-letter ISO code, for example 'USD'.
  5. Test URL - (for test orders) should be:
    https://test.authorize.net/gateway/transact.dll
  6. Post URL - (for live orders) should be:
    https://secure.authorize.net/gateway/transact.dll
  7. TransactionKey - This is the transaction key which is generated on the AuthorizeNet back end system. It is used in the generation of the MD5 hash. If this does not match the one on the back end of AuthorizeNet, transactions will not be accepted by AuthorizeNet.
  8. LoginID - Should be provided to you with your AuthorizeNet account details

Some configuration to your account must be done at Authorize.Net's Web site (Authorize.Net will have supplied you with access details). This is referred to as Authorize.Net's Merchant Management System. Login at:

https://secure.authorize.net

  1. Go to 'Settings and Profile' and select 'Relay Response'. Change this to the callback URL of your site, i.e. http://www.sitename.xyz.com/callback.aspx?g=authorizenetsim.
  2. Click on 'Receipt page' and 'receipt method'. This sets the page on your site that a user is returned to after finishing a transaction (normally should be http://www.sitename.xyz.com/checkoutcomplete.aspx)
  3. Set the receipt method to 'Link', and text to "Click here to return to the store", or something similar.
  4. Go to 'Settings and Profile', under 'Security', select 'obtain transaction key'. Enter your secret answer to obtain your key. This key must be entered in the TransactionKey setting (see 7. above).

Bitcoin is a radical peer-to-peer payment system that enables transactions to be made in virtual currency between any user; unlike credit cards, there are no charge-backs, transaction fees are virtually zero and there is no reliance on third party providers or infrastructure.

Bitcoin payments require simply a bitcoin alpha-numeric address; this makes them very simple to conduct, unlike credit card payments which typically require card number, expiry date, CVV codes, name, street address and so on. Kartris takes advantage of this by opening up the possibility to take 'anonymous' orders when Bitcoin is used for downloadable or digital content. Essentially, customers need not provide identifying details other than an email address (and it's easy to set up free email addresses) - it's possible to transact in the kind private way one might traditionally only be able to do in a bricks and mortar store while paying cash.

Kartris communicates with the Bitcoin client via a JSON interface. When the order is created in the checkout, Kartris contacts the Bitcoin client and tells it to generate a new payment address, which is notified to Kartris. Kartris saves the order in the database, shows the 'checkout complete' page which shows the Bitcoin payment address the customer must make payment to. This is also emailed to the customer.

Because each order generates its own payment address, it's easier to tie up incoming payments with the corresponding order. A .vbs script which can be run on a schedule checks to see what pending Bitcoin orders are in Kartris, and whether the required number of confirmations have been made yet. If they have, the script calls back Kartris to notify it. The order status is then automatically updated as 'paid'.

Kartris includes native Bitcoin support, by which we mean it can process payments using the official Bitcoin client running on your own hardware as opposed to using some third party service which will charge you a fee.

The Bitcoin client can be downloaded here:

http://bitcoin.org/en/download

We use the command-line JSON support in this client, so you must use this rather than third party clients or the cut-down versions.

The Bitcoin client must be installed on the web server where your web site is hosted, so this rules out shared hosting - you must really have your own server or virtual server.

Install the software locally on the server where your site is running. Make sure it is set to start up automatically when Windows does.

You will then need to locate the Bitcoin settings folder. This should be located here by default:

C:\Users\[username]\AppData\Roaming\Bitcoin

(where [username] is the Windows user account name)

Within this folder, there may be a file called bitcoin.conf. If there isn't you can create one and paste the following into it:

# bitcoin.conf configuration file. Lines beginning with # are comments.
 
 
 # Network-related settings:
 
 # Run on the test network instead of the real bitcoin network.
 #testnet=0
 
 # Connect via a socks4 proxy
 #proxy=127.0.0.1:9050
 
 ##############################################################
 ##            Quick Primer on addnode vs connect            ##
 ##  Let's say for instance you use addnode=4.2.2.4          ##
 ##  addnode will connect you to and tell you about the      ##
 ##    nodes connected to 4.2.2.4.  In addition it will tell ##
 ##    the other nodes connected to it that you exist so     ##
 ##    they can connect to you.                              ##
 ##  connect will not do the above when you 'connect' to it. ##
 ##    It will *only* connect you to 4.2.2.4 and no one else.##
 ##                                                          ##
 ##  So if you're behind a firewall, or have other problems  ##
 ##  finding nodes, add some using 'addnode'.                ##
 ##                                                          ##
 ##  If you want to stay private, use 'connect' to only      ##
 ##  connect to "trusted" nodes.                             ##
 ##                                                          ##
 ##  If you run multiple nodes on a LAN, there's no need for ##
 ##  all of them to open lots of connections.  Instead       ##
 ##  'connect' them all to one node that is port forwarded   ##
 ##  and has lots of connections.                            ##
 ##       Thanks goes to [Noodle] on Freenode.               ##
 ##############################################################
 
 # Use as many addnode= settings as you like to connect to specific peers
 #addnode=69.164.218.197
 #addnode=10.0.0.2:8333
 
 # ... or use as many connect= settings as you like to connect ONLY
 # to specific peers:
 #connect=69.164.218.197
 #connect=10.0.0.1:8333
 
 
 # Maximum number of inbound+outbound connections.
 #maxconnections=
 
 
 # JSON-RPC options (for controlling a running Bitcoin/bitcoind process)
 
server=1 tells Bitcoin-QT to accept JSON-RPC commands.
 #server=0
 
 # You must set rpcuser and rpcpassword to secure the JSON-RPC api
 rpcuser=Kartris
 rpcpassword=ThisShouldBeSecureAndNotThisDefaultOrYouWillGetRobbed
 
 # How many seconds bitcoin will wait for a complete RPC HTTP request.
 # after the HTTP connection is established. 
 #rpctimeout=30
 
 # By default, only RPC connections from localhost are allowed.  Specify
 # as many rpcallowip= settings as you like to allow connections from
 # other hosts (and you may use * as a wildcard character).
 # NOTE: opening up the RPC port to hosts outside your local
 # trusted network is NOT RECOMMENDED, because the rpcpassword
 # is transmitted over the network unencrypted.
 #rpcallowip=10.1.1.34
 #rpcallowip=192.168.1.*
 
 # Listen for RPC connections on this TCP port:
 rpcport=8332
 
 # You can use Bitcoin or bitcoind to send commands to Bitcoin/bitcoind
 # running on another host using this option:
 rpcconnect=127.0.0.1
 
 # Use Secure Sockets Layer (also known as TLS or HTTPS) to communicate
 # with Bitcoin -server or bitcoind
 #rpcssl=1
 
 # OpenSSL settings used when rpcssl=1
 #rpcsslciphers=TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH
 #rpcsslcertificatechainfile=server.cert
 #rpcsslprivatekeyfile=server.pem
 
 
 # Miscellaneous options
 
 # Set gen=1 to attempt to generate bitcoins
 #gen=0
  
 # Pre-generate this many public/private key pairs, so wallet backups will be valid for
 # both prior transactions and several dozen future transactions.
 #keypool=100
 
 # Pay an optional transaction fee every time you send bitcoins.  Transactions with fees
 # are more likely than free transactions to be included in generated blocks, so may
 # be validated sooner.
 #paytxfee=0.00
 
 # Allow direct connections for the 'pay via IP address' feature.
 #allowreceivebyip=1
   
 # User interface options
 
 # Start Bitcoin minimized
 min=1
 
 # Minimize to the system tray
 minimizetotray=1

This sample file comes from the Bitcoin documentation here:

https://en.bitcoin.it/wiki/Running_Bitcoin#Bitcoin.conf_Configuration_File

You can see that the majority is commented out, but the relevant lines that you need active in your file are as follows:

  • server=1 - this turns on the JSON support in the client, so Kartris can communicate with it
  • rpcport=8332 - this defines the port that will be used for remote communication
  • rpcconnect=127.0.0.1 - this defines the address at which the client is running; 127.0.0.1 is the default local network address
  • rpcuser=Kartris - a username (you can choose your own)
  • rpcpassword=ThisShouldBeSecureAndNotThisDefaultOrYouWillGetRobbed - you should define your own password here, don't use our default!!!
  • min=1 - this is not essential, it just tells the Bitcoin client to start minimized, preferably if running on your server
  • minimizetotray=1 - again, not essential, but preferable as the client starts up whenever the server reboots

Go to Configuration > Payment and Shipping Gateways and click to edit Bitcoin. You should ensure that Bitcoin is turned 'ON' (or set to TEST or FAKE for testing). Your settings should look similar to the following:

Bitcoin gateway settings

The ProcessCurrency MUST be BTC. This ensures that orders are converted to the right value in Bitcoin at checkout.

BitcoinRPCHost, BitcoinRPCPort, BitcoinRPCUser and BitcoinRPCPassword should all match the ones you configured in the Bitcoin.conf file, see 18.5.3. Setting up the Bitcoin client

The final step is to ensure that successful payments are notified to Kartris so it can update orders appropriately. To do this, we created a .vbs script. By default, this script comes in the Bitcoin plugin folder within the Kartris site zip. But you can put this anywhere on your server.

There are a number of settings within this that will need to be set. You can edit it in notepad or a similar plain text editor. A typical file might look like this:

'====================
'Kartris Database
'====================
strKartrisDBName = "k25008_test"
strKartrisDBServerName = "localhost\SQLExpress"
blnUseWindowsAuth = true
strKartrisDBUserName = "sa"
strKartrisDBPassword = "sa"
strKartrisDBPort = 1433

'====================
'Bitcoin Client - Should match with your Bitcoin payment gateway settings in Kartris
'====================
strBitcoinHost = "http://localhost"
strBitcoinPort = "8332"
strBitcoinUsername = "Kartris"  
strBitcoinPassword = "ThisShouldBeSecureAndNotThisDefaultOrYouWillGetRobbed"

'=======================
'REQUIRED CONFIRMATIONS
'Number of confirmations for bitcoin payments to be considered 'paid'
'=======================
intRequiredConfirmation = "1"

'====================
'WORKING FOLDER PATH
'Folder where the log files will be saved to
'====================
'--don't forget to put backslash at the end (\)
strWorkingFolderPath = "C:\Users\TestUser\Desktop\"
'Whether to only log confirmed payments, will not log queries for addresses that returns 0.
'*True = smaller log file size but with less details. 
blnLogConfirmedPaymentsOnly = True

'====================
'Other Settings
'====================
numCursorType = 1 'for SQL Server
strEmailMethod = "off"
strMailServer = "localhost"
strEmailFromAddress = "[email protected]"
strEmailSubject = "Summary"

In the above file, we have values for the strKartrisDBUserName and strKartrisDBPassword, but because we set blnUseWindowsAuth to true, these aren't required, so the values don't matter.

The Bitcoin client details should match those configured in the bitcoin.conf file, and the Kartris back end (see 18.5.3. Setting up the Bitcoin client and 18.5.4. Set up within Kartris above).

We have set the intRequiredConfirmation to "1". This is the number of confirmations the Bitcoin client should receive before an order is considered as successfully paid. Most Bitcoin documentation suggests waiting for 3-6 confirmations before considering a transaction as successful and irreversible, but the downside is that this will take longer. We'd suggest you start with a higher number (e.g. 6) and only reduce it if the delay becomes an issue (for most mail order items, waiting up to an hour, but normally less isn't going to make any real difference as to how quickly the customer will get their order.

You should set up a scheduled task in Windows to run this .vbs on a regular basis, we suggest every 10 minutes.

Bitcoin rates can change sharply very quickly. For this reason, you need to be particularly careful to update the currency rates on your store regularly, even several times per day. From Kartris v2.5008 onwards, the live rate feed in Kartris includes a Bitcoin rate from BCChanger.com. However, you may want to adjust this rate manually before saving to cover you for any potential movement in rates.

The order process through checkout for a customer is virtually identical to that for any other payment system. The main difference is that after placing the order, the customer is notified of the Bitcoin payment address that they need to send funds to (circled in red below):

Bitcoin customer email

The process for a store owner will be similar to that for orders using any other payment system. To check payments in the Bitcoin client directly, view the 'Receive' tab. The addresses for each order will be listed, together with the basic order information to help reconcile them with the corresponding orders in Kartris (circled in red below):

Bitcoin client

Docdata is a Netherlands-based payment provider. It supports payments using credit cards, bank transfers and iDeal.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit Docdata.
  2. For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card, bank transfer or iDeal'.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the Docdata payment process 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 test payment process.
  4. ProcessCurrency - if left blank, payments will be sent to Docdata and processed in the customer's selected currency. If you would prefer to only process Euros, you can enter EUR, and all orders will be converted to EUR at the rate set in your store at checkout before going to the payment system.
  5. PostURL_Test - (for test orders) should be:
    https://test.docdatapayments.com/ps/com.tripledeal.paymentservice.servlets.PaymentService
  6. PostURL_Live - (for live orders) should be:
    https://www.tripledeal.com/ps/com.tripledeal.paymentservice.servlets.PaymentService
  7. MerchantPassword - This is the api key password, not the password you use to login to Docdata's panel.
  8. MerchantName - The account name Docdata provide to you.

You will need to set up Docdata with details of where to send updates on the status of payments to, and whether to redirect the user to after payment. To do this, login to your Docdata account, then go to Settings > View/Edit Merchant Profile, then click the URL button near the top. You should see a form like this:

Docdata settings

The Update URL is the most important setting; this should point to the callback.aspx page on your site, for example:

http://www.mysite.xyz/callback.aspx?g=docdata&mt_id=

It's important that you leave the mt_id= at the end; Docdata will append the order ID number to this. This URL is not called in a user's browser, rather it is called directly by Docdata each time the order status is updated.

The other settings control where a user is sent immediately after payment. We suggest you create custom pages in Kartris for each, so you can design the message to show to customers. For example create pages called:

Success
Cancelled
Error
Pending

These will have the URLs as follows:

http://www.mysite.xyz/t-Success.aspx
http://www.mysite.xyz/t-Cancelled.aspx
http://www.mysite.xyz/t-Error.aspx
http://www.mysite.xyz/t-Pending.aspx

When Docdata sends updates to your Kartris site, it only sends the order ID. The web site is then required to send a request to see the updated status information for the order. The problem is that this requires the payment cluster key. In order to make this work, we therefore have an Access db within the plugin that stores cluster keys against the order ID when an order is first created, and this is then queried later when we need to find the cluster key using the order ID which Docdata sends us.

So there are a couple of things you need to ensure when setting up your site. Firstly, that the Docdata plugin folder is full permissions for the web site account, in order that it can write data to the Access db. Secondly, the site needs to run 32-bit, as it relies on 32-bit Access drivers. You can set this from IIS; find the application pool that the site is running in, view the Advanced Settings for it, and set 'Enable 32-bit Applications' to TRUE.

GP Webpay is a payment system based in the Czech Republic, providing a remote-type payment system that supports 3DS.

Please review the GP Webpay documents. You will need to create secure certificates on their admin interface before setting up your Kartris.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit GP Webpay.
  2. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a transaction will be sent to the alternative 'test' processing URL, which behaves the same as the main production URL but does not actually bill the card. 'FAKE' is another mode to aid setup and testing, Kartris itself formats an appropriate callback to itself, simulating what the remote side should pass back. It is useful for checking order emails, for example.
  3. Most of the settings will correspond to named settings provided to you by GP Webpay.
  4. The CertPFXLocalPath setting is the full local path to the .pfx file created as part of the GP Webpay account setup. If this is located on your web site somewhere, you can find the local path of the root of your Kartris installation from Database Admin > Tools. This path value should end with the name of your .pfx file.
  5. The CerfPFXPassword is the password associated with this .pfx file, not your account or any other password.
  6. The CertCerGPWebPayPublicLocalPath is the local path to the .cer file that contains GP Webpay's public cert. There is a production (live) cert, and one for the test server. Both files are included in the GP Webpay plugin folder for Kartris. You just need to find and enter the actual local path to the right file (muzo.signing_prod.cer for live transactions, muzo.signing_test.cer for test transactions to the test server).
  7. The ProcessCurrency can be left blank if you want Kartris to use whatever currency the user has chosen on the web site. Alternatively, you can set a 3 letter ISO code such as GBP or USD to force orders to be converted into that currency before processing.

IMPORTANT: Although GP Webpay uses numeric currency codes, Kartris will convert to these from the three-letter ISO codes. So you should NOT enter numeric values here, only recognized three letter currency codes. Setting the process currency is useful if your merchant account only supports one currency, or if your site has currencies available to users that your merchant account cannot handle. GP Webpay itself supports these currencies (though your merchant account may not): CZK, EUR, GBP, HUF, PLN, RUB, USD.

On most payment systems, the gateway vendor will create a new account/installation for each of your sites. However one of the attractions of GP Webpay for admins with many sites is that they can all run through a single account. One issue that results from this is regarding the uniqueness of order IDs.

Typically Kartris allocates order IDs as numbers, sequentially as orders go into the tblKartrisOrders table (which happens before orders are paid, hence actual paid order numbers might have gaps between them where orders allocated some IDs don't end up paid and finished). If you run multiple sites, these will all start numbering from 1, hence you'll have multiple sites creating IDs which might be duplicates. This will be an issue when these orders are sent to GP Webpay, as it requires all orders have a unique ID. If another of your sites previously used the same ID, GP Webpay will reject it.

The fix is relatively simple. You should adjust the 'seed' value on the O_ID field of the tblKartrisOrders table (don't from within SQL Server Management Studio), so instead of being '1' (starting numbering at 1), it is some higher value. For example, if you had three web sites, you could start one at '1' another at '1000000' and another at '2000000'. Put the numbers far enough apart that each is never likely to reach where the next starts numbering, and you should avoid your sites ever issuing the same order IDs as each other.

With just the settings above in 18.7.2. Setup within Kartris, you will get errors at checkout and in the logs see references that the crypto provider cannot find the file specified (i.e. the .pfx file), even though you have verified that the path to it is correct. For technical reasons, to access the certificate, you need to make an adjustment to the application pool that the site runs in.

  1. go to IIS Manager
  2. go to the application pool instance
  3. click advanced settings
  4. Under Process model, set Load User Profile to true
Once this is done, you should be able to checkout and reach the GP Webpay payment pages.

NETBANX is a service of a global payments company Optimal Payments PLC, which is currently based on the Isle of Man. It is a 'remote' type, UK-oriented payment gateway.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit Netbanx.
  2. For 'friendly name', you can enter 'Netbanx', 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.
  3. 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 Netbanx payment page 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 Netbanx payment process.
  4. Rather than having an account ID to identify your orders to Netbanx, it has customized payment URLs that include your site or company name. There are both test and live URLs, with the format as follows:

    https://pay.netbanx.com/OPsite-name-upp
    https://pay.test.netbanx.com/OPsite-name-upp

    Kartris will decide which one to use based on the STATUS setting for this gateway.

Netbanx will provide you with details of their admin panel. You will need to add permitted URLs to this; their gateway will only accept orders that are referred to it from these allowed URLs.

The callback also needs to be set up at Netbanx - this tells Netbanx the page to send payment success or failure messages to, so that Kartris can update the order status to show it was paid, and send confirmation mails. This should be set to:

http://www.yoursite.xyz/Callback-Netbanx.aspx

Further information to follow...

Further information to follow...

Paypal is a popular internet payment service available in most countries. At present, Kartris integrates only with Paypal Web Site Payments Standard.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit PayPal.
  2. For the 'business', enter the email address of your Paypal account - this is effectively your PayPal user ID.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that transactions will be sent to PayPal's sandbox server. 'FAKE' means that Kartris will skip the PayPal 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 PayPal payment process.
  4. If you have Kartris v2.9 or above, it will automatically determine whether to post to the live or sandbox Paypal server. If you have an earlier version of Kartris (or a Paypal DLL in Kartris earlier than 1.1.0.0) you will need to change the URL setting to the appropriate one for LIVE or test orders.

    For live orders:
    https://www.paypal.com/cgi-bin/webscr


    For test orders:
    https://www.sandbox.paypal.com/cgi-bin/webscr

In order to ensure that PayPal 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 PayPal account.

  1. Login to PayPal and go to My Account > Profile. Then click to view My Selling Preferences (left hand side) and then a bit over half way down, click the 'update' link by 'Instant payment notifications'.
  2. The Notification URL should be http://www.mysite.xyz/Callback-PayPal.aspx. The 'Receive IPN messages' radio button should be checked.
  3. Back on the My Selling Preferences page, click the 'update' link by 'Website preferences'. Turn 'Auto Return' on, and enter http://www.mysite.xyz/CheckoutComplete.aspx as the 'Return URL'. This will redirect the user back to your site after they complete a payment on PayPal. But it is important to note that the order itself is called back immediately after payment by PayPal's server calling the Callback.aspx page of your site (see 2. immediately above).
  4. Set 'Payment Data Transfer' off - we don't need this as we send info via the IPN step in 2. above.

You may find that orders where data submitted contains non-English characters (such as French or German accented characters) generate an INVALID response at PayPal. To fix this:

  1. Log into PayPal
  2. Go to My Selling Preferences (see above)
  3. Click 'Paypal Button Language Encoding' link at foot of page, and then click the 'more options' button
  4. Set 'Encoding' to 'UTF-8' 
  5. Set 'Do you want to use the same encoding for data sent from paypal to you?' to 'Yes'.
  6. Click 'Save' 
We advise doing this even if you're in the US or UK, as it's quite possible you'll have customers with names and/or addresses either domestically or overseas that contain non-English accented characters.

Google Analytics ecommerce tracking requires that a client side javascript is run the user's browser when they complete an order. This happens in Kartris on the CheckoutComplete.aspx page right after returning from the payment gateway (see 3. above).

It cannot be done on the callback because that is called by PayPal, not the customer's browser. Unfortunately PayPal puts in a 5-second delay after a completed payment before returning the customer to the store. This inevitably results in some customers dropping out after a successful payment but before they have been redirected back to your site, and hence not being logged by Google Analytics as completed sales. There is no workaround for this; the Google Analytics code can only run on the user's browser; it must run after the payment is complete (otherwise you will log sales as successful that don't complete payment) and PayPal apparently has no way to reduce or eliminate the 5-second delay). This is not a Kartris issue alone; it is an issue with all carts that support Google Analytics when they are set up to use PayPal Web Site Payments Standard.

Further information to follow...

This is a built-in payment method that can handle situations where you wish to accept orders without payment. We commonly refer to this as 'payment by PO' (purchase order); essentially a customer can check out from the site and instead of providing credit card details, you invoice them for subsequent payment (which might be by cheque, or bank transfer, or even cash).


Many companies require invoices to them include a purchase order number, so there is a field to receive this during checkout.

All payment systems have this setting, but typically it is most commonly used with the 'PO - Offline payment' system. If checked, only users who have pre-approved will see this option at checkout and hence be able to use it. This way, you can accept orders for payment later by customers who you have granted credit terms to, but new customers and others that are unapproved must make payment by credit card or another online payment system.

We would advise that even if not using the PO option on your store, you keep it set to ON but then set it as AuthorizedOnly, which will prevent the public from using it unless you specifically allow them to. This is because orders of zero value (which can occur either if some items are free, or if a coupon is used for the full value of the order) will use the PO checkout route. If you turn the PO option off, you will effectively prevent the store bypassing the payment system for zero value orders.

Realex is a popular payment system for the UK and Ireland.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit Realex.
  2. MerchantID - supplied by Realex. This is not the merchant number supplied by your bank.
  3. SharedSecret - This is supplied by Realex. It is used in the generation of the SHA1 hash. If this does not match the one on Realex, transactions will not be accepted by the gateway.
  4. ProcessCurrency - You must set this config setting to the 3 letter ISO currency code of your Realex account. For example, if your account processes Euros, this setting must be set to ‘EUR’. Setting this config setting correctly ensures that all orders will be converted to Euros prior to passing over to Realex. If you don’t set this (and your store supports multiple currencies), you will pass orders in GBP or USD to the Realex gateway, but it assume these amounts are in Euros.
  5. AutoSettleFlag - Used to signify whether or not you wish the transaction to be captured in the next batch or not. If '1', then all the transactions will automatically be settled in the next batch. If '0' it means that you will manually settle transactions after the goods have been shipped.
  6. URL - address of the secure payment page on the Realex site.
  7. ReturnTSS - Use to signify whether or not you want to use Realex’s Transaction Suitability Score. If this is '1', six additional fields will also be supplied to Realex in every transaction (shipping code, shipping country, billing code, billing country, customer id, customer email). Otherwise, set to '0'.

Before you can use Realex’s Realauth Redirect, you must first provide Realex with the URL of your callback page. This should be:

http://www.demo.xyz/Callback-Realex.aspx

(this is URL-mapped to the Callback.aspx file by Kartris)

The response URL is to be mailed to [email protected]. You can also have an HTML template uploaded to the Realex Payment servers so that the redirection should resemble the rest of the shopping experience (or else it will use Realex’s default template). You can send your template to them via same email address. For further info, check the Realex developer's guide.

In case Realauth is unable to contact your callback page, you can set a static success/failure message. This can be done at Realex's administration web site (Realex will have supplied you with access details).

It is also possible to customize the look and feel of the HTML response Realex sends to users with a template on your Kartris site. If present, this will be used to format the response Kartris sends to Realex when an order is called back. Realex then relays this HTML to the customer.

The response to Realex from Kartris is formatted using a file which should be placed here on your site:

/Skins/[your skin]/templates/Callback_Realex.html

SagePay (formerly called 'Protx') is one of the most popular credit card payment providers in the UK.

VSP Form is a remote-type payment system, where customers are sent to a secure page on SagePay's servers to conduct the card transaction.

The system is simple to set up, but is unusual compared to most remote type payment systems in that the 'callback' (relaying information on a successful payment back to the store) is achieved by redirecting the user's browser back to the store. Most payment systems make the callback themselves (their server calls the store's callback page directly), even if they subsequently send the user back to the store after payment. In theory, payments might not be notified back to your store if a user closes their browser immediately after the payment was made, but in practice, we rarely see this and the system seems stable and reliable.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit SagePay VSP Form.
  2. For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card with SagePay'.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the SagePay payment process 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 SagePay test payment process.
  4. ProcessCurrency - if your store supports some currencies that your SagePay account cannot process, you should set this with a three-letter ISO code to convert all orders to this currency prior to sending users to the payment pages.
  5. Test URL - (for test orders) should be:
    https://test.sagepay.com/Simulator/VSPFormGateway.asp
  6. Post URL - (for live orders) should be:
    https://live.sagepay.com/gateway/service/vspform-register.vsp
  7. VSPProtocol - SagePay uses a versioning system so that when a newer version of their system is introduced, you can continue to process orders with the older version (at least for some period). The Kartris SagePay support is designed for 'Protocol 2.23', so you should not change this number unless your Kartris payment system is upgraded at some point in the future.
  8. The other various SagePay settings required should be supplied to you by SagePay.

All the required information to process an order and direct the callback back to your store is actually posted through to SagePay with the order, so no further setup is required at their end. However, you should ensure with SagePay's support that your account is live before you start processing orders.

Orders passed through your SagePay account must have unique IDs. If you experience this error when trying to checkout, it means the order ID that is being passed has been used before on your account. This can happen if you've switched to Kartris from another store system, so IDs are starting from a low level. It can also happen if you restored a older backup of your Kartris database for some reason.


The simple way to fix this is to set your database so that order numbers are allocated from a much higher based (above the range of any order numbers you might previously have run through the account). In SQL Management Studio, open up the tblKartrisOrders table in design view and view the properties of the O_ID field. There is a section for 'identity'. Within this, there is a seed value, which at default will be 1. Change this to a number in the tens of thousands, or hundreds of thousands, save the table changes. From now on, orders should be allocated much higher ID numbers, and these will be passed to SagePay as order IDs.

SagePay (formerly called 'Protx') is one of the most popular credit card payment providers in the UK.

VSP Direct is a local-type payment system, where customers enter card information directly into the Kartris checkout page. It therefore requires SSL.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit SagePayDirect.
  2. For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card with SagePay'.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the SagePay payment process 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 SagePay test payment process.
  4. ProcessCurrency - if your store supports some currencies that your SagePay account cannot process, you should set this with a three-letter ISO code to convert all orders to this currency prior to sending users to the payment pages.
  5. VSPProtocol - SagePay uses a versioning system so that when a newer version of their system is introduced, you can continue to process orders with the older version (at least for some period). The Kartris SagePay support is designed for 'Protocol 2.23', so you should not change this number unless your Kartris payment system is upgraded at some point in the future.
  6. The other various SagePay settings required should be supplied to you by SagePay.

IMPORTANT: Secure Trading is no longer accepting customers on this particular implementation. We are maintaining it for legacy reasons. New customers therefore should not choose to setup an account with Secure Trading as Kartris is not compatible with the version they will require you to run.

Secure Trading delivers a fully PCI DSS compliant online payment processing solution to businesses worldwide.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit Secure Trading.
  2. For 'friendly name', you can enter 'Secure Trading', 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.
  3. 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 Secure Trading 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 Secure Trading payment process.
  4. 'Required Fields' should be set to 'name,email'.
  5. 'CallbackID' should be set to 1 if you only have a single web site. If you use your Secure Trading account with multiple web sites, you can number each of them.
  6. 'SiteReferenceID' should be set to the values provided by Secure Trading.
  7. 'Password' is an arbitrary password you use to protect the callback process; it should match the one set up in the callback.txt file (see 18.17.2. Setup within Secure Trading).

The majority of configuration for Secure Trading is contained in a number of text files that are uploaded through your Secure Trading admin area. We provide versions of these files configured for Kartris within a zip in the /Plugins/Secure Trading/ folder of Kartris. You must use these text configuration files rather than the default ones available from Secure Trading. You can remove the zip itself from your site, as it does not need to be present there.

callback.txt contains the following text:

method1	POST
url1	http://www.mydomainnamegoeshere.com/callback.aspx?g=securetrading&p=stpassword
fields1	orderref, streference, email, amount, stresult

You should edit the URL to match your site. The parameter 'g' should remain as 'securetrading' but 'p' should be set to the same 'Password' configured for Secure Trading within your Kartris back end.

If you have multiple online stores using the same Secure Trading account, you can copy these three lines of text and paste them below. The 'CallbackID' in 18.17.1. Setup within Kartris will be '1' for the site covered by the first three lines of the file, '2' for the next three lines and so on.

Remember, our callback.txt file is different to the standard one available from Secure Trading. You must use our version or your callbacks will fail.

failure.html and success.html

These files are templates for the pages displayed to a customer when making an order. These must be static HTML files, do not change them to .asp or .aspx or other active pages because the Secure Trading server will not run these.

form.html

This is the HTML template used for the credit card form that Secure Trading displays to your customers. Be very careful when editing this that you do not change any field names, remove required fields or otherwise break the form.

If you experience problems with Secure Trading, please ensure that you revert files to the ones we provide with Kartris. The most common issues we see are bugs introduced by edits to the various template files, or use of default files provided by Secure Trading.
Note: for legacy reasons, some aspects of WorldPay within Kartris are still referred to as RBS WorldPay, though WorldPay is once again independent and separately branded as simply 'WorldPay'.

  1. Go to Configuration > Payment and Shipping Gateways and click to edit RBSWorldPay.
  2. For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card with WorldPay'.
  3. Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the WorldPay payment process 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 WorldPay test payment process.
  4. ProcessCurrency - If your WorldPay account can process orders in all the currencies you have available for customers to use on the site, then you can leave this blank to process the order in whatever currency the customer is using. If you cannot process all the currencies available, you can convert all orders to a specified currency at checkout. The total will be shown to the user in both currencies, with an explanation. For example, setting this to 'GBP' will convert all orders to British Pounds at checkout.
  5. Test URL - (for test orders) should be:
    https://select-test.worldpay.com/wcc/purchase
  6. Post URL - (for live orders) should be:
    https://secure.worldpay.com/wcc/purchase
  7. AuthMode - This should be set to 'A' to authorize and bill transactions or 'E' to just authorize and hold funds (useful if you wish to do further fraud screening before accepting the payment). You will need to contact your WorldPay representative to set this facility up. Transactions can only be held unbilled for a few days before they lapse - see WorldPay’s documentation for further information. If you just hold transactions, you must login to your WorldPay admin area and manually choose to bill a transaction.
  8. InstallID - WorldPay will give you a unique number for your installation, which needs to go here.
  9. CallbackPassword - This value should match the password you set within your WorldPay account (see below)

  1. Check the 'Payment Response Enabled' box.
  2. Enter the 'Payment Response URL' as http://www.yoursite.xyz/Callback.aspx?g=rbsworldpay&d=off
  3. Check the 'Enable Shopper Response' box. This will show a text version of the order on WP.
  4. If you want to have a standard looking WorldPay confirmation page, uncheck the 'Enable Shopper Response' box. You can then customize the page returned using resultY.html and resultC.htm pages.
    http://www.worldpay.com/support/kb/bg/customisingadvanced/custa7105.html

When WorldPay calls back your site, you can send HTML to WorldPay of a response that you wish it to relay to the customer. In this way, when the customer successfully pays, they see your confirmation page on the WorldPay secure area.

For security reasons, WorldPay restricts the HTML tags that can be used in the template. Javascript and embedded objects are banned. You should refer to WorldPay documentation for more details.

The response to WorldPay from Kartris is formatted using a file which should be placed here on your site:

/Skins/[your skin]/templates/Callback_RBSWorldPay.html

Powered by tomeCMS