solon 0.0.1

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Alastair Brunton, Daniel Turner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.textile

@@ -0,0 +1,143 @@
+h1. Solon - Sagepay VSP Server
+
+h2. Introduction
+
+Solon is a library for accessing the Sagepay VSP Server. Its patterns are loosely modeled on "ActiveMerchant":http://www.activemerchant.org/, for clarity (unfortunately AM doesn't support the VSP Server mode of operation). Solon was built for an application called "Woobius":https://www.woobius.com, but is released free of charge (and free of any warranties) to the community in the hope that it will be useful.
+
+Using the Sagepay 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 Sagepay, 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.
+
+Sagepay is an UK payment gateway. You can find more information on their VPS Server service "here":http://techsupport.Sagepay.com/vspservercustom.asp.
+
+h2. Licence
+
+The initial version of Solon 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":http://www.oss-watch.ac.uk/resources/apache2.xml.
+
+As a user, this means you can effectively use Solon for whatever you want so long as you agree not to sue people about it.
+
+As a contributor, it means that you licence to Solon 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:
+
+<pre>
+	ruby simulate.rb
+</pre>
+
+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:
+
+<pre>
+	PEEVES_VENDOR           = "woobius"
+	PEEVES_GATEWAY_MODE     = :simulator
+</pre>
+
+The gateway mode can be set to <code>:simulator</code>, <code>:test</code>, or <code>:live</code>.
+
+Then, in environment.rb, do:
+
+<pre>
+	Solon::Config.vendor 		= PEEVES_VENDOR
+	Solon::Config.gateway_mode = PEEVES_GATEWAY_MODE
+</pre>
+
+h3. Making a request
+
+As per <code>simulate.rb</code>:
+
+<pre>
+	transaction_reference = Solon::UniqueId.generate("TEST")
+	customer_data = Solon::CustomerData.new(:surname => 'blah',
+	                                         :firstnames => 'blah',
+	                                         :address1 => 'blah',
+	                                         :address2 => 'blah',
+	                                         :city => 'blah',
+	                                         :post_code => 'blah',
+	                                         :country => 'gb',
+	                                         :email => 'customer@email.com'
+	                                        )
+
+	# Payment registration
+	payment_response = p.payment(Solon::Money.new(1000, "GBP"),
+	              {
+	                :transaction_reference => transaction_reference,
+	                :description           => "Test Transaction",
+	                :notification_url      => "http://callback.example.com/process_stuff",
+	                :customer_data         => { :billing  => customer_data,
+	                                            :delivery => customer_data,
+	                                            :email    => customer_data.email }
+	              })
+</pre>
+
+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 Sagepay 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:
+
+<pre>
+	def record_response_params(params)
+    returning SolonGateway.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
+</pre>
+
+In response to this, you must send back a success message or the transaction will eventually be cancelled by Sagepay:
+
+<pre>
+	render :text => SolonGateway.response(SolonGateway::APPROVED, url, "Payment succeeded")
+</pre>
+
+Sagepay will then forward the user to <code>url</code>, where you can display a happy success page.
+
+h3. Repeat transactions
+
+Sagepay VSP Server wouldn't be worth much without repeat transactions. Here's an example of how to use them (this code sits on an Invoice class in Woobius):
+
+<pre>
+  def pay_from(previous_invoice)
+    response = SolonGateway.new.repeat(Solon::Money.new(self.currency_amount, self.currency),
+      {
+        :transaction_reference                    => self.reference,
+        :description                              => self.description,
+        :related_transaction_reference            => previous_invoice.reference,
+        :related_vps_transaction_id               => previous_invoice.vps_transaction_id,
+        :related_security_key                     => previous_invoice.security_key,
+        :related_transaction_authorisation_number => previous_invoice.transaction_authorisation_number
+      })
+    self.update_attributes(
+      :last_status              => response.status,
+      :last_status_detail       => response.status_detail,
+      :vps_transaction_id       => response.vps_transaction_id,
+      :security_key             => response.security_key
+    )
+    if response.approved?
+      self.paid!
+    end
+
+    response
+  end
+</pre>
+
+h3. Keeping abreast of changes
+
+Things might change. If you pull the latest version of Solon and something doesn't work, check the changelog: "CHANGES.textile":http://github.com/swombat/peeves/tree/master/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!
+
+Thanks!

