datatrans 1.0.0 → 2.0.0

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.9.2

data/README.markdown

@@ -3,29 +3,173 @@ Datatrans
 
 Ruby adapter for the Datatrans payment gateway (http://www.datatrans.ch).
 
-Usage
-=====
-
 Configuration
 -------------
 
+Set your datatrans credentials in your environment.
+
     Datatrans.configure do |config|
       config.merchant_id = '1234567'
-      config.sign_key = '...'
+      config.sign_key = 'ab739fd5b7c2a1...'
       config.environment = :production
     end
 
 Possible values for the environment: `:production`, `:development`
 
-Controller
-----------
+Web Authorization
+=================
+
+If you want to process a credit card the first time a web authorization is
+necessary. Add the following code to a controller action that shows the form.
+You need to pass at least `amount`, `currency` and `refno` (order number).
+
+    @transaction = Datatrans::Web::Transaction.new({
+      :amount => 1000, # in cents!
+      :currency => 'CHF',
+      :refno => 'ABCDEF',
+      :uppCustomerEmail => 'customer@email.com'
+      # feel free to add more upp infos here ...
+    })
+    
+In your View your show the credit card form with a convenient helper:
+
+In this example we use just ECA (Mastercard) as paymentmethod. Feel free to
+provide an appropriate select field to offer more payment methods. This is the
+form you will show in your "new" method.
+
+    = form_tag Datatrans.web_authorize_url do
+    
+      = text_field_tag :paymentmethod, 'ECA'
+      = text_field_tag :cardno
+      = text_field_tag :expm
+      = text_field_tag :expy
+      = text_field_tag :cvv
+    
+      = hidden_field_tag :successUrl, <your_application_return_url>
+      = hidden_field_tag :cancelUrl, <your_application_return_url>
+      = hidden_field_tag :errorUrl, <your_application_return_url>
+    
+      = datatrans_notification_request_hidden_fields(@transaction)
+    
+      = submit_tag "send"
+      
+In this example we use just ECA (Mastercard) as paymentmethod. Feel free to
+provide an appropriate select field to offer more payment methods. Don't forget
+to add `successUrl`, `cancelUrl` and `errorUrl`. We recommend to set them all
+to the same value.
+ 
+After you submit the request to Datatrans they redirect back to your application.
+Now you can process the transaction like this:
+
+    begin
+      transaction = Datatrans::Web::Transaction.new(params)
+      
+      if transaction.authorize
+        # transaction was successful, access the following attributes
+        # transaction.transaction_id
+        # transaction.creditcard_alias
+        # transaction.masked_cc
+        # transaction.authorization_code
+        # ...
+        
+      else
+        # transaction was not successful, accces the error details
+        # transaction.error_code, transaction.error_message, transaction.error_detail
+        
+      end 
+    rescue Datatrans::InvalidSignatureError => exception
+      # the signature was wrong, the request may have been compromised...
+    end
+  
+XML Transactions
+================
+
+If you have already a credit card alias or an authorized transaction you can
+use the convenient XML methods to process payments.
+
+Authorize
+---------
+
+    transaction = Datatrans::XML::Transaction.new(
+      :refno => 'ABCDEF',
+      :amount => 1000, # in cents!
+      :currency => 'CHF',
+      :aliasCC => '8383843729284848348',
+      :expm => 12,
+      :expy => 15
+    )
+    
+    if transaction.authorize
+      # ok, the transaction is authorized...
+      # access same values as in the web authorization (e.g. transaction.transaction_id)
+    else
+      # transaction.error_code, transaction.error_message, transaction.error_detail
+    end
+
+
+Capture
+-------
+
+To capture an authorized transaction you use the following code:
 
-TODO
+    transaction = Datatrans::XML::Transaction.new(
+      :refno => 'ABCDEF',
+      :amount => 1000, # in cents!
+      :currency => 'CHF',
+      :transaction_id => 19834324987349723948729834
+    )
+    
+    begin
+      if transaction.capture
+        # ok, the money is yours...
+      else
+        # transaction.error_code, transaction.error_message, transaction.error_detail
+      end
+    rescue Datatrans::InvalidSignatureError => exception
+      # the signature was wrong, the request may have been compromised...
+    end
+    
 
-View
+Void
 ----
 
-TODO
+To make an authorized transaction invalid use void.
+
+    transaction = Datatrans::XML::Transaction.new(
+      :refno => 'ABCDEF',
+      :amount => 1000, # in cents!
+      :currency => 'CHF',
+      :transaction_id => 19834324987349723948729834
+    )
+    
+    if transaction.void
+      # ok, the transaction is not longer valid...
+    else
+      # transaction.error_code, transaction.error_message, transaction.error_detail
+    end
+
+
+Todo
+====
+
+* allow signing of xml transactions
+* allow signing with different keys
+* add credit method to reverse already captured transactions
+* add purchase method to authorize and capture in one step
+* dry code more
+
+
+Contribute
+==========
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add specs for it. This is important so we don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself we can ignore when we pull)
+* Send us a pull request. Bonus points for topic branches.
+  
 
 Credits
 =======

