omnipay 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bd4376a27e44aa8518b5ffa2ac3d68b10b2bcc10
-  data.tar.gz: 2ce839a8fb9322596f5b99c3bc9de877c9794583
+  metadata.gz: 426ecbaa0b5c6679ed1270a5f4e95d3b0e701724
+  data.tar.gz: d888f625b19af11cfb97ac2980187da74bcf29c8
 SHA512:
-  metadata.gz: 0ebf71355c1f7bece7ee9b172a64d0d3266b93b8e6d2d99099d0a06849ed212b26e7795bd34a2c583635f57978fa4125f85e4dc55b74e796cc54605936c25667
-  data.tar.gz: 27a788697beb58f2ab9243cbb1ff5f6a05298c9d1e78d19940be08495364ccb174d02bf01f6659ae7642a5e0bc65c59e01dfef57459e2e900c32ea4159f453b5
+  metadata.gz: e426e0bc7aeaf2da37c3fedf6ea1c42c9588f02dd3916cc86906418a14a3364c40261a18e1c3edbeffaf3f1433d11a016d9f265335829959e9e6eb5a32e98c82
+  data.tar.gz: 55ff42d3659b4e787a4050c9cedb41b0c2f385076517a7f1a9d3f1c5d1d36734e4c8de0a003661a5eb6096d241a5c7e4d69857950ebbb46c00107b570c9393a5

data/lib/omnipay.rb

@@ -1,14 +1,17 @@
 # The root Omnipay module. Used for defining its global configuration
 module Omnipay
 
+  autoload :Adapter, 'omnipay/adapter'
   autoload :Gateway, 'omnipay/gateway'
   autoload :AutosubmitForm, 'omnipay/autosubmit_form'
   autoload :Configuration, 'omnipay/configuration'
   autoload :Gateways, 'omnipay/gateways'
   autoload :Middleware, 'omnipay/middleware'
+  autoload :Helpers, 'omnipay/helpers'
 
-  # Error code for an untreatable response
-  INVALID_RESPONSE = :invalid_response
+
+  # Code for a successful transaction
+  SUCCESS = :success
 
   # Error code for a user-initiated payment failure
   CANCELATION = :cancelation
@@ -16,18 +19,20 @@ module Omnipay
   # Error code for a valid response but a failed payment
   PAYMENT_REFUSED = :payment_refused
 
-  # Error code for a signature mismatch
-  WRONG_SIGNATURE = :wrong_signature
+  # Error code for an untreatable response
+  INVALID_RESPONSE = :invalid_response
 
 
 
   # Accessors to the configured gateways
+  # @return [Gateways] the configured gateways
   def self.gateways
     @gateways ||= Omnipay::Gateways.new
   end
 
 
   # Syntaxic sugar for adding a new gateway
+  # @see Gateways#push
   def self.use_gateway(opts = {}, &block)
     self.gateways.push(opts, &block)
   end
@@ -44,7 +49,7 @@ module Omnipay
   # Example use : 
   # 
   #   Omnipay.configure do |config|
-  #     config.secret_token = "a-secret-token"
+  #     config.base_path = '/payment'
   #   end
   def self.configure
     yield configuration

data/lib/omnipay/adapter.rb