data/lib/solon/basket.rb

@@ -0,0 +1,15 @@
+module Solon
+  class Basket
+    attr_accessor :items
+    
+    def initialize(*args)
+      @items = args
+    end
+    
+    def to_post_data
+      "#{@items.length}:" + @items.join(':')
+    end
+
+    alias_method :to_s, :to_post_data    
+  end
+end

data/lib/solon/basket_item.rb

@@ -0,0 +1,11 @@
+module Solon
+  class BasketItem
+    attr_accessor :description, :quantity, :unit_cost_without_tax, :tax_applied, :unit_cost_with_tax, :total_cost_with_tax
+    
+    def to_post_data
+      "#{description}:#{quantity}:#{unit_cost_with_tax}:#{tax_applied}:#{unit_cost_with_tax}:#{total_cost_with_tax}"
+    end
+    
+    alias_method :to_s, :to_post_data
+  end
+end

data/lib/solon/config.rb

@@ -0,0 +1,6 @@
+module Solon
+  module Config
+    mattr_accessor :vendor
+    mattr_accessor :gateway_mode
+  end
+end

data/lib/solon/customer_data.rb

@@ -0,0 +1,16 @@
+module Solon
+  class CustomerData
+    # attr_accessor :address, :post_code, :name, :contact_number, :email
+    attr_accessor :surname, :firstnames, :address1, :address2, :city, :post_code, :country, :state, :phone, :email
+
+    def initialize(attrs = {})
+      attrs.each do |h,v|
+        send("#{h.to_s}=", v)
+      end
+    end
+    
+    def [](arg)
+      send("#{arg}")
+    end
+  end
+end

data/lib/solon/error.rb

@@ -0,0 +1,4 @@
+module Solon #:nodoc:
+  class Error < StandardError #:nodoc:
+  end
+end

data/lib/solon/money.rb

@@ -0,0 +1,10 @@
+module Solon
+  class Money
+    def initialize(amount, currency)
+      @amount = amount.to_f
+      @currency = currency
+    end
+    
+    attr_accessor :amount, :currency
+  end
+end

data/lib/solon/net/https_gateway.rb

@@ -0,0 +1,80 @@
+require 'net/https'
+
+module Solon
+  module Net
+
+    class ConnectionError < Solon::Error
+    end
+
+    class RetriableConnectionError < Solon::Error
+    end
+
+    class HttpsGateway
+
+      MAX_RETRIES = 3
+      OPEN_TIMEOUT = 60
+      READ_TIMEOUT = 60
+      
+      def initialize(url, retry_safe=false, debug=false)
+        @url        = url
+        @retry_safe = retry_safe
+        @debug      = debug
+      end
+      
+      def retry_safe?
+        @retry_safe
+      end
+      
+      def debug?
+        @debug
+      end
+      
+      def send(headers, data)
+        headers['Content-Type'] ||= "application/x-www-form-urlencoded"
+        
+        uri   = URI.parse(@url)
+        
+        http = ::Net::HTTP.new(uri.host, uri.port)
+        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = READ_TIMEOUT
+
+        http.set_debug_output $stdout if debug?
+        
+        http.use_ssl      = true
+        
+        http.verify_mode    = ::OpenSSL::SSL::VERIFY_NONE
+        
+        retry_exceptions do 
+          begin
+            http.post(uri.request_uri, data, headers).body
+          rescue EOFError => e
+            raise ConnectionError, "The remote server dropped the connection"
+          rescue Errno::ECONNRESET => e
+            raise ConnectionError, "The remote server reset the connection"
+          rescue Errno::ECONNREFUSED => e
+            raise RetriableConnectionError, "The remote server refused the connection"
+          rescue Timeout::Error, Errno::ETIMEDOUT => e
+            raise ConnectionError, "The connection to the remote server timed out"
+          end
+        end
+        
+      end
+      
+      def retry_exceptions
+        retries = MAX_RETRIES
+        begin
+          yield
+        rescue RetriableConnectionError => e
+          retries -= 1
+          puts e.inspect
+          retry unless retries.zero?
+          raise ConnectionError, e.message
+        rescue ConnectionError
+          retries -= 1
+          retry if retry_safe? && !retries.zero?
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/solon/post_data.rb