data/datatrans.gemspec

@@ -20,4 +20,9 @@ Gem::Specification.new do |s|
   
   s.add_dependency 'httparty'
   s.add_dependency 'activesupport', '>= 3.0.0'
+  s.add_dependency 'i18n'
+  s.add_dependency 'builder'
+  
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'actionpack', '>= 3.0.0'
 end

data/lib/datatrans.rb

@@ -1,3 +1,6 @@
+require 'active_support/core_ext/module'
+require 'action_view'
+
 module Datatrans
   BASE_URL = 'https://payment.datatrans.biz'
   WEB_AUTHORIZE_URL = "#{BASE_URL}/upp/jsp/upStart.jsp"
@@ -38,10 +41,13 @@ module Datatrans
       raise "Unknown environment '#{environment}'. Available: :development, :production."
     end
   end
+  
+  class InvalidSignatureError < StandardError; end
 end
 
 require 'datatrans/version'
-require 'datatrans/notification'
-require 'datatrans/transaction'
+require 'datatrans/common'
+require 'datatrans/xml/transaction'
+require 'datatrans/web/transaction'
 
-ActionView::Base.send :include, Datatrans::Notification::ViewHelper if defined? ActionView
+ActionView::Base.send :include, Datatrans::Web::ViewHelper if defined? ActionView

data/lib/datatrans/common.rb

@@ -0,0 +1,9 @@
+require 'openssl'
+
+module Datatrans::Common
+  def sign(*fields)
+    key = Datatrans.sign_key.split(/([a-f0-9][a-f0-9])/).reject(&:empty?)
+    key = key.pack("H*" * key.size)
+    OpenSSL::HMAC.hexdigest(OpenSSL::Digest::MD5.new, key, fields.join)
+  end
+end

data/lib/datatrans/version.rb

@@ -1,3 +1,3 @@
 module Datatrans
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/lib/datatrans/web/transaction.rb

@@ -0,0 +1,55 @@
+require 'active_support/core_ext/hash'
+
+module Datatrans::Web
+  class Transaction
+    include Datatrans::Common
+    
+    attr_accessor :request
+    attr_reader :response, :params
+    
+    def initialize(params)
+      raise 'Please define Datatrans.sign_key!' unless Datatrans.sign_key.present?
+
+      params = params.to_hash
+      params.symbolize_keys!
+      params.reverse_merge!({ :reqtype => 'NOA', :useAlias => 'Yes', :hiddenMode => 'Yes' })
+      @params = params
+    end
+    
+    def signature
+      sign(Datatrans.merchant_id, params[:amount], params[:currency], params[:refno])
+    end
+    
+    def authorize
+      @response = AuthorizeResponse.new(params)
+      @response.successful?
+    end
+    
+    def method_missing(method, *args, &block)
+      if response.respond_to? method.to_sym
+        response.send(method)
+      else
+        super
+      end
+    end
+  end
+  
+  module ViewHelper
+    def datatrans_notification_request_hidden_fields(transaction)
+      [
+        hidden_field_tag(:merchantId, Datatrans.merchant_id),
+        hidden_field_tag(:hiddenMode, transaction.params[:hiddenMode]),
+        hidden_field_tag(:reqtype, transaction.params[:reqtype]),
+        hidden_field_tag(:amount, transaction.params[:amount]),
+        hidden_field_tag(:currency, transaction.params[:currency]),
+        hidden_field_tag(:useAlias, transaction.params[:useAlias]),
+        hidden_field_tag(:sign, transaction.signature),
+        hidden_field_tag(:refno, transaction.params[:refno]),
+        hidden_field_tag(:uppCustomerName, transaction.params[:uppCustomerName]),
+        hidden_field_tag(:uppCustomerEmail, transaction.params[:uppCustomerEmail])
+      ].join.html_safe
+    end
+  end
+end
+
+require 'datatrans/web/transaction/authorize'

data/lib/datatrans/web/transaction/authorize.rb