@@ -0,0 +1,272 @@
+module Omnipay
+
+  require 'ostruct'
+
+  # Base adapter class
+  # Inherited by specific implementations
+  class Adapter
+
+    # Handle adapter and payment configuration
+    # Can be defined
+    # - at the class level
+    # - at the adapter initialization
+    # - at the payment redirection (only payment config)
+    # Adapter config is mandatory
+    # Payment config is not, but extra fields are
+
+    ConfigField = Struct.new(:explaination, :value, :mandatory)
+
+    DEFAULT_ADAPTER_CONFIG = {
+      :sandbox => ConfigField.new('when enabled, the payment are not actually withdrawn', true, nil)
+    }
+
+    DEFAULT_PAYMENT_CONFIG = {
+      :amount       => ConfigField.new('The amount (in cents) to pay', nil, true),
+      :reference    => ConfigField.new('The local reference of the payment', nil, true),
+      :currency     => ConfigField.new('The ISO 4217 code for the currency to use', 'USD', true),
+      :locale       => ConfigField.new('The ISO 639-1 locale code for the payment page', 'en', true),
+      :title        => ConfigField.new('The title to display on the payment page', nil, false),
+      :description  => ConfigField.new('A description to display on the payment page', nil, false),
+      :template_url => ConfigField.new('The url for the template to use on the payment page', nil, false)
+    }
+
+
+    # ========================
+    # Setup the adapter config
+    # ========================
+
+    # Accessor to the adapter config
+    def self.adapter_config
+      @adapter_config ||= Omnipay::Helpers.deep_dup(DEFAULT_ADAPTER_CONFIG)
+    end
+
+    # Add a new config field to the adapter.
+    # Is mandatory and unfilled. 
+    # If default value or optional => should be a payment config
+    def self.config(name, explaination)
+      adapter_config[name] = ConfigField.new(explaination, nil, true)
+    end
+
+
+    # ====================================
+    # Setup the payment redirection config
+    # ====================================
+
+    # Accessor to the payment config
+    def self.payment_config
+      @payment_config ||= Omnipay::Helpers.deep_dup(DEFAULT_PAYMENT_CONFIG)
+    end
+
+    # Add a new field to the payment config
+    # Options are :mandatory (default false) and :default (default nil)
+    def self.custom_payment_param(name, explaination, opts = {})
+      if payment_config.has_key?(name)
+        raise ArgumentError, "Cannot add custom payment param #{name}, as it already exists and is : #{payment_config[name].explaination}"
+      end
+      payment_config[name] = ConfigField.new(explaination, opts[:default], !!opts[:mandatory])
+    end
+
+    # Setup default values for existing payment params
+    def self.default_payment_params(default_values)
+      default_values.each do |name, default_value|
+        payment_config[name] && ( payment_config[name].value = default_value )
+      end
+    end
+
+
+    # ===================
+    # Setup if IPN or not
+    # ===================
+
+    def self.enable_ipn
+      @ipn_enabled = true
+    end
+
+    def self.ipn?
+      !!@ipn_enabled
+    end
+
+
+    # =============================
+    # Actual adapter instance logic
+    # =============================
+
+    def initialize(config = {})
+      payment_config = config.delete(:payment)
+
+      @adapter_config = build_adapter_config(config)
+      @payment_config = build_payment_config(payment_config)
+    end
+
+
+    # Config easy readers
+    # from : {:foo => ConfigField(..., value='bar')}
+    # to   : config.foo # => 'bar'
+    def config
+      @config ||= OpenStruct.new(Hash[@adapter_config.map{|name, config_field| [name, config_field.value]}])
+    end
+
+    def default_payment_params
+      @default_payment_params ||= OpenStruct.new(Hash[@payment_config.map{|name, config_field| [name, config_field.value]}])
+    end
+
+
+    # ================
+    # Public interface
+    # ================
+
+    def request_phase(params, ipn_url, callback_url)
+      payment_params = Omnipay::Helpers.deep_dup(@payment_config)
+
+      # Merge params with default payment config
+      params.each do |name, value|
+        payment_params[name] && payment_params[name].value = value
+      end
+
+      # Validate payment params
+      payment_params.each do |name, config_field|
+        if config_field.mandatory && config_field.value.nil?
+          raise ArgumentError, "Mandatory payment parameter #{name} is not defined. It is supposed to be #{config_field.explaination}"          
+        end
+      end
+
+      # {name => config_field} to OpenStruct(name => value)
+      payment_params = OpenStruct.new(
+        Hash[ payment_params.map{|name, config_field| [name, config_field.value]} ]
+      )
+
+      # Forward to the right method (redirection_with_ipn or redirection)
+      if self.class.ipn?
+        return payment_page_redirection_ipn(payment_params, ipn_url, callback_url)
+      else
+        return payment_page_redirection(payment_params, callback_url)
+      end
+    end
+
+
+    def ipn_hash(request)
+      request = Rack::Request.new(request.env.dup)
+      return validate_payment_notification(request)
+    end
+
+
+    def callback_hash(request)
+      request = Rack::Request.new(request.env.dup)
+      return validate_callback_status(request)
+    end
+
+
+    # ===============================
+    # Logic to redefine in subclasses
+    # ===============================
+
+    def payment_page_redirection(params, callback_url)      
+      raise NoMethodError, "To redefine in adapter implementation"
+    end
+
+    def payment_page_ipn_redirection(params, ipn_url, callback_url)
+      raise NoMethodError, "To redefine in adapter implementation"
+    end
+
+
+    def validate_payment_notification(request)
+      raise NoMethodError, "To redefine in adapter implementation"
+    end
+
+
+    def validate_callback_status(request)
+      raise NoMethodError, "To redefine in adapter implementation"
+    end
+
+
+    protected
+
+    # ==========================
+    # Helpers to format response
+    # ==========================
+
+    def payment_error(message)
+      status_error(message)
+    end
+
+    def payment_failed(reference, reason)
+      status_failed(reason).merge(
+        :reference => reference
+      )
+    end
+
+    def payment_canceled(reference)
+      status_canceled.merge(
+        :reference => reference
+      )
+    end
+
+    def payment_successful(reference, transaction_id, amount)
+      status_successful(reference).merge(
+        :amount => amount,
+        :transaction_id => transaction_id
+      )
+    end
+
+
+    def status_error(message = '')
+      {:success => false, :status => Omnipay::INVALID_RESPONSE, :error_message => message}
+    end
+
+    def status_failed(message = '')
+      {:success => false, :status => Omnipay::PAYMENT_REFUSED, :error_message => message}
+    end
+
+    def status_canceled
+      {:success => false, :status => Omnipay::CANCELATION}
+    end
+
+    def status_successful(reference)
+      {:success => true,  :status => Omnipay::SUCCESS, :reference => reference}
+    end
+
+
+    private
+
+    # Build the instance adapter config from the class one and a hash of value overrides
+    def build_adapter_config(overrides)
+      # Clone the default config
+      adapter_config = Omnipay::Helpers.deep_dup(self.class.adapter_config)
+
+      # Override its values
+      overrides.each do |name, value|
+        next unless adapter_config.has_key? name
+        adapter_config[name].value = value
+      end
+
+      # Validate it
+      adapter_config.each do |name, config_field|
+        if config_field.mandatory && config_field.value == nil
+          raise ArgumentError, "Mandatory config field #{name} is not defined. It is supposed to be #{config_field.explaination}"
+        end
+      end
+
+      return adapter_config
+    end
+
+
+    # Build the instance payment config from the class one and a hash of value overrides
+    def build_payment_config(overrides)
+      overrides ||= {} # Nil can be passed as an argument
+
+      # Clone the default config
+      payment_config = Omnipay::Helpers.deep_dup(self.class.payment_config)
+
+      # Override its values
+      overrides.each do |name, value|
+        next unless payment_config.has_key? name
+        payment_config[name].value = value
+      end
+
+      # No validation, done at the redirection time
+      return payment_config
+    end
+
+  end
+
+end