@@ -0,0 +1,11 @@
+require 'cgi'
+
+module Solon
+  class PostData < Hash
+    def to_post_data
+      collect { |key, value| "#{key}=#{CGI.escape(value.to_s)}" }.join("&")  
+    end
+  
+    alias_method :to_s, :to_post_data
+  end
+end

data/lib/solon/protx_callback.rb

@@ -0,0 +1,34 @@
+module Solon
+  class SagepayCallback < SagepayResponse
+    def initialize(response)
+      @response = response
+      if @response.is_a?(String)
+        response.split("&").each do |line|
+          key, *value = line.split("=")
+          value = value.join("=")
+          self[key] = value
+        end
+      elsif @response.is_a?(Hash)
+        response.each do |key, value|
+          self[key] = value
+        end
+      else
+        raise Solon::Error, "Cannot parse response of type #{@response.class}"
+      end
+    end
+    
+    def failed?
+      SolonGateway::FAILURES.include?(self.status.to_sym)
+    end
+    
+    def error?
+      SolonGateway::ERRORS.include?(self.status.to_sym)
+    end
+    
+    # Generic status checker method
+    def st(status_check)
+      status_check.to_s == self.status.to_s
+    end
+    
+  end
+end

data/lib/solon/protx_response.rb

@@ -0,0 +1,84 @@
+require 'cgi'
+module Solon
+  class SagepayResponse
+    def initialize(response)
+      RAILS_DEFAULT_LOGGER.debug "Sagepay response: #{response}"
+      @response = response
+      if @response.is_a?(String)
+        response.split("\r\n").each do |line|
+          key, *value = line.split("=")
+          value = value.join("=")
+          self[key] = value
+        end
+      elsif @response.is_a?(Hash)
+        response.each do |key, value|
+          self[key] = value
+        end
+      else
+        raise Solon::Error, "Cannot parse response of type #{@response.class}"
+      end
+    end
+    
+    def method_missing(id, *args)
+      id = id.to_s
+      @values ||= {}
+
+      case id[-1]
+        when 61: # :blah=
+          @values[id[0..-2].to_sym] = args[0]
+        when 63: # :blah?
+          @values.has_key?(id[0..-2].to_sym)
+        else # :blah
+          @values[id.to_sym]
+      end
+    end
+    
+    def []=(key, value)
+      self.send("#{mapping[key] || key}=", CGI.unescape(value))
+    end
+    
+    def [](key)
+      self.send("#{mapping[key] || key}")
+    end
+    
+    
+    # TODO: Make this work, currently fails all
+    def verify!
+      return self
+      md5 = Digest::MD5.new
+      md5 << "#{self.vps_transaction_id}#{self.transaction_reference}#{self.status}#{self.transaction_authorisation_number}" +
+      "#{Solon::Config.vendor}#{self.avs_cv2_result}#{self.security_key}#{self.address_result}#{self.post_code_result}" +
+      "#{self.cv2_result}#{self.gift_aid}#{self.status_3d_secure}#{self.code_3d_secure}"
+      
+      raise Solon::Error, "MD5 appears to have been tampered with! (#{md5.hexdigest} != #{self.vps_signature})" unless md5.hexdigest == self.vps_signature
+
+      self
+    end
+    
+    def approved?
+      self.status == SolonGateway::APPROVED
+    end
+
+  private
+    def mapping
+      {
+        "VPSProtocol"       => :vps_protocol,
+        "Status"            => :status,
+        "StatusDetail"      => :status_detail,
+        "VPSTxId"           => :vps_transaction_id,
+        "SecurityKey"       => :security_key,
+        "NextURL"           => :next_url,
+        "TxAuthNo"          => :transaction_authorisation_number,
+        "AVSCV2"            => :avs_cv2_result,
+        "AddressResult"     => :address_result,
+        "PostCodeResult"    => :post_code_result,
+        "CV2Result"         => :cv2_result,
+        "VendorTxCode"      => :transaction_reference,
+        "GiftAid"           => :gift_aid,
+        "3DSecureStatus"    => :status_3d_secure,
+        "CAVV"              => :code_3d_secure,
+        "VPSSignature"      => :vps_signature
+      }
+    end
+  end
+end

data/lib/solon/protx_services.rb

