sisow 0.9.0

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+lib/sisow.yml
+coverage/
+spec/vcr_cassettes

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in sisow.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,116 @@
+= Sisow
+
+*NOTE* This gem is work in progress. I'm planning to have it ready somewhere in March.
+
+This gem provides an interface to interact with the Sisow payment provider. Sisow offers payments through the iDeal (Dutch),
+Bancontact/Mister Cash (Belgian) and Sofort (German) online payment systems.
+
+To use this gem, you'll need a payment account at Sisow (you'll need your <tt>merchant key</tt> and <tt>merchant id</tt>).
+The gem is aimed at Rails 3.2 but it should work on older Rails versions as well as in non-Rails apps.
+
+== Installation
+
+To install this gem, simply do <tt>gem install sisow</tt> or add it to your Gemfile:
+
+  gem 'sisow'
+
+And update your bundle with <tt>bundle install</tt>
+
+== Usage
+
+=== Configuration
+
+To be able to use the gem, you must first configure it. If you're on Rails, insert the following code in <tt>config/initializers/sisow.rb</tt>:
+
+  Sisow.setup do |config|
+    config.merchant_key = 'your-merchant-key'
+    config.merchant_id  = 'your-merchant-id'
+
+    #
+    # The following settings are optional
+    #
+    config.test_mode    = false   # default: false
+    config.debug_mode   = false   # default: false
+  end
+
+That's it. Once you restart your Rails application (or open a Rails console) you should be able to communicate with
+the Sisow API.
+
+=== Getting a list of issuers
+
+To set up a payment, your user needs to choose an issuer (a bank) that will fulfill the payment. To fetch a list of Issuers, use the following command:
+
+  Sisow::Issuer.list
+
+This will return a list of <tt>Sisow::Issuer</tt> objects that have an <tt>id</tt> and a <tt>name</tt>. The <tt>id</tt> is needed
+to set up the payment in the following step.
+
+=== Setting up a payment
+
+After choosing an issuer, your user must be redirected to the payment page for that issuer. For that to happen, you'll have to
+set up a payment through the Sisow API, after which you'll be given a URL to redirect your user to.
+
+Setting up a payment looks like this:
+
+  payment_attributes = {
+    :purchase_id    => '2012-01-28-33558',      # for your own reference
+    :issuer_id      => '99',                    # the issuer id from the previous step
+    :description    => 'Acme Inc. payment',     # description of this payment
+    :amount         => 1299,                    # amount in Euro in cents
+    :entrance_code  => 'foobar-foxtrot',        # a verification code you can choose. Cannot contain spaces
+    :return_url     => 'http://example.com',    # where the user is sent after the payment
+    :cancel_url     => 'http://example.com',    # where the user is sent when he cancels the payment
+    :callback_url   => 'http://example.com',    # where a failed (not cancelled) payment will be reported
+    :notify_url     => 'http://example.com',    # where the payment status will be reported
+  }
+
+  payment = Sisow::IdealPayment.new(payment_attributes)
+  redirect_url = payment.payment_url
+
+=== Supported payment methods
+
+This gem supports payments through iDeal, Bancontact/Mister Cash and Sofort. Each of these payment methods have their own class. Payment attributes are the same for each payment method, so in the example above you should only need to switch <tt>Sisow::IdealPayment</tt> for one of the other classes. These are the available class names:
+
+  Sisow::IdealPayment       # for iDeal payments
+  Sisow::BancontactPayment  # for Bancontact/Mister Cash payments
+  Sisow::SofortPayment      # for Sofort payments
+
+=== Validity checks
+
+The Sisow API has a few safety measures built in, to prevent malicious users from tampering with your payments. These checks are documented in the Sisow API documentation and are implemented in the gem.
+
+=== Callbacks
+
+As documented in the Sisow API documentation, four callbacks are available. When setting up your payment, each of these callbacks can be assigned a URL. These are: <tt>return_url</tt>, <tt>cancel_url</tt>, <tt>callback_url</tt> and <tt>notify_url</tt>. After a successful or failed payment, or when the payment timeout has been reached, the Sisow API will attempt to perform a GET request on the URL's you defined.
+
+The <tt>Sisow::Api::Callback</tt> can handle these callbacks for you. To initialize such an instance you should provide the following query parameters (which are given by Sisow in the request):
+
+  callback = Sisow::Api::Callback.new(
+    :transaction_id => params[:trxid],
+    :entrance_code  => params[:ec],
+    :status         => params[:status],
+    :sha1           => params[:sha1]
+  )
+
+After initializing a <tt>Sisow::Api::Callback</tt> instance, you can check the validity of the callback and check the transaction status:
+
+  callback.validate!  # Will raise a Sisow::Exception unless the callback is valid
+  callback.valid?     # Will return a boolean to indicate the validity of the callback
+  callback.success?   # True if the transaction was successful
+  callback.expired?   # True if the transaction has expired
+  callback.cancelled? # True if the transaction was cancelled
+  callback.failure?   # True if the transaction has failed
+
+== Development
+
+Your contributions are more than welcome. To contribute to this gem, follow these steps:
+
+1. Fork the repository from Github
+2. Clone your fork on your development machine
+3. Install the dependencies with <tt>bundle install</tt>
+4. Copy <tt>spec/sisow.yml.example</tt> to <tt>spec/sisow.yml</tt> and enter your own Sisow credentials
+5. Verify your clone is working by running <tt>rspec</tt>
+6. Hack away
+7. Run the specs with <tt>rspec</tt>
+8. Verify spec coverage by opening <tt>coverage/index.html</tt>
+9. If all is good: send me a pull request

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/sisow.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'httparty'
+require 'hashie'
+
+require 'sisow/configuration'
+require 'sisow/error_response'
+require 'sisow/exception'
+require 'sisow/issuer'
+require 'sisow/ping'
+require 'sisow/payment'
+require 'sisow/payment/ideal_payment'
+require 'sisow/payment/bancontact_payment'
+require 'sisow/payment/sofort_payment'
+require 'sisow/merchant'
+require 'sisow/api/request'
+require 'sisow/api/request/directory_request'
+require 'sisow/api/request/ping_request'
+require 'sisow/api/request/transaction_request'
+require 'sisow/api/request/check_merchant_request'
+require 'sisow/api/callback'
+
+module Sisow
+
+  class << self
+
+    def service_reachable?
+      ping = Sisow::Ping.send
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+  end
+
+end