data/lib/omnipay/configuration.rb

@@ -3,11 +3,15 @@ require 'singleton'
 module Omnipay
 
   # The global Omnipay configuration singleton
+  # Can be assigned the following values : 
+  # - +base_path+ (default "/pay") : the base path which will be hit in the payment providers callbacks.
+  # - +base_uri+ (default nil) : the base uri (scheme + host + port) which will be hit in the payment providers callbacks.
   class Configuration
     include Singleton
-    attr_accessor :base_path
+    attr_accessor :base_path, :base_uri
 
     def initialize
+      @base_uri = nil
       @base_path = "/pay"
     end
   end

data/lib/omnipay/gateway.rb

@@ -1,10 +1,18 @@
 module Omnipay
 
-  # Instance of a gateway connection. Has an uid, and encapsulates an adapter strategy
+  # Instance of a gateway connection. Has an uid, and encapsulates an adapter strategy.
   class Gateway
 
     attr_reader :uid, :adapter_class, :config, :adapter
 
+    # @param opts [Hash] 
+    #
+    # The options hash must include the following keys :
+    #  - :uid => the gateways uid
+    #  - :adapter => the adapter class
+    #
+    # The options hash may also include the following keys :
+    #  - :config => the configration hash passed to the adapter for its initialization
     def initialize(opts = {})
       @uid            = opts[:uid]
       @adapter_class  = opts[:adapter]
@@ -18,19 +26,23 @@ module Omnipay
 
 
     # The Rack::Response corresponding to the redirection to the payment page
+    # @param opts [Hash] The attributes of the current payment. Will be passed on to the adapter.
+    # The options hash must contain the following keys : 
+    # - +:base_uri+ : the current http scheme + host (used in the post-payment redirection)
+    # - +:amount [Integer]+ : the amount to pay, in cents
+    # Depending on the adapter used, the options hash may have other mandatory keys. Refer to the adapter's documentation for more details
+    # @return [Rack::Response] the GET or POST redirection to the payment provider
     def payment_redirection(opts = {})
-      host = opts.delete :host
-      amount = opts.delete :amount
+      base_uri = get_base_uri(opts)
+      raise ArgumentError.new('Missing parameter :base_uri') unless base_uri
 
-      raise ArgumentError.new('Missing parameter :host') unless host
-      raise ArgumentError.new('Missing parameter :amount') unless amount
+      ipn_url      = "#{base_uri}#{Omnipay.configuration.base_path}/#{uid}/ipn"
+      callback_url = "#{base_uri}#{Omnipay.configuration.base_path}/#{uid}/callback"
 
-      callback_url = "#{host}#{Omnipay.configuration.base_path}/#{uid}/callback"
-
-      method, url, params = @adapter.request_phase(amount, callback_url, opts)
+      method, url, params = @adapter.request_phase(opts, ipn_url, callback_url)
 
       if method == 'GET'
-        redirect_url = url + '?' + Rack::Utils.build_query(params)
+        redirect_url = url + (url.include?('?') ? '&' : '?') + Rack::Utils.build_query(params)
         Rack::Response.new.tap{|response| response.redirect(redirect_url)}
 
       elsif method == 'POST'
@@ -44,12 +56,38 @@ module Omnipay
     end
 
 
-    # The response hash
-    def formatted_response_for(params)
-      @adapter.callback_hash(params).merge(:raw => params)
+    # The formatted response hashes
+    # @return [Hash] the processed response which will be present in the request environement under 'omnipay.response'
+    def ipn_hash(request)
+      @adapter.ipn_hash(request).merge(:raw => request.params)
+    end
+
+    def callback_hash(request)
+      @adapter.callback_hash(request).merge(:raw => request.params)
     end
 
 
+    # Is IPN enabled?
+    def ipn_enabled?
+      @adapter_class.ipn?
+    end
+
+
+    private
+
+    def get_base_uri(opts)
+      base_uri = opts.delete :base_uri
+
+      if !base_uri && opts[:host]
+        base_uri = opts.delete :host
+        Kernel.warn "[DEPRECATION] `host` is deprecated.  Please use `base_uri` instead."
+      end
+
+      base_uri ||= Omnipay.configuration.base_uri
+
+      base_uri
+    end
+
   end
 
 end

data/lib/omnipay/gateways.rb

@@ -3,7 +3,6 @@ module Omnipay
   # Structure responsible for storing and accessing the application's configured gateways
   class Gateways
 
-
     def initialize
       @gateways = {}
       @dynamic_configs = [] # Collection of procs which given a uid may or may not return a gateway config hash
@@ -11,6 +10,14 @@ module Omnipay
 
 
     # Add a new gateway, static or dynamic
+    #
+    # Can be initialized via a config hash, or a block.
+    #
+    # If initialized with a hash, it must contains the `:uid` and `:adapter` keys
+    #
+    # If initialized with a block, the block must take the uid as an argument, and return a config hash with an `:adapter` key
+    # @param opts [Hash] the gateway configuration, if static.
+    # @param block [Proc] the gateway configuration, if dynamic.
     def push(opts = {}, &block)
       if block_given?
         @dynamic_configs << Proc.new(&block)