@@ -0,0 +1,51 @@
+module Solon
+  module SagepayServices
+    BASE_URL = {
+      :simulator  => 'https://test.sagepay.com/simulator/VSPServerGateway.asp',
+      :test       => 'https://test.sagepay.com/gateway/service/',
+      :live       => 'https://live.sagepay.com/gateway/service/'
+    }
+
+    SERVICE = {
+      :simulator => {
+        :payment      => '?Service=VendorRegisterTx',
+        :deferred     => '?Service=VendorRegisterTx',
+        :release      => '?Service=VendorReleaseTx',
+        :abort        => '?Service=VendorAbortTx',
+        :refund       => '?Service=VendorRefundTx',
+        :repeat       => '?Service=VendorRepeatTx',
+        :void         => '?Service=VendorVoidTx',
+        :manual       => lambda { raise Solon::Error, "MANUAL transactions not supported in simulator mode" },
+        :directrefund => lambda { raise Solon::Error, "DIRECTREFUND transactions not supported in simulator mode" },
+        :authorise    => '?Service=VendorAuthoriseTx',
+        :cancel       => '?Service=VendorCancelTx'
+      },
+      :test => {
+        :payment      => 'vspserver-register.vsp',
+        :deferred     => 'vspserver-register.vsp',
+        :release      => 'release.vsp',
+        :abort        => 'abort.vsp',
+        :refund       => 'refund.vsp',
+        :repeat       => 'repeat.vsp',
+        :void         => 'void.vsp',
+        :manual       => 'manual.vsp',
+        :directrefund => 'directrefund.vsp',
+        :authorise    => 'authorise.vsp',
+        :cancel       => 'cancel.vsp'
+      },
+      :live => {
+        :payment      => 'vspserver-register.vsp',
+        :deferred     => 'vspserver-register.vsp',
+        :release      => 'release.vsp',
+        :abort        => 'abort.vsp',
+        :refund       => 'refund.vsp',
+        :repeat       => 'repeat.vsp',
+        :void         => 'void.vsp',
+        :manual       => 'manual.vsp',
+        :directrefund => 'directrefund.vsp',
+        :authorise    => 'authorise.vsp',
+        :cancel       => 'cancel.vsp'
+      }
+    }
+  end
+end

data/lib/solon/unique_id.rb

@@ -0,0 +1,7 @@
+module Solon
+  class UniqueId
+    def self.generate(specific=nil)
+      "W-#{specific[0..14]}-#{Time.now.to_f}-#{'%05d' % rand(99999)}"
+    end
+  end
+end

data/lib/solon_gateway.rb

