Kartris User Guide

17.6. Bitcoin

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.

17.6.1. Basic overview

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

17.6.2. Pre-requisites to run Bitcoin support

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.

17.6.3. Setting up the Bitcoin client

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

17.6.4. Set up within Kartris

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:
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 @17.6.3. Setting up the Bitcoin client

17.6.5. Setting up the VBS - notifying Kartris of payment

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 = "no_reply@mysite.xyz"
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 @17.6.3. Setting up the Bitcoin client and @17.6.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.

17.6.6. Currency rates

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.

17.6.7. Process from a customer perspective

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

17.6.8. Process from a store owner perspective

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):
 
powered by tomehost