data/lib/sisow/api/callback.rb

@@ -0,0 +1,51 @@
+module Sisow
+  module Api
+    class Callback
+
+      attr_accessor :transaction_id,
+                    :entrance_code,
+                    :status,
+                    :sha1
+
+      def initialize(attributes = {})
+        attributes.each do |k,v|
+          send("#{k}=", v)
+        end
+      end
+
+      def valid?
+        valid_callback == true
+      end
+
+      def validate!
+        raise Sisow::Exception, "This callback is forged" and return if valid_callback == false
+      end
+
+      def success?
+        @status == 'Success'
+      end
+
+      def expired?
+        @status == 'Expired'
+      end
+
+      def cancelled?
+        @status == 'Cancelled'
+      end
+
+      def failure?
+        @status == 'Failure'
+      end
+
+      private
+
+        def valid_callback
+          string = [ @transaction_id, @entrance_code, @status, Sisow.configuration.merchant_id, Sisow.configuration.merchant_key ].join
+          calculated_sha1 = Digest::SHA1.hexdigest(string)
+
+          calculated_sha1 == @sha1
+        end
+
+    end
+  end
+end

data/lib/sisow/api/request.rb

@@ -0,0 +1,67 @@
+module Sisow
+  module Api
+    class Request
+
+      include HTTParty
+      base_uri "http://www.sisow.nl/Sisow/iDeal/RestHandler.ashx/"
+
+      def self.perform
+        new.perform
+      end
+
+      def perform
+        raise Sisow::Exception, 'Your merchant_id or merchant_key are not set' unless can_perform?
+
+        validate!
+
+        response = self.class.get(uri)
+        response = Hashie::Mash.new(response)
+
+        error!(response) if response.errorresponse?
+
+        clean(response)
+      end
+
+      def default_params
+        {
+          :merchantid  => Sisow.configuration.merchant_id,
+          :merchantkey => Sisow.configuration.merchant_key,
+          :test        => Sisow.configuration.test_mode_enabled?? test_mode_param : nil
+        }
+      end
+
+      def params;     raise 'Implement me in a subclass'; end
+      def method;     raise 'Implement me in a subclass'; end
+      def clean;      raise 'Implement me in a subclass'; end
+      def validate!;  raise 'Implement me in a subclass'; end
+
+      private
+
+        def can_perform?
+          !Sisow.configuration.merchant_id.empty? && !Sisow.configuration.merchant_key.empty?
+        end
+
+        def uri
+          [ '/', method, '?', encoded_params ].join
+        end
+
+        def params_string
+          params.map { |k,v| [ k, '=', v ].join }.join('&')
+        end
+
+        def encoded_params
+          URI.encode(params_string)
+        end
+
+        def test_mode_param
+          'true'
+        end
+
+        def error!(response)
+          error_response = Sisow::ErrorResponse.new(response)
+          raise Sisow::Exception, error_response.message and return
+        end
+
+    end
+  end
+end