@@ -0,0 +1,397 @@
+require 'cgi'
+
+class SolonGateway
+  include Solon::SagepayServices
+    
+  APPROVED  = 'OK'
+  INVALID   = 'INVALID'
+  NOTAUTHED = 'NOTAUTHED'
+  ABORT     = 'ABORT'
+  REJECTED  = 'REJECTED'
+  ERROR     = 'ERROR'
+  ABORT_REPEATED = 'ABORT REPEATED'
+  
+  FAILURES = [:NOTAUTHED, :ABORT, :REJECTED, :ABORT_REPEATED]
+  ERRORS = [:INVALID, :ERROR]
+  
+  
+  VPS_PROTOCOL = "2.23"
+  
+  TRANSACTIONS = {
+    :payment          => 'PAYMENT',
+    :authenticate     => 'AUTHENTICATE',
+    :authorise        => 'AUTHORISE',
+    :deferred         => 'DEFERRED',
+    :refund           => 'REFUND',
+    :release          => 'RELEASE',
+    :repeat           => 'REPEAT',
+    :void             => 'VOID',
+    :cancel           => 'CANCEL',
+    :abort            => 'ABORT'
+  }
+  
+  AVS_CVV_CODE = {
+    "NOTPROVIDED" => nil, 
+    "NOTCHECKED" => 'X',
+    "MATCHED" => 'Y',
+    "NOTMATCHED" => 'N'
+  }
+    
+  def initialize(mode=Solon::Config.gateway_mode)
+    @mode = mode
+  end
+  
+  def debug=(value)
+    @no_debug = !value
+  end
+  
+  def debug?
+    @mode == :simulator && !@no_debug
+  end
+  
+  # Registers a payment so that the user can enter their details.
+  # Returns a URL that the user must be forwarded to to make the payment. If the process following this request is
+  # followed (i.e. redirect to next_url, user fills in their details, Sagepay notifies server, and server responds with OK)
+  # the settlement will go out the next day, automatically, for the full amount.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => description (required, String(100))
+  # => notification_url (required, String)
+  # => billing_data (optional, BillingData)
+  # => basket (optional, Basket)
+  # Response:
+  # => status
+  # => status_detail
+  # => vps_transaction_id
+  # => security_key
+  # => next_url
+  def payment(money, options)
+    log "payment", options
+    
+    add_common TRANSACTIONS[:payment]
+    add_registration(money, options)
+    add_customer(options)
+    add_basket(options)
+    
+    commit! :payment
+  end
+  
+  # Registers a payment so that the user can enter their details.
+  # Returns a URL that the user must be forwarded to to make the payment. If the process following this request is
+  # followed (i.e. redirect to next_url, user fills in their details, Sagepay notifies server, and server responds with OK)
+  # the settlement will NOT go out the next day. Further "Authorise" requests are required before the user will be
+  # charged.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => description (required, String(100))
+  # => notification_url (required, String)
+  # => billing_data (optional, BillingData)
+  # => basket (optional, Basket)
+  # Response:
+  # => status
+  # => status_detail
+  # => vps_transaction_id
+  # => security_key
+  # => next_url
+  def authenticate(money, options)
+    log "authenticate", options
+    
+    add_common(TRANSACTIONS[:authenticate])
+    add_registration(money, options)
+    add_customer(options)
+    add_basket(options)
+    
+    commit! :payment
+  end
+  
+  # Registers a payment so that the user can enter their details.
+  # Returns a URL that the user must be forwarded to to make the payment. If the process following this request is
+  # followed (i.e. redirect to next_url, user fills in their details, Sagepay notifies server, and server responds with OK)
+  # the settlement will NOT go out the next day, but a "shadow" will be placed on the account until the deferred payment
+  # is "Released" or "Aborted". Deferred payments are only supposed to be used to add a delay of up to 7 days, to allow
+  # cahrging at the point when the order is shipped.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => description (required, String(100))
+  # => notification_url (required, String)
+  # => billing_data (optional, BillingData)
+  # => basket (optional, Basket)
+  # Response:
+  # => status
+  # => status_detail
+  # => vps_transaction_id
+  # => security_key
+  # => next_url
+  def deferred(money, options)
+    log "deferred", options
+    
+    add_common TRANSACTIONS[:deferred]
+    add_registration(money, options)
+    add_customer(options)
+    add_basket(options)
+    
+    commit! :deferred
+  end  
+  
+  # Submits a repeat transaction.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => description (required, String(100))
+  # => related_transaction_reference (required, String(40))
+  # => related_vps_transaction_id (required, String(38))
+  # => related_security_key (required, String(10))
+  # => related_transaction_authorisation_number (required, Long Integer)  
+  # Response:
+  # => status
+  # => status_detail
+  # => vps_transaction_id
+  # => transaction_authorisation_number
+  # => security_key
+  def repeat(money, options)
+    log "repeat", options
+    
+    add_common(TRANSACTIONS[:repeat])
+    add_related(options)
+    add_registration(money, options)
+    
+    commit! :repeat
+  end
+  
+  # Authorises a previously authenticated transaction. This can be done multiple times, for amounts adding up to
+  # a maximum of 115% of the authenticated amount.
+  # => transaction_reference (required, String(40))
+  # => description (required, String(100))
+  # => related_transaction_reference (required, String(40))
+  # => related_vps_transaction_id (required, String(38))
+  # => related_security_key (required, String(10))
+  # Response:
+  # => status
+  # => status_detail
+  # => vps_transaction_id
+  # => transaction_authorisation_number
+  # => security_key
+  # => avs_cv2_result
+  # => address_result
+  # => post_code_result
+  # => cv2_result
+  def authorise(money, options)
+    log "authorise", options
+    
+    add_common TRANSACTIONS[:authorise]
+    add_related(options)
+    add_registration(money, options)
+    
+    commit! :authorise
+  end
+  
+  # Cancels a previously authenticated transaction.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => vps_transaction_id (required, String(38))
+  # => security_key (required, String(10))
+  # Response:
+  # => status
+  # => status_detail
+  def cancel(options)
+    log "cancel", options
+    
+    add_common TRANSACTIONS[:cancel]
+    add_post_processing(options)
+    
+    commit! :cancel
+  end
+
+  # Releases (processes for payment/settlement) a DEFERRED or REPEATDEFERRED payment.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => vps_transaction_id (required, String(38))
+  # => security_key (required, String(10))
+  # => transaction_authorisation_number (required, Long Integer)
+  # Response:
+  # => status
+  # => status_detail
+  def release(money, options)
+    log "release", options
+    
+    add_common TRANSACTIONS[:release]
+    add_post_processing(options)
+    @post["ReleaseAmount"]        = "%.2f" % money.amount
+    
+    commit! :release
+  end
+  
+  # Voids a previously authorised payment (only possible after receiving the NotificationURL response).
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => vps_transaction_id (required, String(38))
+  # => security_key (required, String(10))
+  # => transaction_authorisation_number (required, Long Integer)
+  # Response:
+  # => status
+  # => status_detail
+  def void(options)
+    log "void", options
+    
+    add_common(TRANSACTIONS[:void])
+    add_post_processing(options)
+    
+    commit! :void
+  end
+  
+  
+  # Aborts (cancels) a DEFERRED payment.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => vps_transaction_id (required, String(38))
+  # => security_key (required, String(10))
+  # => transaction_authorisation_number (required, Long Integer)  
+  # Response:
+  # => status
+  # => status_detail
+  def abort(options)
+    log "abort", options
+    
+    add_common(TRANSACTIONS[:abort])
+    add_post_processing(options)
+    
+    commit! :abort
+  end
+  
+  # Refunds a previously settled transaction.
+  # Options:
+  # => transaction_reference (required, String(40))
+  # => description (required, String(100))
+  # => related_transaction_reference (required, String(40))
+  # => related_vps_transaction_id (required, String(38))
+  # => related_security_key (required, String(10))
+  # => related_transaction_authorisation_number (required, Long Integer)
+  # Response:
+  # => status
+  # => status_detail
+  # => vps_transaction_id
+  # => transaction_authorisation_number
+  def refund(money, options)
+    log "refund", options
+    
+    add_common(TRANSACTIONS[:refund])
+    add_related(options)
+    add_registration(money, options)
+    
+    commit! :refund
+  end
+  
+  def self.parse_notification(params)
+    Solon::SagepayResponse.new(params).verify!
+  end
+  
+  def self.parse_callback(params)
+    Solon::SagepayCallback.new(params).verify!
+  end
+  
+  def self.response(status, redirect_url, status_detail)
+    "Status=#{status}\r\n" +
+    "RedirectURL=#{redirect_url}\r\n" +
+    "StatusDetail=#{status_detail}"
+  end
+  
+private
+  def url_for(action)
+    BASE_URL[@mode] + SERVICE[@mode][action]
+  end
+
+  def commit!(action)
+    RAILS_DEFAULT_LOGGER.debug  "Sending Sagepay post to #{url_for(action)}:\n" +
+                                "Post: #{@post.inspect}\n" +
+                                "Post data: #{@post.to_post_data}"
+    response = Solon::Net::HttpsGateway.new(url_for(action), true, debug?).send({}, @post.to_post_data)
+    Solon::SagepayResponse.new(response)
+  end
+
+  def add_common(type)
+    @post = Solon::PostData.new
+    @post["TxType"]         = type
+    @post["VPSProtocol"]    = VPS_PROTOCOL
+    @post["Vendor"]         = Solon::Config.vendor
+  end
+
+  def add_post_processing(options)
+    @post["VendorTxCode"]         = options[:transaction_reference][0..39]
+    @post["VPSTxId"]              = options[:vps_transaction_id][0..37]
+    @post["SecurityKey"]          = options[:security_key][0..9]
+    @post["TxAuthNo"]             = options[:transaction_authorisation_number] unless options[:transaction_authorisation_number].nil?
+  end
+  
+  def add_related(options)
+    @post["RelatedVendorTxCode"]         = options[:related_transaction_reference][0..39]
+    @post["RelatedVPSTxId"]              = options[:related_vps_transaction_id][0..37]
+    @post["RelatedSecurityKey"]          = options[:related_security_key][0..9]
+    @post["RelatedTxAuthNo"]             = options[:related_transaction_authorisation_number] unless options[:related_transaction_authorisation_number].nil?
+  end
+  
+  def add_registration(money, options)
+    @post["VendorTxCode"]         = options[:transaction_reference][0..39]
+    @post["Amount"]               = "%.2f" % money.amount
+    @post["Currency"]             = money.currency
+    @post["Description"]          = options[:description][0..99]
+    @post["NotificationURL"]      = options[:notification_url][0..254] unless options[:notification_url].nil?
+  end
+  
+  def add_customer(options)
+    unless options[:customer_data].nil?
+      @post["CustomerEMail"]     = options[:customer_data][:email]
+      add_billing(options[:customer_data])
+      add_delivery(options[:customer_data])
+    end
+  end
+
+  def add_billing(options)
+    unless options[:billing].nil?
+      # removed character limitation, as they should be enforced in view
+      @post["BillingSurname"]     = options[:billing].surname
+      @post["BillingFirstnames"]  = options[:billing].firstnames
+      @post["BillingAddress1"]    = options[:billing].address1
+      @post["BillingAddress2"]    = options[:billing].address2
+      @post["BillingCity"]        = options[:billing].city
+      @post["BillingPostCode"]    = options[:billing].post_code
+      @post["BillingCountry"]     = options[:billing].country
+      @post["BillingPhone"]       = options[:billing].phone
+    end
+  end
+
+  def add_delivery(options)
+    unless options[:delivery].nil?
+      # removed character limitation, as they should be enforced in view
+      @post["DeliverySurname"]     = options[:delivery].surname
+      @post["DeliveryFirstnames"]  = options[:delivery].firstnames
+      @post["DeliveryAddress1"]    = options[:delivery].address1
+      @post["DeliveryAddress2"]    = options[:delivery].address2
+      @post["DeliveryCity"]        = options[:delivery].city
+      @post["DeliveryPostCode"]    = options[:delivery].post_code
+      @post["DeliveryCountry"]     = options[:delivery].country
+      @post["DeliveryPhone"]       = options[:delivery].phone
+    end
+  end
+  
+  def add_basket(options)
+    unless options[:basket].nil?
+      @post["Basket"]             = options[:basket].to_post_data
+    end
+  end
+  
+  def log(method, options)
+    RAILS_DEFAULT_LOGGER.debug "Called #{method} with options #{options.inspect}"
+  end
+
+  def requires!(hash, *params)
+    params.each do |param| 
+      if param.is_a?(Array)
+        raise ArgumentError.new("Missing required parameter: #{param.first}") unless hash.has_key?(param.first) 
+
+        valid_options = param[1..-1]
+        raise ArgumentError.new("Parameter: #{param.first} must be one of #{valid_options.to_sentence(:connector => 'or')}") unless valid_options.include?(hash[param.first])
+      else
+        raise ArgumentError.new("Missing required parameter: #{param}") unless hash.has_key?(param) 
+      end
+    end
+  end    
+end