@@ -24,7 +31,9 @@ module Omnipay
     end
 
 
-    # Find and/or instanciate a gateway for the given uid
+    # Find a static gateway or instanciate a dynamic gateway for the given uid
+    # @param uid [String] the gateway's uid
+    # @return [Gateway] the corresponding gateway, or nil if none
     def find(uid)
       gateway = @gateways[uid]
       return gateway if gateway

data/lib/omnipay/helpers.rb

@@ -0,0 +1,15 @@
+module Omnipay
+
+  module Helpers
+
+    # Deep hash clone
+    def self.deep_dup(hash)
+      hash.inject({}) do |clone, (key, value)|
+        clone[key] = value.dup
+        clone
+      end
+    end
+
+  end
+
+end

data/lib/omnipay/middleware.rb

@@ -18,6 +18,8 @@ module Omnipay
 
     # The standard rack middleware call. Will be processed by an instance of RequestPhase or CallbackPhase if the
     # path matches the adapter's uid. Will forward to the app otherwise
+    # @param env [Hash] the request's environment
+    # @return [Rack::Reponse]
     def call(env)
 
       # Get the current request
@@ -31,16 +33,18 @@ module Omnipay
       gateway = Omnipay.gateways.find(uid)
       return @app.call(env) unless gateway
 
+      # Handle the IPN phase
+      return call_ipn(request, gateway) if ipn_phase?(request, uid)
+
       # Handle the callback phase
       if callback_phase?(request, uid)
-        # Symbolize the params keys
-        params = Hash[request.params.map{|k,v|[k.to_sym,v]}]
 
-        # Set the formatted response
-        request.env['omnipay.response'] = gateway.formatted_response_for(params)
+        # If no IPN : send the ipn request before
+        if !gateway.ipn_enabled?
+          call_ipn(request, gateway, :force => true)
+        end
 
-        # Force a get request
-        request.env['REQUEST_METHOD'] = 'GET'
+        return call_callback(request, gateway)
       end
 
       # Forward to the app
@@ -51,8 +55,48 @@ module Omnipay
 
     private
 
+    def ipn_path(uid)
+      "#{Omnipay.configuration.base_path}/#{uid}/ipn"
+    end
+
+    def callback_path(uid)
+      "#{Omnipay.configuration.base_path}/#{uid}/callback"
+    end
+
+    def ipn_phase?(request, uid)
+      request.path == ipn_path(uid)
+    end
+
     def callback_phase?(request, uid)
-      request.path == "#{Omnipay.configuration.base_path}/#{uid}/callback"
+      request.path == callback_path(uid)
+    end
+
+    def call_ipn(request, gateway, opts = {})
+      # Force : override the path
+      if opts[:force]
+        request = Rack::Request.new(request.env.dup)
+        request.path_info = ipn_path(gateway.uid)
+      end
+
+      # Set the formatted response
+      request.env['omnipay.response'] = gateway.ipn_hash(request)
+
+      # Force a POST on the app
+      request.env['REQUEST_METHOD'] = 'POST'
+
+      # Call the app
+      @app.call(request.env)
+    end
+
+    def call_callback(request, gateway)
+      # Set the formatted response
+      request.env['omnipay.response'] = gateway.callback_hash(request)
+
+      # Force a get request
+      request.env['REQUEST_METHOD'] = 'GET'
+
+      # Call the app
+      @app.call(request.env)
     end
 
 

data/lib/omnipay/railtie.rb

@@ -4,10 +4,10 @@ module Omnipay
     module Helpers
 
       def redirect_to_payment(uid, opts = {})
-        app_host = "#{request.scheme}://#{request.host_with_port}"
+        base_uri = "#{request.scheme}://#{request.host_with_port}"
         gateway = Omnipay.gateways.find(uid)
         if gateway
-          rack_response = gateway.payment_redirection(opts.merge(:host => app_host))
+          rack_response = gateway.payment_redirection(opts.merge(:base_uri => base_uri))
 
           self.response_body = rack_response.body
           self.status = rack_response.status
@@ -22,7 +22,11 @@ module Omnipay
     end
   end
 
-
+  # Custom helpers for rails applications
+  # Define the method : <b>+ActionController#redirect_to_payment(uid, opts={})+</b>
+  # - <b>+uid+</b> : the gateway's uid
+  # - <b>+opts+</b> : the options expected by Gateway#payment_redirection. The host is automatically determined, but the <b>+amount+</b> in cents, and other mandatory options depending on the adapter, have to be specified.
+  # Called in a controller, this method redirects the visitor to the payment provider.
   class Railtie < Rails::Railtie
 
     initializer "omnipay.configure_rails_initialization" do

data/lib/omnipay/sample_adapter.rb

