RubyGems - solon - Versions diffs - 0.0.5 → 0.1.0 - Mend

solon 0.0.5 → 0.1.0

Files changed (5) hide show

data/README.textile CHANGED Viewed

@@ -2,142 +2,150 @@ 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.
+Solon is another library for interacting with the sagepay VSP server. It is largely the codebase from the seemingly defunct Peeves library with some modifications.
-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.
+This library is not the cleanest out there and you may want to look at the other sagepay offerings before using this library.
-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
+h2. Installation (Rails 3)
-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.
+Add the following to your Gemfile
-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.
+<pre>
+gem 'solon'
+</pre>
-As a contributor, it means that you licence to Solon any contributions that you make as per the Apache licence.
+<pre>
+  bundle
+</pre>
-h2. Kicking the tyres
+In each of your environments you can define the sagepay mode of operation accordingly.
-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:
+In config/environments/(development|test|production|[staging]).rb
 <pre>
-	ruby simulate.rb
+	Solon::Config.vendor 		= [vendor_name]
+	Solon::Config.gateway_mode = :simulator | :test | :live
 </pre>
-Everything should work. If it doesn't work, try asking me (swombat) for help on freenode, channel #flails.
+h2. Integration Guide
-Assuming everything worked fine, revert your change to simulate.rb.
+Best plan is to generate yourself an controller for dealing with the integration.
-h2. Usage
-h3. Configuration
+rails g controller sages
-In each environment file, you want to do something like this:
+in routes.rb
-<pre>
-	PEEVES_VENDOR           = "woobius"
-	PEEVES_GATEWAY_MODE     = :simulator
-</pre>
+resources :sages
-The gateway mode can be set to <code>:simulator</code>, <code>:test</code>, or <code>:live</code>.
-Then, in environment.rb, do:
+Assumes an order has an identifier in order.identifier
 <pre>