@@ -0,0 +1,68 @@
+class Datatrans::Web::Transaction
+  class AuthorizeResponse
+    attr_accessor :params
+    
+    def initialize(params)
+      @params = params
+    end
+    
+    def successful?
+      raise Datatrans::InvalidSignatureError unless valid_signature?
+      response_code == '01' && response_message == 'Authorized' && !errors_occurred?
+    end
+    
+    def valid_signature?
+      return true if errors_occurred? # no sign2 sent on error
+      sign(Datatrans.merchant_id, params[:amount], params[:currency], params[:uppTransactionId]) == params[:sign2]
+    end
+    
+    def response_code
+      params[:responseCode] rescue nil
+    end
+    
+    def response_message
+      params[:responseMessage] rescue nil
+    end
+    
+    def transaction_id
+      params[:uppTransactionId] rescue nil 
+    end
+    
+    def reference_number
+      params[:refno] rescue nil 
+    end
+    
+    def authorization_code
+      params[:authorizationCode] rescue nil
+    end
+
+    def masked_cc
+      params[:maskedCC] rescue nil
+    end
+    
+    def creditcard_alias
+      params[:aliasCC] rescue nil
+    end
+    
+    def error_code
+      params[:errorCode] rescue nil
+    end
+    
+    def error_message
+      params[:errorMessage] rescue nil
+    end
+    
+    def error_detail
+      params[:errorDetail] rescue nil
+    end
+    
+    
+    private
+    
+    def errors_occurred?
+      error_code || error_message || error_detail
+    end
+    
+    include Datatrans::Common
+  end
+end

data/lib/datatrans/xml/transaction.rb

@@ -0,0 +1,47 @@
+require 'active_support/core_ext/hash'
+
+module Datatrans::XML
+  class Transaction
+    attr_accessor :request
+    attr_reader :response, :params
+    
+    def initialize(params)
+      @params = params.symbolize_keys
+    end
+    
+    def authorize
+      self.request = AuthorizeRequest.new(params)
+      @response = AuthorizeResponse.new(request.process)
+      @response.successful?
+    end
+    
+    def void
+      self.request = VoidRequest.new(params)
+      @response = VoidResponse.new(request.process)
+      @response.successful?
+    end
+    
+    def capture
+      self.request = CaptureRequest.new(params)
+      @response = CaptureResponse.new(request.process)
+      @response.successful?
+    end
+    
+    # TODO: purchase, credit methods
+    
+    
+    def method_missing(method, *args, &block)
+      if response.respond_to? method.to_sym
+        response.send(method)
+      elsif request.respond_to? method.to_sym
+        request.send(method)
+      else
+        super
+      end
+    end
+  end
+end
+
+require 'datatrans/xml/transaction/authorize'
+require 'datatrans/xml/transaction/void'
+require 'datatrans/xml/transaction/capture'

data/lib/datatrans/xml/transaction/authorize.rb

@@ -0,0 +1,83 @@
+require 'datatrans/xml/transaction/request'
+require 'datatrans/xml/transaction/response'
+
+class Datatrans::XML::Transaction
+  class AuthorizeRequest < Request
+    
+    def process
+      self.class.post(Datatrans.xml_authorize_url, 
+        :headers => { 'Content-Type' => 'text/xml' },
+        :body => build_authorize_request.to_s).parsed_response
+    end
+    
+    
+    private
+    
+    def build_authorize_request
+      build_xml_request(:authorization) do |xml|
+        xml.amount params[:amount]
+        xml.currency params[:currency]
+        xml.aliasCC params[:aliasCC]
+        xml.expm params[:expm]
+        xml.expy params[:expy]
+        xml.sign sign(Datatrans.merchant_id, params[:amount], params[:currency], params[:refno])
+      end
+    end
+    
+  end
+  
+  class AuthorizeResponse < Response
+    
+    def successful?
+      response_code == '01' && response_message == 'Authorized'
+    end
+    
+    def response_code
+      params_root_node['response']['responseCode'] rescue nil
+    end
+    
+    def response_message
+      params_root_node['response']['responseMessage'] rescue nil
+    end
+    
+    def transaction_id
+      params_root_node['response']['uppTransactionId'] rescue nil 
+    end
+    
+    def reference_number
+      params_root_node['refno'] rescue nil 
+    end
+    
+    def authorization_code
+      params_root_node['response']['authorizationCode'] rescue nil
+    end
+
+    def masked_cc
+      params_root_node['response']['maskedCC'] rescue nil
+    end
+    
+    def creditcard_alias
+      params_root_node['request']['aliasCC'] rescue nil
+    end
+    
+    def error_code
+      params_root_node['error']['errorCode'] rescue nil 
+    end
+    
+    def error_message
+      params_root_node['error']['errorMessage'] rescue nil
+    end
+    
+    def error_detail
+      params_root_node['error']['errorDetail'] rescue nil
+    end
+    
+    
+    private
+    
+    def params_root_node
+      params['authorizationService']['body']['transaction']
+    end
+    
+  end
+end