adyen 0.3.8 → 1.0.0

data/.gitignore

@@ -4,3 +4,7 @@
 adyen-*.gem
 .yardoc
 *.swp
+*.swo
+.DS_Store
+t.rb
+spec/functional/initializer.rb

data/.kick

@@ -0,0 +1,35 @@
+options.on('--doc', 'Also generate docs.') do
+  process do |files|
+    if files.any? { |f| f =~ /lib\/.+\.rb$/ }
+      execute "yardoc --no-private"
+      execute(%{osascript -e 'tell application "Safari"
+        do JavaScript "window.location.reload()" in first document
+      end tell'})
+    end
+  end
+end
+
+recipe :ruby
+
+process do |files|
+  specs = files.take_and_map do |file|
+    case file
+    when "spec/spec_helper.rb"
+      Dir.glob("spec/**/*_spec.rb")
+    when "spec/api/spec_helper.rb"
+      Dir.glob("spec/api/*_spec.rb")
+    when "lib/adyen/api.rb"
+      "spec/api/api_spec.rb"
+    when "lib/adyen/api/xml_querier.rb"
+      ["spec/api/payment_service_spec.rb", "spec/api/recurring_service_spec.rb"]
+    when "lib/adyen/api/simple_soap_client.rb"
+      ["spec/api/simple_soap_client_spec.rb", "spec/api/payment_service_spec.rb", "spec/api/recurring_service_spec.rb"]
+    when "lib/adyen/api/response.rb"
+      ["spec/api/response_spec.rb", "spec/api/payment_service_spec.rb", "spec/api/recurring_service_spec.rb"]
+    when %r{lib/adyen/api/templates/(.+)\.rb$}, %r{lib/adyen/api/(.+)\.rb$}
+      "spec/api/#{$1}_spec.rb"
+    end
+  end
+  Ruby.run_tests(specs)
+end
+

data/LICENSE

@@ -1,4 +1,5 @@
-Copyright (c) 2008 - 2009 Willem van Bergen and Michel Barbosa
+Copyright (c) 2008 - 2011 
+Willem van Bergen, Michel Barbosa, Stefan Borsje & Eloy Duran
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +18,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -24,11 +24,15 @@ to make the Adyen functionality available in your Rails project:
 
   config.gem 'adyen'
 
-You can also install it as a Rails plugin (*deprecated*):
+The Adyen gem will happily use REXML for communication with Adyen’s SOAP API, however, if
+you have the Nokogiri gem installed and required the gem will use that for performance.
 
-  script/plugin install git://github.com/wvanbergen/adyen.git
-  
-Depending on your use case, you may also need the following gems: activerecord, handsoap and nokogiri.
+== Generators
+
+The gem ships with a generator for Rails 3. To create an ActiveRecord migration, mode, and
+ActionController for the notifications send by Adyen, run the following:
+
+  $ rails generate adyen:notification
 
 == Usage
 

data/Rakefile

@@ -2,4 +2,14 @@ Dir[File.dirname(__FILE__) + "/tasks/*.rake"].each { |file| load(file) }
 
 GithubGem::RakeTasks.new(:gem)
 
+begin
+  require 'rubygems'
+  require 'yard'
+  require File.expand_path('../yard_extensions', __FILE__)
+  YARD::Rake::YardocTask.new do |y|
+    y.options << '--no-private' << '--title' << 'The ‘Adyen payment service’ library for Ruby'
+  end
+rescue LoadError
+end
+
 task :default => "spec:specdoc"

data/TODO

@@ -1,7 +1,17 @@
-* Use require/autoload instead of const_missing
-* Make sure Japansese yens work as expected (this is the only currency Adyen does not expect to be in cents)
-* Ditch SOAP library dependency.
-* Complete SOAP API.
+1.0
+===
+
+* Screen documentation
+
+Possible/Later
+==============
+
+* Add a capture! method to an authorisation response from the PaymentService.
+
+* Add iDEAL API. To get started, see the `iDEAL' topic-branch which contains `ideal-scratchpad.rb' and a stub for a functional spec.
+
+* Add the DirectDebit API.
+
 * Add ActiveMerchant integration
 
 * Split up gem to have more explicit dependency requirements, e.g.:

data/adyen.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name    = 'adyen'
-  s.version = "0.3.8"
-  s.date    = "2010-09-23"
+  s.version = "1.0.0"
+  s.date    = "2011-01-22"
 
   s.summary = "Integrate Adyen payment services in your Ruby on Rails application."
   s.description = <<-EOS
@@ -13,24 +13,18 @@ Gem::Specification.new do |s|
 
   s.authors  = ['Willem van Bergen', 'Michel Barbosa', 'Stefan Borsje', 'Eloy Duran']
   s.email    = ['willem@vanbergen.org', 'cicaboo@gmail.com', 'mail@sborsje.nl', 'eloy.de.enige@gmail.com']
-  s.homepage = 'http://wiki.github.com/wvanbergen/adyen'
+  s.homepage = 'http://github.com/wvanbergen/adyen/wiki'
 
   s.add_development_dependency('rake')
-  s.add_development_dependency('rspec', '>= 1.1.4')
-  s.add_development_dependency('git', '>= 1.1.0')
-  s.add_development_dependency('gemcutter')
-  
-  # Drop or make runtime dependency.
-  s.add_development_dependency('activerecord')
-  s.add_development_dependency('handsoap')
+  s.add_development_dependency('rspec', '~> 2.0')
   s.add_development_dependency('nokogiri')
-
-  s.requirements << 'Handsoap is required for accessing the SOAP services. See http://github.com/troelskn/handsoap.'
-  s.requirements << 'ActiveRecord is required for storing the notifications in your database.'
+  s.add_development_dependency('rails', '>= 2.3')
+  
+  s.requirements << 'Having Nokogiri installed will speed up XML handling when using the SOAP API.'
 
   s.rdoc_options << '--title' << s.name << '--main' << 'README.rdoc' << '--line-numbers' << '--inline-source'
   s.extra_rdoc_files = ['README.rdoc']
 
-  s.files = %w(spec/spec_helper.rb spec/adyen_spec.rb lib/adyen/form.rb .gitignore spec/notification_spec.rb lib/adyen/soap.rb LICENSE spec/soap_spec.rb init.rb adyen.gemspec Rakefile spec/form_spec.rb README.rdoc lib/adyen/notification.rb lib/adyen/formatter.rb tasks/github-gem.rake lib/adyen/encoding.rb TODO lib/adyen/matchers.rb lib/adyen.rb)
-  s.test_files = %w(spec/adyen_spec.rb spec/notification_spec.rb spec/soap_spec.rb spec/form_spec.rb)
+  s.files = %w(.gitignore .kick LICENSE README.rdoc Rakefile TODO adyen.gemspec lib/adyen.rb lib/adyen/api.rb lib/adyen/api/cacert.pem lib/adyen/api/payment_service.rb lib/adyen/api/recurring_service.rb lib/adyen/api/response.rb lib/adyen/api/simple_soap_client.rb lib/adyen/api/templates/payment_service.rb lib/adyen/api/templates/recurring_service.rb lib/adyen/api/test_helpers.rb lib/adyen/api/xml_querier.rb lib/adyen/configuration.rb lib/adyen/encoding.rb lib/adyen/form.rb lib/adyen/formatter.rb lib/adyen/matchers.rb lib/adyen/notification_generator.rb lib/adyen/railtie.rb lib/adyen/templates/notification_migration.rb lib/adyen/templates/notification_model.rb spec/adyen_spec.rb spec/api/api_spec.rb spec/api/payment_service_spec.rb spec/api/recurring_service_spec.rb spec/api/response_spec.rb spec/api/simple_soap_client_spec.rb spec/api/spec_helper.rb spec/api/test_helpers_spec.rb spec/form_spec.rb spec/functional/api_spec.rb spec/functional/initializer.rb.sample spec/spec_helper.rb tasks/github-gem.rake yard_extensions.rb)
+  s.test_files = %w(spec/adyen_spec.rb spec/api/api_spec.rb spec/api/payment_service_spec.rb spec/api/recurring_service_spec.rb spec/api/response_spec.rb spec/api/simple_soap_client_spec.rb spec/api/test_helpers_spec.rb spec/form_spec.rb spec/functional/api_spec.rb)
 end

data/lib/adyen.rb

@@ -5,73 +5,24 @@
 # The most important submodules are:
 # * {Adyen::Form} for generating payment form fields, generating redirect URLs 
 #   to the Adyen payment system, and generating and checking of signatures.
-# * {Adyen::Notification} for handling notifications sent by Adyen to your servers.
-# * {Adyen::SOAP} for communicating with the Adyen SOAP services for payment
-#   maintenance and issuing recurring payments.
+# * {Adyen::API} for communicating with the Adyen SOAP services for issuing
+#   (recurring) payments and recurring contract maintenance.
 module Adyen
 
   # Version constant for the Adyen plugin.
   # DO NOT CHANGE THIS VALUE BY HAND. It will be updated automatically by
   # the gem:release rake task.
-  VERSION = "0.3.8"
+  VERSION = "1.0.0"
 
-  # Loads configuration settings from a Hash.
-  #
-  # @param [Hash] hash The (nested Hash) with configuration variables.
-  # @param [Module] mod The current working module. This parameter is used
-  #    to recursively traverse the hash for submodules.
-  # @raise [StandardError] An exception is raised of an unkown configuration 
-  #    setting is encountered in the hash.
-  def self.load_config(hash, mod = Adyen)
-    hash.each do |key, value|
-      if key.to_s =~ /^[a-z]/ && mod.respond_to?(:"#{key}=")
-        mod.send(:"#{key}=", value)
-      elsif key.to_s =~ /^[A-Z]/
-        self.load_config(value, mod.const_get(key))
-      else
-        raise "Unknown configuration variable: '#{key}' for #{mod}"
-      end
-    end
-  end
-
-  # The Rails environment for which to use to Adyen "live" environment.
-  LIVE_RAILS_ENVIRONMENTS = ['production']
-
-  # Setter voor the current Adyen environment.
-  # @param ['test', 'live'] env The Adyen environment to use
-  def self.environment=(env)
-    @environment = env
-  end
-
-  # Returns the current Adyen environment, either test or live.
-  #
-  # It will return the +override+ value if set, it will return the value set
-  # using {Adyen.environment=} otherwise. If this value also isn't set, the
-  # environment is determined with {Adyen.autodetect_environment}.
-  #
-  # @param ['test', 'live'] override An environment to override the default with.
-  # @return ['test', 'live'] The Adyen environment that is currently being used.
-  def self.environment(override = nil)
-    override || @environment || Adyen.autodetect_environment
-  end
-
-  # Autodetects the Adyen environment based on the RAILS_ENV constant.
-  # @return ['test', 'live'] The Adyen environment that corresponds to the Rails environment
-  def self.autodetect_environment
-    (defined?(RAILS_ENV) && Adyen::LIVE_RAILS_ENVIRONMENTS.include?(RAILS_ENV.to_s.downcase)) ? 'live' : 'test'
-  end
-
-  # Loads submodules on demand, so that dependencies are not required.
-  # @param [Symbol] sym The name of the submodule
-  # @return [Module] The actual loaded submodule.
-  # @raise [LoadError, NameError] If the submodule cannot be loaded
-  def self.const_missing(sym)
-    require "adyen/#{sym.to_s.downcase}"
-    return Adyen.const_get(sym)
-  rescue Exception
-    super(sym)
+  # @return [Configuration] The configuration singleton.
+  def self.configuration
+    @configuration ||= Adyen::Configuration.new
   end
 end
 
+require 'adyen/configuration'
 require 'adyen/encoding'
 require 'adyen/formatter'
+require 'adyen/form'
+
+require 'adyen/railtie' if defined?(::Rails) && ::Rails::VERSION::MAJOR >= 3

data/lib/adyen/api.rb

@@ -0,0 +1,281 @@
+require 'adyen'
+require 'adyen/api/simple_soap_client'
+require 'adyen/api/payment_service'
+require 'adyen/api/recurring_service'
+
+module Adyen
+  # The API module contains classes that interact with the Adyen SOAP API.
+  #
+  # You'll need to provide a username and password to interact with Adyen:
+  #
+  #     Adyen.configuration.api_username = 'ws@Company.MyAccount'
+  #     Adyen.configuration.api_password = 'secret'
+  #
+  # Furthermore, you can setup default parameters, which will be used by every API call, by using
+  # {Adyen::API.default_arguments}.
+  #
+  # The following classes, which handle the SOAP services, are available:
+  #
+  # * {PaymentService}   - for authorisation of, and modification to, payments.
+  # * {RecurringService} - for handling recurring contract details.
+  #
+  # *However*, direct use of these classes is discouraged in favor of the shortcut methods defined
+  # on the API module. These methods *expect* that you set the :merchant_account as a default
+  # parameter.
+  #
+  # Note that you'll need an Adyen notification PSP reference for some of the calls. Because of
+  # this, store all notifications that Adyen sends to you. Moreover, the responses to these calls 
+  # do *not* tell you whether or not the requested action was successful. For this you will also 
+  # have to check the notification.
+  #
+  # = Authorising payments
+  #
+  # To authorise payments, not recurring ones, the customers payment details will have to pass
+  # through your application’s infrastucture. Because of this you will have to contact Adyen and
+  # provide the necessary paperwork which says that you’re PCI DSS compliant, before you are given
+  # access to Adyen’s API.
+  #
+  # Unless you are going to process over twenty thousand payments anually, the PCI DSS
+  # Self-Assessment Questionnaire (SAQ) type A will _probably_ suffice.
+  #
+  # @see http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard
+  # @see https://www.pcisecuritystandards.org/saq/instructions_dss.shtml
+  # @see http://usa.visa.com/merchants/risk_management/cisp_merchants.html
+  module API
+    extend self
+
+    # Authorise a payment.
+    #
+    # @see capture_payment
+    #
+    # Of all options, only the details are optional. But since the IP is’s used in various risk
+    # checks, and the email and reference are needed to enable recurring contract, it’s a good
+    # idea to supply it anyway.
+    #
+    # @example
+    #   response = Adyen::API.authorise_payment(
+    #     invoice.id,
+    #     { :currency => 'EUR', :value => invoice.amount },
+    #     { :reference => user.id, :email => user.email, :ip => '8.8.8.8' },
+    #     { :holder_name => "Simon Hopper", :number => '4444333322221111', :cvc => '737', :expiry_month => 12, :expiry_year => 2012 }
+    #   )
+    #   response.authorised? # => true
+    #
+    # @param          [Numeric,String] reference      Your reference (ID) for this payment.
+    # @param          [Hash]           amount         A hash describing the money to charge.
+    # @param          [Hash]           shopper        A hash describing the shopper.
+    # @param          [Hash]           card           A hash describing the creditcard details.
+    #
+    # @option amount  [String]         :currency      The ISO currency code (EUR, GBP, USD, etc).
+    # @option amount  [Integer]        :value         The value of the payment in discrete cents,
+    #                                                 unless the currency does not have cents.
+    #
+    # @option shopper [Numeric,String] :reference     The shopper’s reference (ID).
+    # @option shopper [String]         :email         The shopper’s email address.
+    # @option shopper [String]         :ip            The shopper’s IP address.
+    #
+    # @option card    [String]         :holder_name   The full name on the card.
+    # @option card    [String]         :number        The card number.
+    # @option card    [String]         :cvc           The card’s verification code.
+    # @option card    [Numeric,String] :expiry_month  The month in which the card expires.
+    # @option card    [Numeric,String] :expiry_year   The year in which the card expires.
+    #
+    # @param [Boolean] enable_recurring_contract      Store the payment details at Adyen for
+    #                                                 future recurring or one-click payments.
+    #
+    # @return [PaymentService::AuthorisationResponse] The response object which holds the
+    #                                                 authorisation status.
+    def authorise_payment(reference, amount, shopper, card, enable_recurring_contract = false)
+      PaymentService.new(
+        :reference => reference,
+        :amount    => amount,
+        :shopper   => shopper,
+        :card      => card,
+        :recurring => enable_recurring_contract
+      ).authorise_payment
+    end
+
+    # Authorise a recurring payment. The contract detail will default to the ‘+latest+’, which
+    # is generally what you’d want.
+    #
+    # @see capture_payment
+    #
+    # Of all options, only the shopper’s IP address is optional. But since it’s used in various
+    # risk checks, it’s a good idea to supply it anyway.
+    #
+    # @example
+    #   response = Adyen::API.authorise_recurring_payment(
+    #     invoice.id,
+    #     { :currency => 'EUR', :value => invoice.amount },
+    #     { :reference => user.id, :email => user.email, :ip => '8.8.8.8' }
+    #   )
+    #   response.authorised? # => true
+    #
+    # @param          [Numeric,String] reference      Your reference (ID) for this payment.
+    # @param          [Hash]           amount         A hash describing the money to charge.
+    # @param          [Hash]           shopper        A hash describing the shopper.
+    #
+    # @option amount  [String]         :currency      The ISO currency code (EUR, GBP, USD, etc).
+    # @option amount  [Integer]        :value         The value of the payment in discrete cents,
+    #                                                 unless the currency does not have cents.
+    #
+    # @option shopper [Numeric,String] :reference     The shopper’s reference (ID).
+    # @option shopper [String]         :email         The shopper’s email address.
+    # @option shopper [String]         :ip            The shopper’s IP address.
+    #
+    # @param [String] recurring_detail_reference      The recurring contract reference to use.
+    # @see list_recurring_details
+    #
+    # @return [PaymentService::AuthorisationResponse] The response object which holds the
+    #                                                 authorisation status.
+    def authorise_recurring_payment(reference, amount, shopper, recurring_detail_reference = 'LATEST')
+      PaymentService.new(
+        :reference => reference,
+        :amount    => amount,
+        :shopper   => shopper,
+        :recurring_detail_reference => recurring_detail_reference
+      ).authorise_recurring_payment
+    end
+
+    # Authorise a ‘one-click’ payment. A specific contract detail *has* to be specified.
+    #
+    # @see capture_payment
+    #
+    # Of all options, only the shopper’s IP address is optional. But since it’s used in various
+    # risk checks, it’s a good idea to supply it anyway.
+    #
+    # @example
+    #   detail  = Adyen::API.list_recurring_details(user.id).details.last[:recurring_detail_reference]
+    #   payment = Adyen::API.authorise_one_click_payment(
+    #     invoice.id,
+    #     { :currency => 'EUR', :value => invoice.amount },
+    #     { :reference => user.id, :email => user.email, :ip => '8.8.8.8' },
+    #     '737',
+    #     detail
+    #   )
+    #   payment.authorised? # => true
+    #
+    # @param          [Numeric,String] reference      Your reference (ID) for this payment.
+    # @param          [Hash]           amount         A hash describing the money to charge.
+    # @param          [Hash]           shopper        A hash describing the shopper.
+    # @param          [String]         card_cvc       The card’s verification code.
+    #
+    # @option amount  [String]         :currency      The ISO currency code (EUR, GBP, USD, etc).
+    # @option amount  [Integer]        :value         The value of the payment in discrete cents,
+    #                                                 unless the currency does not have cents.
+    #
+    # @option shopper [Numeric,String] :reference     The shopper’s reference (ID).
+    # @option shopper [String]         :email         The shopper’s email address.
+    # @option shopper [String]         :ip            The shopper’s IP address.
+    #
+    # @param [String] recurring_detail_reference      The recurring contract reference to use.
+    # @see list_recurring_details
+    #
+    # @return [PaymentService::AuthorisationResponse] The response object which holds the
+    #                                                 authorisation status.
+    def authorise_one_click_payment(reference, amount, shopper, card_cvc, recurring_detail_reference)
+      PaymentService.new(
+        :reference => reference,
+        :amount    => amount,
+        :shopper   => shopper,
+        :card      => { :cvc => card_cvc },
+        :recurring_detail_reference => recurring_detail_reference
+      ).authorise_one_click_payment
+    end
+
+    # Capture an authorised payment.
+    #
+    # You can also configure your merchant account to automatically capture authorised payments
+    # in the merchant account settings.
+    #
+    # @see https://ca-test.adyen.com/ca/ca/accounts/manageMerchantAccount.shtml
+    #
+    # Note that the response of this request will only indicate whether or
+    # not the request has been successfuly received. Check the notitification
+    # for the actual mutation status.
+    #
+    # @param         [String]         psp_reference   The PSP reference, from Adyen, of the
+    #                                                 previously authorised request.
+    # @param         [Hash]           amount          A hash describing the money to charge.
+    # @option amount [String]         :currency       The ISO currency code (EUR, GBP, USD, etc).
+    # @option amount [Integer]        :value          The value of the payment in discrete cents,
+    #                                                 unless the currency does not have cents.
+    #
+    # @return [PaymentService::CaptureResponse] The response object.
+    def capture_payment(psp_reference, amount)
+      PaymentService.new(:psp_reference => psp_reference, :amount => amount).capture
+    end
+
+    # Refund a captured payment.
+    #
+    # Note that the response of this request will only indicate whether or
+    # not the request has been successfuly received. Check the notitification
+    # for the actual mutation status.
+    #
+    # @param         [String]         psp_reference   The PSP reference, from Adyen, of the
+    #                                                 previously authorised request.
+    # @param         [Hash]           amount          A hash describing the money to charge.
+    # @option amount [String]         :currency       The ISO currency code (EUR, GBP, USD, etc).
+    # @option amount [Integer]        :value          The value of the payment in discrete cents,
+    #                                                 unless the currency does not have cents.
+    #
+    # @return [PaymentService::RefundResponse] The response object.
+    def refund_payment(psp_reference, amount)
+      PaymentService.new(:psp_reference => psp_reference, :amount => amount).refund
+    end
+
+    # Cancel or refund a payment. Use this if you want to cancel or refund
+    # the payment, but are unsure what the current status is.
+    #
+    # Note that the response of this request will only indicate whether or
+    # not the request has been successfuly received. Check the notitification
+    # for the actual mutation status.
+    #
+    # @param         [String]         psp_reference   The PSP reference, from Adyen, of the
+    #                                                 previously authorised request.
+    #
+    # @return [PaymentService::CancelOrRefundResponse] The response object.
+    def cancel_or_refund_payment(psp_reference)
+      PaymentService.new(:psp_reference => psp_reference).cancel_or_refund
+    end
+
+    # Cancel an authorised payment.
+    #
+    # Note that the response of this request will only indicate whether or
+    # not the request has been successfuly received. Check the notitification
+    # for the actual mutation status.
+    #
+    # @param         [String]         psp_reference   The PSP reference, from Adyen, of the
+    #                                                 previously authorised request.
+    #
+    # @return [PaymentService::CancelResponse] The response object.
+    def cancel_payment(psp_reference)
+      PaymentService.new(:psp_reference => psp_reference).cancel
+    end
+
+    # Retrieve the recurring contract details for a shopper.
+    #
+    # @param         [String]       shopper_reference The ID used to store payment details for
+    #                                                 this shopper.
+    #
+    # @return [RecurringService::ListResponse] The response object.
+    def list_recurring_details(shopper_reference)
+      RecurringService.new(:shopper => { :reference => shopper_reference }).list
+    end
+
+    # Disable the recurring contract details for a shopper.
+    #
+    # @param         [String]       shopper_reference The ID used to store payment details for
+    #                                                 this shopper.
+    # @param [String,nil] recurring_detail_reference  The ID of a specific recurring contract.
+    #                                                 Defaults to all.
+    #
+    # @return [RecurringService::DisableResponse] The response object.
+    def disable_recurring_contract(shopper_reference, recurring_detail_reference = nil)
+      RecurringService.new({
+        :shopper => { :reference => shopper_reference },
+        :recurring_detail_reference => recurring_detail_reference
+      }).disable
+    end
+  end
+end