-	Solon::Config.vendor 		= PEEVES_VENDOR
-	Solon::Config.gateway_mode = PEEVES_GATEWAY_MODE
-</pre>
+require 'digest/sha1'
-h3. Making a request
+before_create :set_identifier
-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 }
-	              })
+def set_identifier
+  self.identifier = Digest::SHA1.hexdigest(rand(1000).to_s + Time.now.to_s.split(//).sort_by {rand}.join)
+end
 </pre>
-This will register a payment and return a url that you should forward the user to.
+It is a good plan to create an order_transaction model to store order transactions locally for debugging.
-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:
+The first step is registering the payment.
 <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
+def create
+  @order.update_attribute(:transaction_reference, Solon::UniqueId.generate(@order.id.to_s))
+  p = SolonGateway.new
+  @response = p.payment Solon::Money.new(@order.amount.to_f, "GBP"),
+  {
+    :transaction_reference => @order.transaction_reference,
+    :description => "Description of payment",
+    :notification_url => callback_sage_url(@order.identifier),
+    :customer_data => @order.sage_customer_data
+  }
+  if @response.next_url
+    @order.transactions.create(:params => @response, :success => true, :message => "Purchase Transaction",
+    :amount => @order.amount.to_f, :reference => @order.transaction_reference)
+    @order.update_attributes(:security_key => @response.security_key, :user_location => 'away')
+    @order.send_pending_email
+    redirect_to @response.next_url
+  else
+    @order.transactions.create(:params => @response, :success => false, :message => "Purchase Transaction")
+    flash[:warning] = "Unable to make payment, please contact support."
+    redirect_to root_url
   end
+end
 </pre>
-In response to this, you must send back a success message or the transaction will eventually be cancelled by Sagepay:
+The next step is handling to callbacks from sage page.
 <pre>
-	render :text => SolonGateway.response(SolonGateway::APPROVED, url, "Payment succeeded")
-</pre>
+def callback
+  # Parse the callback
+  callback = SolonGateway.parse_callback(request.raw_post)
+  # Get the order from identifier
+  begin
+    @order = Order.find_by_identifier!(params[:id])
+    @order.sage_callback = callback
+  rescue ActiveRecord::RecordNotFound =>  msg
+    # Error if cannot find.
+    render :text => SolonGateway.response('INVALID', no_order_sage_url, 'Transaction complete'), :layout => false
+    return
+  end
+  # If the order has already been paid, render an OK response.
+  if @order.paid?
+    render_response(@order)
+    return
+  end
-Sagepay will then forward the user to <code>url</code>, where you can display a happy success page.
+  if @order.valid_callback?
+    # all is well
+  else
+    # error
+  end
-h3. Repeat transactions
+  render_response(@order)
+end
+</pre>
-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):
+Various responses tell the app different things about the order and you need to render a response in the right manner.
 <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!
+  private
+  def render_response(order)
+    if order.valid_callback?
+      render :text => SolonGateway.response('OK', sage_url(order), 'Transaction complete'), :layout => false
+    elsif order.invalid_callback?
+      render :text => SolonGateway.response('INVALID', invalid_order_sage_url(order), 'Transaction complete'), :layout => false
+    elsif order.sage_callback.st(:NOTAUTHED)
+      render :text => SolonGateway.response('OK', notauthed_sage_url(order), 'Transaction complete'), :layout => false
+    elsif order.sage_callback.st(:ABORT)
+      render :text => SolonGateway.response('OK', abort_sage_url(order), 'Transaction complete'), :layout => false
+    elsif order.sage_callback.st(:REJECTED)
+      render :text => SolonGateway.response('OK', rejected_sage_url(order), 'Transaction complete'), :layout => false
+    elsif order.sage_callback.error?
+      render :text => SolonGateway.response('INVALID', invalid_sage_url(order), 'Transaction complete'), :layout => false
+    else
+      render :text => SolonGateway.response('ERROR', error_sage_url(order), 'Transaction complete'), :layout => false
     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.
+Valid and invalid callbacks not only check that the callback is approved (callback.approved?) but also check that the value of the order locally has not changed since the transaction began. This is a danger with offsite payment gateways.
+The checking of whether a callback is valid is left to the app developer.
-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/solon.gemspec CHANGED Viewed

@@ -4,7 +4,7 @@ $:.unshift lib unless $:.include?(lib)
 Gem::Specification.new do |s|
   s.name        = "solon"
-  s.version     = "0.0.5"
+  s.version     = "0.1.0"
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Alastair Brunton"]
   s.email       = ["info@simplyexcited.co.uk"]

data/spec/solon_gateway_spec.rb CHANGED Viewed

@@ -6,31 +6,31 @@ describe SolonGateway 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'
-                                              )
+      :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} ,
-                    })
+      {
+        :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
@@ -38,7 +38,7 @@ describe SolonGateway do
     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
@@ -46,60 +46,75 @@ describe SolonGateway do
   # 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 "sending an authenticate request" do
+    before(:each) do
+      # pending
+      @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'
+      )
+      @response = @p.authenticate Solon::Money.new(1000, "GBP"),
+      {
+        :transaction_reference => @transaction_reference,
+        :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
+    # it "should be cancellable" do
+    #       pending
+    #       @response2 = @p.cancel({
+    #         :transaction_reference => @transaction_reference,
+    #         :vps_transaction_id => @response.vps_transaction_id,
+    #         :security_key => @response.security_key,
+    #         :related_vps_transaction_id => '12345'
+    #       })
+    #       puts @response2.inspect
+    #       puts @response.transaction_authorisation_number
+    #       puts @response.vps_transaction_id
+    #       puts @response.inspect
+    #       @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",
+        "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)

data/spec/spec_helper.rb CHANGED Viewed

@@ -1,6 +1,17 @@
 require 'rubygems'
-require 'activesupport'
+require 'active_support'
+require 'active_support/core_ext'
+require File.dirname(__FILE__) + "/../lib/solon"
+class Rails
+  def self.logger
+    Logger.new('/tmp/log.txt')
+  end
+end
+Solon::Config.vendor = '[add vendorname here for simulator]'
+Solon::Config.gateway_mode = :simulator
-$LOAD_PATH << File.dirname(__FILE__) + "/../lib/"
-ActiveSupport::Dependencies.load_paths = $LOAD_PATH

metadata CHANGED Viewed

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: solon
 version: !ruby/object:Gem::Version
-  hash: 21
+  hash: 27
   prerelease: false
   segments:
   - 0
+  - 1
   - 0
-  - 5
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors:
 - Alastair Brunton
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2011-08-19 00:00:00 +02:00
+date: 2011-09-02 00:00:00 +02:00
 default_executable:
 dependencies: []