@@ -0,0 +1,114 @@
+module Omnipay
+  module Adapters
+
+    # This is a sample Omnipay adapter implementation for a fictive payment provider. You can use it as a boilerplate to develop your own.
+    #
+    # This adapter will take two arguments in its configuration :
+    # * *api_key* [String - mandatory] : given by the payment provider, used for authenticating to their API
+    # * *sandbox* [Boolean - optional] : whether the payment should be done in a sandbox or with the real payment page
+    # It may then be set up like this in a rack application
+    #   Omnipay.use_gateway(
+    #     :uid => 'my_gateway',
+    #     :adapter => Omnipay::Adapters::SampleAdapter,
+    #     :config => {
+    #       :api_key => 'my-api-key',
+    #       :sandbox => (ENV['RACK_ENV'] != 'production')
+    #     }
+    #   )
+    #
+    # Let's say our payment provider needs to be given the birthdate of the buyer for every payment. It also accepts a locale to display the payment page in
+    # It means that the redirection to the payment provider will be called like this :
+    #   my_gateway = Omnipay.gateways.find('my_gateway')
+    #   my_gateway.payment_redirection({
+    #     :amount => 1295, # Amount in cents, mandatory for every adapter
+    #     :host => 'http://www.my-website.com', # Also mandatory for every adapter, used to compute the redirect_url
+    #     :birthdate => current_user.birthdate, # Custom field for this adapter class
+    #     :locale => 'fr' # Optional field for this adapter class
+    #   })
+    class SampleAdapter
+
+      # The adapters initialization
+      # @param config [Hash] the adapter's configuration which will be populated in the application's omnipay config file. For the example above in a dev environment, the value would be {:api_key => 'my-api-key', :sandbox => true}. It is up to you to decide which fields are mandatory, and to both check them in this initializer and specify them in your documentation. In this case :
+      #   * +api_key+ : the API key given for your fictive gateway's account. Mandatory
+      #   * +sandbox+ : whether to use a sandboxed payment page, or a real one. Optional and defaults to true
+      # @return [SampleAdapter]
+      def initialize(config = {})
+        @api_key = config[:api_key]
+        raise ArgumentError.new("Missing api_key") unless @api_key
+
+        @mode = (config[:sandbox] == false) ? 'production' : 'sandbox'
+      end
+
+
+      # Responsible for determining the redirection to the payment page for a given amount
+      # 
+      # @param amount [Integer] the amount **in cents** that the user has to pay
+      # @param callback_url[String] where the user has be redirected after its payment
+      # @param params [Hash] the additional GET parameters sent to the omnipay payment URL. This is where you check wether the arguments expected by your the payment provider are present. In this case, we check : 
+      #  * +birthdate+ The user's birth date. Mandatory because expected by the provider
+      #  * +locale+ The language of the payment page. No required
+      # @return [Array] an array containing the 4 following values :
+      #  * +[String]+ 'GET' or 'POST' : the HTTP method to use for redirecting to the payment page
+      #  * +[String]+ the absolute URL of the payment page. Example : "https\://my-provider.tld/sc12fdg57df"
+      #  * +[Hash]+   the GET or POST parameters to send to the payment page
+      def request_phase(amount, callback_url, params={})
+        # Check our params
+        birthdate = params[:birthdate] && params[:birthdate].to_date
+        raise ArgumentError.new('parameter birthdate must be given') if birthdate.blank?
+
+        locale = params[:locale] || 'en'
+
+        # Build the transaction (this is where the provider-specific code happens)
+        amount_in_dollar = (amount.to_f / 100).round(2)
+        payment_params = build_transaction_for_provider(amount, birthdate, locale, callback_url)
+
+        # Return the redirection details (method, url, params)
+        return ['GET', 'http://my-provider-payment-endpoint.com', payment_params]
+      end
+     
+
+      # Analyze the redirection from the payment provider, to determine if the payment is a success, and its details
+      # @param params [Hash] the GET/POST parameters sent by the payment gateway to the callback url
+      # @return [Hash] the resulting response hash which will be accessible in the application. Must contain the following values :
+      #  * *:success* (+Boolean+) | Did the payment occur or not?
+      #  * *:transaction_id* (+String+) <i>if successful</i> | The id of the transaction.
+      #  * *:error* (+Symbol+) <i>if failed</i> | The reason why the payment was not successful. The available values are :
+      #    * _Omnipay::CANCELED_ : The payment didn't occur because of the user.
+      #    * _Omnipay::PAYMENT_REFUSED_ : The payment didn't occue because of an error on the gateway's side.
+      #    * _Omnipay::INVALID_RESPONSE_ : The response from the gateway cannot be parsed. The payment may or may not have occured.
+      #  * *:error_message* (+String+) <i>if failed</i> | A more detailed error message / stack trace, for logging purposes
+      def callback_hash(params)
+
+        transaction_id = params[:transaction_id]
+        transaction = fetch_transaction(transaction_id)
+
+        if !transaction
+          return { :success => false, :error => Omnipay::INVALID_RESPONSE, :error_message => "No transaction found with id #{transaction_id}"}
+        end
+
+        if transaction.success
+          { :success => true, :transaction_id => transaction_id }
+        else
+          if transaction.canceled
+            { :success => false, :error => Omnipay::CANCELATION }
+          else
+            { :success => false, :error => Omnipay::PAYMENT_REFUSED, :error_message => "Transaction #{transaction_id} was not successful : #{transaction.error}" }
+          end
+        end
+      end
+
+
+      private
+
+      def build_new_transaction(amount, locale)
+        # TODO        
+      end
+
+      def fetch_transaction(transaction_id)
+        # TODO
+      end
+
+    end
+
+  end
+end

data/lib/omnipay/version.rb

@@ -1,3 +1,3 @@
 module Omnipay
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnipay
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - ClicRDV
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-20 00:00:00.000000000 Z
+date: 2014-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -47,16 +47,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/omnipay.rb
-- lib/omnipay/adapters/mangopay.rb
-- lib/omnipay/adapters/mangopay/client.rb
-- lib/omnipay/adapters/oneclicpay.rb
-- lib/omnipay/adapters/sample_adapter.rb
+- lib/omnipay/adapter.rb
 - lib/omnipay/autosubmit_form.rb
 - lib/omnipay/configuration.rb
 - lib/omnipay/gateway.rb
 - lib/omnipay/gateways.rb
