Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Multiple changes (see changelog)

  • Loading branch information...
commit 59b4d41d2fe76621d4a0b211a6dbe42a8092e0ec 1 parent f3e6427
Daniel Tenner authored
6 CHANGES.textile
@@ -0,0 +1,6 @@
+h1. Changelog for Peeves
+ - Switched configuration to use <code>mattr_accessor</code> instead of constants
+ - Updated <code>simulate.rb</code> to contain configuration, instead of <code>lib/peeves/config.rb</code>
+ - Updated README.
13 LICENCE.txt
@@ -0,0 +1,13 @@
+Copyright 2009 Daniel Tenner
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+See the License for the specific language governing permissions and
+limitations under the License.
111 README.textile
@@ -1,17 +1,114 @@
-h1. Protx VSP Server
+h1. Peeves - PVS - Protx VSP Server
h2. Introduction
+Peeves is a library for accessing the Protx VSP Server. Its patterns are loosely modeled on "ActiveMerchant":, for clarity (unfortunately AM doesn't support the VSP Server mode of operation). Peeves was built for an application called "Woobius":, but is released free of charge (and free of any warranties) to the community in the hope that it will be useful.
+Using the Protx VSP Server enables you to not have to host payment pages on your own site. You initiate a transaction, then forward the user to the page returned by Protx, and the rest is handled off-site. This has many benefits, in particular not needing to implement credit card validation pages yourself, not needing to handle credit card numbers directly (which means that you're automatically PCI-DSS compliant), and not needing to deal with 3D-secure yourself.
Protx is an UK payment gateway. You can find more information on their VPS Server service "here":
-h2. Setup and Installation
+h2. Licence
+The initial version of Peeves was written from scratch by Daniel Tenner. It is loosely based on ActiveMerchant's patterns, but all code is original, and is licenced under the "Apache Licence":
+As a user, this means you can effectively use Peeves for whatever you want so long as you agree not to sue people about it.
+As a contributor, it means that you licence to Peeves any contributions that you make as per the Apache licence.
+h2. Kicking the tyres
+After setting up your IP address in the VSP Simulator, and obtaining a valid simulator vendor name, temporarily edit <code>simulate.rb</code> with your *vendor name* and run:
+ ruby simulate.rb
+Everything should work. If it doesn't work, try asking me (swombat) for help on freenode, channel #flails.
+Assuming everything worked fine, revert your change to simulate.rb.
+h2. Usage
+h3. Configuration
+In each environment file, you want to do something like this:
-Edit <code>lib/peeves/config.rb</code> with your *vendor name*.
+ PEEVES_VENDOR = "woobius"
+ PEEVES_GATEWAY_MODE = :simulator
+The gateway mode can be set to <code>:simulator</code>, <code>:test</code>, or <code>:live</code>.
+Then, in environment.rb, do:
-Test it by running
-ruby simulate.rb
+ Peeves::Config.vendor = PEEVES_VENDOR
+ Peeves::Config.gateway_mode = PEEVES_GATEWAY_MODE
+h3. Making a request
+As per <code>simulate.rb</code>:
+ transaction_reference = Peeves::UniqueId.generate("TEST")
+ customer_data = => 'blah',
+ :firstnames => 'blah',
+ :address1 => 'blah',
+ :address2 => 'blah',
+ :city => 'blah',
+ :post_code => 'blah',
+ :country => 'gb',
+ :email => ''
+ )
+ # Payment registration
+ payment_response = p.payment(, "GBP"),
+ {
+ :transaction_reference => transaction_reference,
+ :description => "Test Transaction",
+ :notification_url => "",
+ :customer_data => { :billing => customer_data,
+ :delivery => customer_data,
+ :email => }
+ })
+This will register a payment and return a url that you should forward the user to.
+Once the user has made the payment on the Protx VSP Server pages, you will receive a callback at the URL you defined as <code>:notification_url</code>. You should call something like the following on the parameters that you receive back:
+ def record_response_params(params)
+ returning PeevesGateway.parse_notification(params) do |response|
+ self.update_attributes(
+ :last_status => response.status,
+ :last_status_detail => response.last_status_detail,
+ :vps_transaction_id => response.vps_transaction_id,
+ :transaction_authorisation_number => response.transaction_authorisation_number,
+ :status_3d_secure => response.status_3d_secure,
+ :code_3d_secure => response.code_3d_secure
+ )
+ end
+ end
+In response to this, you must send back a success message or the transaction will eventually be cancelled by Protx:
+ render :text => PeevesGateway.response(PeevesGateway::APPROVED, url, "Payment succeeded")
+Protx will then forward the user to <code>url</code>, where you can display a happy success page.
+h3. Keeping abreast of changes
+I've just started a changelog - see "CHANGES.textile":
+h2. Contributing back
+Please use the fork functionality on github to make a fork and then push back your changes to the fork queue. I will probably accept most useful changes, but it might take me a few days before I get around to it!
4 lib/peeves/config.rb
@@ -1,6 +1,6 @@
module Peeves
module Config
- VENDOR = "xinzheng"
- GATEWAY_MODE = :simulator
+ mattr_accessor :vendor
+ mattr_accessor :gateway_mode
2  lib/peeves/protx_response.rb
@@ -44,7 +44,7 @@ def verify!
# TODO: Make this work, currently fails all
md5 =
md5 << "#{self.vps_transaction_id}#{self.transaction_reference}#{self.status}#{self.transaction_authorisation_number}" +
- "#{Peeves::Config::VENDOR}#{self.avs_cv2_result}#{self.security_key}#{self.address_result}#{self.post_code_result}" +
+ "#{Peeves::Config.vendor}#{self.avs_cv2_result}#{self.security_key}#{self.address_result}#{self.post_code_result}" +
raise Peeves::Error, "MD5 appears to have been tampered with! (#{md5.hexdigest} != #{self.vps_signature})" unless md5.hexdigest == self.vps_signature
4 lib/peeves_gateway.rb
@@ -27,7 +27,7 @@ class PeevesGateway
- def initialize(mode=Peeves::Config::GATEWAY_MODE)
+ def initialize(mode=Peeves::Config.gateway_mode)
@mode = mode
@@ -274,7 +274,7 @@ def add_common(type)
@post =
@post["TxType"] = type
@post["VPSProtocol"] = VPS_PROTOCOL
- @post["Vendor"] = Peeves::Config::VENDOR
+ @post["Vendor"] = Peeves::Config.vendor
def add_post_processing(options)
10 simulate.rb
@@ -1,12 +1,16 @@
require 'rubygems'
require 'activesupport'
-# require 'ruby-debug'
$LOAD_PATH << "lib"
ActiveSupport::Dependencies.load_paths = $LOAD_PATH
+Peeves::Config.vendor = "woobius"
+# END
+Peeves::Config.gateway_mode = :simulator
p =
transaction_reference = Peeves::UniqueId.generate("TEST")
Please sign in to comment.
Something went wrong with that request. Please try again.