data/solon.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib/', __FILE__)
+$:.unshift lib unless $:.include?(lib)
+ 
+Gem::Specification.new do |s|
+  s.name        = "solon"
+  s.version     = "0.0.1"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Alastair Brunton"]
+  s.email       = ["info@simplyexcited.co.uk"]
+  s.homepage    = "http://github.com/pyrat/solon"
+  s.summary     = "Interface to Sagepay payment processor"
+  s.description = "Interface for Sagepay VSP Server only."
+ 
+  s.required_rubygems_version = ">= 1.3.1"
+  s.require_path = 'lib'
+  s.files       = `git ls-files`.split("\n")
+end

data/spec/solon_gateway_spec.rb

@@ -0,0 +1,113 @@
+require 'spec/spec_helper'
+
+describe SolonGateway do
+
+  before(:each) do
+    @p = SolonGateway.new(:simulator)
+    @p.debug = false
+  end
+  
+  describe "sending a payment request" do
+    before(:each) do
+      customer_data = Solon::CustomerData.new(:surname	=> 'blah',
+                                               :firstnames => 'blah',
+                                               :address1 => 'blah',
+                                               :address2 => 'blah',
+                                               :city => 'blah',
+                                               :post_code => 'blah',
+                                               :country => 'gb'
+                                              )
+
+      @response = @p.payment(Solon::Money.new(1000, "GBP"),
+                    {
+                      :transaction_reference => Solon::UniqueId.generate("TEST"),
+                      :description           => "Test Transaction",
+                      :notification_url      => "http://test.example.com",
+                      :customer_data         => {:billing => customer_data, :delivery =>customer_data} ,
+                    })
+    end
+    
+    it "should return a SagepayResponse" do
+      @response.is_a?(Solon::SagepayResponse).should be_true
+    end
+    
+    it "should have a vps_transaction_id" do
+      @response.vps_transaction_id.should_not be_nil
+    end
+
+    it "should have a security_key" do
+      @response.security_key.should_not be_nil
+    end
+    
+    it "should not have a transaction_authorisation_number" do
+      @response.transaction_authorisation_number.should be_nil
+    end
+  end
+
+  # commented out
+  # AUTHORISE can only be used after AUTHENTICATE, not PAYMENT
+#  describe "sending an authenticate request" do
+#    before(:each) do
+#      pending
+#      @transaction_reference = Solon::UniqueId.generate("TEST")
+#      @response = @p.authenticate Solon::Money.new(1000, "GBP"),
+#        {
+#          :transaction_reference => @transaction_reference,
+#          :description => "Test Transaction",
+#          :notification_url => "http://test.example.com"
+#        }
+#    end
+#
+#    it "should return a SagepayResponse" do
+#      @response.is_a?(Solon::SagepayResponse).should be_true
+#    end
+#
+#    it "should have a vps_transaction_id" do
+#      @response.vps_transaction_id.should_not be_nil
+#    end
+#
+#    it "should have a security_key" do
+#      @response.security_key.should_not be_nil
+#    end
+#
+#    it "should not have a transaction_authorisation_number" do
+#      @response.transaction_authorisation_number.should be_nil
+#    end
+#
+#    it "should be cancellable" do
+#      @response2 = @p.cancel({
+#        :transaction_reference => @transaction_reference,
+#        :vps_transaction_id => @response.vps_transaction_id,
+#        :security_key => @response.security_key
+#      })
+#      @response2.status.should == SolonGateway::APPROVED
+#    end
+#  end
+
+  describe "receiving a notification" do
+    before(:each) do
+      params = {
+        "Status"=>"OK", 
+        "TxType"=>"PAYMENT", 
+        "VPSTxId"=>"{861A2DB0-E734-4DEB-8F8B-12C47B9ADF3E}", 
+        "VendorTxCode"=>"W-TEST-1227524828.86576-59414", 
+        "GiftAid"=>"0", 
+        "AVSCV2"=>"ALL MATCH", 
+        "TxAuthNo"=>"8661", 
+        "VPSProtocol"=>"2.22", 
+        "CAVV"=>"MNL2CYF4URE47IQNBI6DAH", 
+        "3DSecureStatus"=>"OK", 
+        "VPSSignature"=>"49A6FA9FE0631919D9B1E72ACE57584D", 
+        "CV2Result"=>"MATCHED", 
+        "PostCodeResult"=>"MATCHED", 
+        "AddressResult"=>"MATCHED"
+      }
+      @result = SolonGateway.parse_notification(params)
+    end
+
+    it "should be able to parse the notification into a Sagepay Response" do
+      @result.is_a?(Solon::SagepayResponse).should be_true
+    end
+  end
+
+end

data/spec/spec.opts

@@ -0,0 +1,6 @@
+--colour
+--format
+progress
+--loadby
+mtime
+--reverse

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'activesupport'
+
+$LOAD_PATH << File.dirname(__FILE__) + "/../lib/"
+
+ActiveSupport::Dependencies.load_paths = $LOAD_PATH

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: solon
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Alastair Brunton
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-14 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: Interface for Sagepay VSP Server only.
+email: 
+- info@simplyexcited.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE.txt
+- README.textile
+- lib/solon/basket.rb
+- lib/solon/basket_item.rb
+- lib/solon/config.rb
+- lib/solon/customer_data.rb
+- lib/solon/error.rb
+- lib/solon/money.rb
+- lib/solon/net/https_gateway.rb
+- lib/solon/post_data.rb
+- lib/solon/protx_callback.rb
+- lib/solon/protx_response.rb
+- lib/solon/protx_services.rb
+- lib/solon/unique_id.rb
+- lib/solon_gateway.rb
+- solon.gemspec
+- spec/solon_gateway_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/pyrat/solon
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 25
+      segments: 
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Interface to Sagepay payment processor
+test_files: []
+