+- lib/omnipay/helpers.rb
 - lib/omnipay/middleware.rb
 - lib/omnipay/railtie.rb
+- lib/omnipay/sample_adapter.rb
 - lib/omnipay/version.rb
 homepage: https://github.com/clicrdv/omnipay
 licenses: []
@@ -77,9 +76,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: '[none]'
-rubygems_version: 2.0.6
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Payment gateway abstraction for rack applications.
 test_files: []
-has_rdoc: 

data/lib/omnipay/adapters/mangopay.rb

@@ -1,138 +0,0 @@
-# Omnipay adapter for mangopay
-# documentation : http://docs.mangopay.com/api-references/
-#
-# Configuration :
-# - client_id:string (mandatory) : client id of your mangopay account
-# - client_passphrase:string (mandatory) : the passphrase for your account
-# - wallet_id:string (mandatory) : the wallet to be credited with the payments
-
-require 'omnipay/adapters/mangopay/client'
-
-module Omnipay
-  module Adapters
-
-    class Mangopay
-
-      attr_reader :client
-
-      def initialize(config = {})
-
-        raise ArgumentError.new("Missing client_id, client_passphrase, or wallet_id parameter") unless [config[:client_id], config[:client_passphrase], config[:wallet_id]].all?
-
-        @client = Client.new(config[:client_id], config[:client_passphrase], :sandbox => !!config[:sandbox])
-        @wallet_id = config[:wallet_id]
-
-      end
-
-
-      def request_phase(amount, callback_url, params = {})
-
-        transaction_id, redirect_url = create_web_payin(amount, callback_url, params)
-
-        # Generate the path and query parameters from the returned redirect_url string
-        uri = URI(redirect_url)
-
-        return [
-          'GET', 
-          "#{uri.scheme}://#{uri.host}#{uri.path}", 
-          Rack::Utils.parse_nested_query(uri.query), 
-          transaction_id
-        ]
-
-      end
-
-
-      def callback_hash(params)
-
-        transaction_id = params[:transactionId]
-
-        begin
-          response = @client.get "/payins/#{transaction_id}"
-        rescue Mangopay::Client::Error => e
-          return {
-            :success => false,
-            :error => Omnipay::INVALID_RESPONSE,
-            :error_message => "Could not fetch details of transaction #{transaction_id}"
-          }
-        end
-
-        # Check if the response is valid
-        if response['code'] != 200
-          return {
-            :success => false,
-            :error => Omnipay::INVALID_RESPONSE
-          }
-        end
-
-
-        # Successful transaction
-        if response['Status'] == 'SUCCEEDED'
-          {
-            :success => true,
-            :amount => response['DebitedFunds']['Amount'],
-            :transaction_id => transaction_id
-          }
-        else
-
-          # Cancelation
-          if ['101001', '101002'].include? response['ResultCode']
-            {
-              :success => false,
-              :error => Omnipay::CANCELATION
-            }
-          else
-            {
-              :success => false,
-              :error => Omnipay::PAYMENT_REFUSED,
-              :error_message => "Refused payment for transaction #{transaction_id}.\nCode : #{response['ResultCode']}\nMessage : #{response['ResultMessage']}"
-            }
-          end
-        end
-      end
-
-
-      private
-
-      def create_web_payin(amount, callback_url, params)
-
-        # Create a user
-        random_key = "#{Time.now.to_i}-#{(0...3).map { ('a'..'z').to_a[rand(26)] }.join}"
-        user_params = {
-          :Email => "user-#{random_key}@host.tld",
-          :FirstName => "User #{random_key}",
-          :LastName => "User #{random_key}",
-          :Birthday => Time.now.to_i,
-          :Nationality => "FR",
-          :CountryOfResidence => "FR"
-        }
-
-        user_id = (@client.post('/users/natural', user_params))["Id"]
-
-        # Create the web payin        
-        payin_params = {
-          :AuthorId => user_id, 
-          :DebitedFunds => {
-            :Currency => 'EUR',
-            :Amount => amount
-          },
-          :Fees => {
-            :Currency => 'EUR',
-            :Amount => 0
-          },
-          :CreditedWalletId => @wallet_id,
-          :ReturnURL => callback_url,
-          :Culture => (params[:locale] || 'fr').upcase,
-          :CardType => 'CB_VISA_MASTERCARD',
-          :SecureMode => 'FORCE'
-        }
-
-        payin = @client.post '/payins/card/web', payin_params
-
-        # Return the transaction reference, and the full redirection url
-        return [payin["Id"], payin["RedirectURL"]]
-      end
-
-    end
-
-  end
-end

data/lib/omnipay/adapters/mangopay/client.rb