data/lib/sisow/api/request/check_merchant_request.rb

@@ -0,0 +1,40 @@
+module Sisow
+  class CheckMerchantRequest < Sisow::Api::Request
+
+    def method
+      'CheckMerchantRequest'
+    end
+
+    def params
+      default_params.merge!(merchant_params)
+    end
+
+    def clean(response)
+      if response.checkmerchantresponse? && response.checkmerchantresponse.merchant?
+        response.checkmerchantresponse.merchant.payments
+      end
+    end
+
+    def validate!
+      true
+    end
+
+    private
+
+      def merchant_params
+        {
+          :sha1 => sha1
+        }
+      end
+
+      def sha1
+        string = [
+          Sisow.configuration.merchant_id,
+          Sisow.configuration.merchant_key
+        ].join
+
+        Digest::SHA1.hexdigest(string)
+      end
+
+  end
+end

data/lib/sisow/api/request/directory_request.rb

@@ -0,0 +1,25 @@
+module Sisow
+  module Api
+    class DirectoryRequest < Request
+
+      def method
+        'DirectoryRequest'
+      end
+
+      def params
+        default_params
+      end
+
+      def clean(response)
+        if response.directoryresponse? && response.directoryresponse.directory?
+          response.directoryresponse.directory
+        end
+      end
+
+      def validate!
+        true
+      end
+
+    end
+  end
+end

data/lib/sisow/api/request/ping_request.rb

@@ -0,0 +1,25 @@
+module Sisow
+  module Api
+    class PingRequest < Request
+
+      def method
+        'PingRequest'
+      end
+
+      def params
+        default_params
+      end
+
+      def clean(response)
+        if response.pingresponse? && response.pingresponse.timestamp?
+          response.pingresponse.timestamp
+        end
+      end
+
+      def validate!
+        true
+      end
+
+    end
+  end
+end

data/lib/sisow/api/request/transaction_request.rb

@@ -0,0 +1,86 @@
+module Sisow
+  module Api
+    class TransactionRequest < Request
+
+      attr_accessor :purchase_id,
+                    :issuer_id,
+                    :description,
+                    :amount,
+                    :payment
+
+      def initialize(payment)
+        @payment = payment
+      end
+
+      def method
+        'TransactionRequest'
+      end
+
+      def params
+        default_params.merge!(transaction_params)
+      end
+
+      def clean(response)
+        check_validity!(response)
+
+        if response.transactionrequest? && response.transactionrequest.transaction?
+          response.transactionrequest.transaction
+        end
+      end
+
+      def validate!
+        raise Sisow::Exception, 'One of your payment parameters is missing or invalid' unless @payment.valid?
+      end
+
+      def sha1
+        string = [
+          payment.purchase_id,
+          payment.entrance_code,
+          payment.amount,
+          Sisow.configuration.merchant_id,
+          Sisow.configuration.merchant_key
+        ].join
+
+        Digest::SHA1.hexdigest(string)
+      end
+
+      private
+
+        def transaction_params
+          {
+            :payment      => payment.payment_method,
+            :purchaseid   => payment.purchase_id,
+            :amount       => payment.amount,
+            :issuerid     => payment.issuer_id,
+            :description  => payment.description,
+            :entrancecode => payment.entrance_code,
+            :returnurl    => payment.return_url,
+            :cancelurl    => payment.cancel_url,
+            :callbackurl  => payment.callback_url,
+            :notifyurl    => payment.notify_url,
+            :shop_id      => payment.shop_id,
+            :sha1         => sha1
+          }
+        end
+
+        def payment
+          @payment
+        end
+
+        def check_validity!(response)
+          string = [
+            response.transactionrequest.transaction.trxid,
+            response.transactionrequest.transaction.issuerurl,
+            Sisow.configuration.merchant_id,
+            Sisow.configuration.merchant_key
+          ].join
+          calculated_sha1 = Digest::SHA1.hexdigest(string)
+
+          if calculated_sha1 != response.transactionrequest.signature.sha1
+            raise Sisow::Exception, "This response has been forged" and return
+          end
+        end
+
+    end
+  end
+end