@@ -1,71 +0,0 @@
-# Client for the mangopay API
-
-require 'httparty'
-require 'json'
-
-module Omnipay
-  module Adapters
-    class Mangopay
-
-      class Client
-
-        class Error < ::StandardError ; end
-
-        include HTTParty
-
-        format :json
-
-        headers 'Accept' => 'application/json'
-        headers 'Content-Type' => 'application/json'
-
-        def initialize(key, secret, opts = {})
-          @key = key
-          @secret = secret
-
-          if opts[:sandbox]
-            @base_uri = 'https://api.sandbox.mangopay.com/v2'
-          else
-            @base_uri = 'https://api.mangopay.com/v2'
-          end
-        end
-
-        def get(path)
-          response = self.class.get "/#{@key}#{path}", 
-            :basic_auth => {:username => @key, :password => @secret}, 
-            :base_uri => @base_uri
-
-          check_errors(response)
-
-          response.parsed_response.merge("code" => response.code)
-        end
-
-        def post(path, params = {})
-          response = self.class.post "/#{@key}#{path}", 
-            :body => params.to_json,
-            :basic_auth => {:username => @key, :password => @secret},
-            :base_uri => @base_uri
-
-          check_errors(response)
-
-          response.parsed_response.merge("code" => response.code)
-        end
-
-
-        private
-
-        def check_errors(response)
-          # nocommit, log the request :/
-          if response.code != 200
-            error_message = response.parsed_response.merge(
-              "code" => response.code
-            )
-
-            raise Error, error_message.inspect
-          end
-        end
-
-      end
-
-    end
-  end
-end

data/lib/omnipay/adapters/oneclicpay.rb

@@ -1,132 +0,0 @@
-# Omnipay adapter for oneclicpay
-# documentation : docs.oneclicpay.com
-#
-# Configuration :
-# - tpe_id:string (mandatory) : serial number of your virutal payment terminal
-# - secret_key:string (mandatory) : security key for your account
-# - sandbox:boolean (default: false) : use the sandbox or the production environment
-
-require 'base64'
-require 'digest'
-require 'httparty'
-
-module Omnipay
-  module Adapters
-
-    class Oneclicpay
-
-      HTTP_METHOD = 'POST'
-
-      REDIRECT_URLS = {
-        :sandbox => 'https://secure.homologation.oneclicpay.com',
-        :production => 'https://secure.oneclicpay.com'
-      }
-
-      VALIDATION_URLS = {
-        :sandbox => 'https://secure.homologation.oneclicpay.com:60000',
-        :production => 'https://secure.oneclicpay.com:60000'
-      }
-
-      def initialize(config = {})
-        @tpe_id = config[:tpe_id]
-        @secret_key = config[:secret_key]
-        @is_sandbox = config[:sandbox]
-
-        raise ArgumentError.new("Missing tpe_id or secret_key parameter") unless [@tpe_id, @secret_key].all?
-      end
-
-
-      def request_phase(amount, callback_url, params={})
-        product_name = params[:title] || ''
-        transaction_id = params[:transaction_id] || random_transaction_id
-        locale = params[:locale] || 'fr'
-
-        [
-          HTTP_METHOD,
-          redirect_url,
-          redirect_params_for(amount, product_name, transaction_id, locale, callback_url),
-          transaction_id
-        ]
-      end
-
-
-      def callback_hash(params)
-
-        if params[:result] == "NOK" && params[:reason] == "Abandon de la transaction."
-          return { :success => false, :error => Omnipay::CANCELATION }
-        end
-
-
-        if params[:result] == "OK"
-
-          # Validate the response via the API
-          transaction_id = params[:transactionId]
-          amount = get_transaction_amount(transaction_id)
-
-          if amount
-            { :success => true, :amount => amount, :transaction_id => transaction_id }
-          else
-            { :success => false, :error => Omnipay::INVALID_RESPONSE, :error_message => "Could not fetch the amount of the transaction #{transaction_id}" }
-          end
-
-
-        elsif params[:result] == "NOK"
-          { :success => false, :error => Omnipay::PAYMENT_REFUSED, :error_message => params[:reason] }
-
-        else
-          { :success => false, :error => Omnipay::INVALID_RESPONSE, :error_message => "No :result key in the params #{params.inspect}" }
-        end
-      end
-
-
-      private
-
-      def redirect_params_for(amount, product_name, transaction_id, locale, callback_url)
-        {
-          :montant => (amount.to_f/100).to_s,
-          :idTPE => @tpe_id,
-          :idTransaction => transaction_id,
-          :devise => 'EUR',
-          :lang => locale,
-          :nom_produit => product_name,
-          :urlRetourOK => callback_url,
-          :urlRetourNOK => callback_url
-        }.tap{|params|
-          params[:sec] = signature(params)
-        }
-      end
-
-      def random_transaction_id
-        "#{Time.now.to_i}-#{@tpe_id}-#{random_token}"
-      end
-
-      def random_token
-        (0...3).map { ('a'..'z').to_a[rand(26)] }.join
-      end
-
-      def signature(params)
-        to_sign = (params.values + [@secret_key]).join('|')
-        Digest::SHA512.hexdigest(Base64.encode64(to_sign).gsub(/\n/, ''))
-      end
-
-      def get_transaction_amount(transaction_id)
-        response = HTTParty.post(
-          "#{validation_url}/rest/payment/find?serialNumber=#{@tpe_id}&key=#{@secret_key}&transactionRef=#{transaction_id}",
-          :headers => {'content-type' => "application/x-www-form-urlencoded"} # For ruby 1.8.7
-        )
-        
-        (response.parsed_response["transaction"][0]["ok"] != 0) && response.parsed_response["transaction"][0]["amount"]
-      end
-
-      def redirect_url
-        @is_sandbox ? REDIRECT_URLS[:sandbox] : REDIRECT_URLS[:production]
-      end
-
-      def validation_url
-        @is_sandbox ? VALIDATION_URLS[:sandbox] : VALIDATION_URLS[:production]
-      end
-
-    end
-
-  end
-end

data/lib/omnipay/adapters/sample_adapter.rb

@@ -1,115 +0,0 @@
-module Omnipay
-  module Adapters
-
-    # This is a sample Omnipay adapter implementation for a fictive payment gateway. You can use it as a boilerplate to develop your own.
-    #
-    # This adapter will take two arguments in its configuration :
-    # * *api_key* [String - mandatory] : given by the payment gateway, used for authenticating to their API
-    # * *sandbox* [Boolean - optional] : whether the payment should be done in a sandbox or with the real payment page
-    # It may then be initialized like this in a rack application
-    #   use Omnipay::Gateway, 
-    #         :uid => 'my-gateway',
-    #         :adapter => Omnipay::Adapters::SampleAdapter
-    #         :config => {
-    #           :api_key => 'my-api-key',
-    #           :sandbox => (ENV['RACK_ENV'] != 'production')
-    #         }
-
-    class SampleAdapter
-
-      # The adapters initialization
-      # @param callback_url [String] the absolute callback URL the user should be redirected to after the payment. Will be generated by Omnipay. Example value : "http\://\www\.my-host.tld/pay/my-gateway/callback"
-      # @param config [Hash] the adapter's configuration as defined in the application's omnipay config file. For the example above in a dev environment, the value would be {:api_key => 'my-api-key', :sandbox => true}. It is up to you to decide which fields are mandatory, and to both check them in this initializer and specify them in your documentation. In this case :
-      #   * *:api_key* [String] (mandatory) : the API key given for your fictive gateway's account
-      #   * *:sandbox* [Boolean] (optional) : whether to use a sandboxed payment page, or a real one. Defaults to true
-      # @return [SampleAdapter]
-      def initialize(config = {})
-        @api_key = config[:api_key]
-        raise ArgumentError.new("Missing api_key") unless @api_key
-
-        @mode = (config[:sandbox] == false) ? 'production' : 'sandbox'
-      end
-
-
-      # Responsible for determining the redirection to the payment page for a given amount
-      # 
-      # @param amount [Integer] the amount **in cents** that the user has to pay
-      # @param params [Hash] the GET parameters sent to the omnipay payment URL. Can be used to specify transaction-specific variables (the locale to use, the payment page's title, ...). Please use the following keys if you need to, for consistency among adapters :
-      #  * *locale* The ISO 639-1 locale code for the payment page
-      #  * *title* The title to display on the payment page
-      #  * *transaction_id* The transaction id to use, if you want the user to be able to force it
-      # @return [Array] an array containing the 4 following values :
-      #  * +[String]+ 'GET' or 'POST' : the HTTP method to use for redirecting to the payment page
-      #  * +[String]+ the absolute URL of the payment page. Example : "https\://my-provider.tld/sc12fdg57df"
-      #  * +[Hash]+   the GET or POST parameters to send to the payment page
-      #  * +[String]+ the unique transaction_id given by the payment provider for the upcoming payment. Has to be accessible in the callback phase. 
-
-      def request_phase(amount, calback_url, params={})
-        amount_in_dollar = amount * 1.0 / 100
-        locale = params[:locale] || 'en'
-
-        transaction = build_new_transaction(amount_in_dollars, callback_url, locale)
-
-        uri = URI(transaction.payment_url)
-
-        method = 'GET'
-        url = "#{uri.scheme}://#{uri.host}#{uri.path}"
-        get_params = Rack::Utils.parse_query(uri.query)
-        transaction_id = transaction.id
-
-        return [
-          method,
-          url,
-          get_params,
-          transaction_id
-        ]
-
-      end
-     
-
-      # @param params [Hash] the GET/POST parameters sent by the payment gateway to the callback url
-      # @return [Hash] the resulting response hash which will be accessible in the application. Must contain the following values :
-      #  * *:success* (+Boolean+) | Did the payment occur or not?
-      #  * *:amount* (+Integer+) <i>if successful</i> | The amount <b>in cents</b> actually payed
-      #  * *:transaction_id* (+String+) <i>if successful</i> | The id of the transaction. Must match the one returned in the request phase.
-      #  * *:error* (+Symbol+) <i>if failed</i> | The reason why the payment was not successful. The available values are :
-      #    * _Omnipay::CANCELED_ : The payment didn't occur because of the user.
-      #    * _Omnipay::PAYMENT_REFUSED_ : The payment didn't occue because of an error on the gateway's side.
-      #    * _Omnipay::INVALID_RESPONSE_ : The response from the gateway cannot be parsed. The payment may or may not have occured.
-      #  * *:error_message* (+String+) <i>if failed</i> | A more detailed error message / stack trace, for logging purposes
-
-      def callback_hash(params)
-
-        transaction_id = params[:transaction_id]
-        transaction = fetch_transaction(transaction_id)
-
-        if !transaction
-          return { :success => false, :error => Omnipay::INVALID_RESPONSE, :error_message => "No transaction found with id #{transaction_id}"}
-        end
-
-        if transaction.success
-          { :success => true, :amount => (transaction.amount*100).to_i, :transaction_id => transaction_id }
-        else
-          if transaction.canceled
-            { :success => false, :error => Omnipay::CANCELATION }
-          else
-            { :success => false, :error => Omnipay::PAYMENT_REFUSED, :error_message => "Transaction #{transaction_id} was not successful : #{transaction.error}" }
-          end
-        end
-      end
-
-
-      private
-
-      def build_new_transaction(amount, locale)
-        # TODO        
-      end
-
-      def fetch_transaction(transaction_id)
-        # TODO
-      end
-
-    end
-
-  end
-end