revo-remit 0.2.3

data/lib/remit/error_codes.rb

@@ -0,0 +1,118 @@
+# Scraped and categorized from http://docs.amazonwebservices.com/AmazonFPS/\
+# 2007-01-08/FPSDeveloperGuide/index.html?ErrorCodesTable.html. You can use
+# these categories to specify default error handling in your application such
+# as asking users to retry or sending an exception email.
+module Remit::ErrorCodes
+  class << self
+    def sender_error?(code)
+      SENDER.include? code.to_sym
+    end
+
+    def recipient_error?(code)
+      RECIPIENT.include? code.to_sym
+    end
+
+    def caller_error?(code)
+      CALLER.include?(code.to_sym)
+    end
+
+    def amazon_error?(code)
+      AMAZON.include? code.to_sym
+    end
+
+    def api_error?(code)
+      API.include? code.to_sym
+    end
+
+    def unknown_error?(code)
+      UNKNOWN.include? code.to_sym
+    end
+  end
+
+  SENDER = [
+    :InactiveAccount_Sender, # The sender's account is in suspended or closed state.
+    :InactiveInstrument, # The payment instrument used for this transaction is no longer active.
+    :InstrumentExpired, # The prepaid or the postpaid instrument has expired.
+    :InstrumentNotActive, # The prepaid or postpaid instrument used in the transaction is not active.
+    :InvalidAccountState_Sender, # Sender account cannot participate in the transaction.
+    :InvalidInstrumentForAccountType, # The sender account can use only credit cards
+    :InvalidInstrumentState, # The prepaid or credit instrument should be active
+    :InvalidTokenId_Sender, # The send token specified is either invalid or canceled or the token is not active.
+    :PaymentInstrumentNotCC, # The payment method specified in the transaction is not a credit card. You can only use a credit card for this transaction.
+    :PaymentInstrumentMissing, # There needs to be a payment instrument defined in the token which defines the payment method.
+    :TokenNotActive_Sender, # The sender token is canceled.
+    :UnverifiedAccount_Sender, # The sender's account must have a verified U.S. credit card or a verified U.S bank account before this transaction can be initiated
+    :UnverifiedBankAccount, # A verified bank account should be used for this transaction
+    :UnverifiedEmailAddress_Sender, # The sender account must have a verified e-mail address for this payment
+  ]
+
+  RECIPIENT = [
+    :InactiveAccount_Recipient, # The recipient's account is in suspended or closed state.
+    :InvalidAccountState_Recipient, # Recipient account cannot participate in the transaction
+    :InvalidRecipientRoleForAccountType, # The recipient account is not allowed to receive payments
+    :InvalidRecipientForCCTransaction, # This account cannot receive credit card payments.
+    :InvalidTokenId_Recipient, # The recipient token specified is either invalid or canceled.
+    :TokenNotActive_Recipient, # The recipient token is canceled.
+    :UnverifiedAccount_Recipient, # The recipient's account must have a verified bank account or a credit card before this transaction can be initiated.
+    :UnverifiedEmailAddress_Recipient, # The recipient account must have a verified e-mail address for receiving payments.
+  ]
+
+  CALLER = [
+    :InactiveAccount_Caller, # The caller's account is in suspended or closed state.
+    :InvalidAccountState_Caller, # The caller account cannot participate in the transaction
+    :InvalidTokenId_Caller, # The caller token specified is either invalid or canceled or the specified token is not active.
+    :TokenNotActive_Caller, # The caller token is canceled.
+    :UnverifiedEmailAddress_Caller, # The caller account must have a verified e-mail address
+  ]
+
+  AMAZON = [
+    :InternalError # A retriable error that happens due to some transient problem in the system.
+  ]
+
+  # bad syntax or logic
+  API = [
+    :AmountOutOfRange, # The transaction amount is more than the allowed range.
+    :BadRule, # One of the GK constructs is not well defined
+    :CannotSpecifyUsageForSingleUseToken, # Token usages cannot be specified for a single use token.
+    :ConcurrentModification, # A retriable error can happen due to concurrent modification of data by two processes.
+    :DuplicateRequest, # A different request associated with this caller reference already exists.
+    :IncompatibleTokens, # The transaction could not be completed because the tokens have incompatible payment instructions.
+    :InstrumentAccessDenied, # The external calling application is not the recipient for this postpaid or prepaid instrument. The caller should be the liability holder
+    :InvalidCallerReference, # The CallerReferece does not have a token associated with it.
+    :InvalidDateRange, # The end date specified is before the start date or the start date is in the future.
+    :InvalidEvent, # The event specified was not subscribed using the SubscribeForCallerNotification operation.
+    :InvalidParams, # One or more parameters in the request is invalid.
+    :InvalidPaymentInstrument, # The payment method used in the transaction is invalid.
+    :InvalidPaymentMethod, # Payment method specified in the GK construct is invalid.
+    :InvalidSenderRoleForAccountType, # This token cannot be used for this operation.
+    :InvalidTokenId, # The token that you are trying to cancel was not installed by you.
+    :InvalidTokenType, # Invalid operation performed on the token. Example, getting the token usage information on a single use token.
+    :InvalidTransactionId, # The specified transaction could not be found or the caller did not execute the transaction or this is not a Pay or Reserve call.
+    :InvalidTransactionState, # The transaction is not completed or it has been temporarily failed.
+    :InvalidUsageDuration, # The duration cannot be less than one hour.
+    :InvalidUsageLimitCount, # The usage count is null or empty.
+    :InvalidUsageStartTime, # The start time specified for the token is not valid.
+    :InvalidUsageType, # The usage type specified is invalid.
+    :OriginalTransactionIncomplete, # The original transaction is still in progress.
+    :OriginalTransactionFailed, # The original transaction has failed
+    :PaymentMethodNotDefined, # Payment method is not defined in the transaction.
+    :RefundAmountExceeded, # The refund amount is more than the refundable amount.
+    :SameTokenIdUsedMultipleTimes, # This token is already used in earlier transactions.
+    :SenderNotOriginalRecipient, # The sender in the refund transaction is not the recipient of the original transaction.
+    :SettleAmountGreaterThanReserveAmount, # The amount being settled is greater than the reserved amount.
+    :TransactionDenied, # This transaction is not allowed.
+    :TransactionExpired, # Returned when the Caller attempts to explicitly retry a transaction that is temporarily declined and is in queue for implicit retry.
+    :TransactionFullyRefundedAlready, # The complete refund for this transaction is already completed
+    :TransactionTypeNotRefundable, # You cannot refund this transaction.
+    :TokenAccessDenied, # Permission is denied to cancel the token.
+    :TokenUsageError, # The token usage limit is exceeded.
+    :UsageNotDefined, # For a multi-use token or a recurring token the usage limits are not specified in the GateKeeper text.
+  ]
+
+  # these errors don't specify who is at fault
+  UNKNOWN = [
+    :InvalidAccountState, # The account is either suspended or closed. Payment instructions cannot be installed on this account.
+    :InsufficientBalance, # The sender, caller, or recipient's account balance has insufficient funds to complete the transaction.
+    :AccountLimitsExceeded, # The spending or the receiving limit on the account is exceeded
+  ]
+end

data/lib/remit/get_pipeline.rb

@@ -0,0 +1,286 @@
+require 'erb'
+
+require 'remit/common'
+
+module Remit
+  module GetPipeline
+    class Pipeline
+
+      @parameters = []
+      attr_reader :parameters
+      
+      class << self
+        # Create the parameters hash for the subclass.
+        def inherited(subclass) #:nodoc:
+          subclass.instance_variable_set('@parameters', [])
+        end
+        
+        def parameter(name)
+          attr_accessor name
+          @parameters << name
+        end
+        
+        def convert_key(key)
+          key = key.to_s
+          if key == 'return_url'
+            :returnURL
+          else
+            key.gsub(/_(.)/) { $1.upcase }.to_sym
+          end
+        end
+        
+        # Returns a hash of all of the parameters for this request, including
+        # those that are inherited.
+        def parameters #:nodoc:
+          (superclass.respond_to?(:parameters) ? superclass.parameters : []) + @parameters
+        end
+      end
+      
+      attr_reader :api
+      attr_reader :pipeline_url
+      
+      parameter :caller_key
+      parameter :cobranding_style
+      parameter :cobranding_url
+      parameter :pipeline_name
+      parameter :return_url
+      parameter :signature
+      parameter :signature_version
+      parameter :signature_method
+      parameter :version
+      parameter :website_description
+
+      def initialize(api, pipeline, options)
+        @api = api
+        @pipeline_url = pipeline
+        
+        options.each do |k,v|
+          self.send("#{k}=", v)
+        end
+      end
+
+      def url
+        uri = URI.parse(self.pipeline_url)
+
+        query = {}
+        self.class.parameters.each do |p|
+          val = self.send(p)
+
+          # Convert Time values to seconds from Epoch
+          val = val.to_i if val.is_a?(Time)
+
+          query[self.class.convert_key(p)] = val
+        end
+
+        # Remove any unused optional parameters
+        query.reject! { |key, value| value.nil? }
+
+        uri.query = SignedQuery.new(self.pipeline_url, self.api.secret_key, query).to_s
+        uri.to_s
+      end
+      
+    end
+    
+    module ValidityPeriod
+      def self.included(base)
+        base.class_eval do
+          parameter :validity_expiry # Time or seconds from Epoch
+          parameter :validity_start # Time or seconds from Epoch
+        end
+      end
+    end
+
+    module UsageLimits
+      def self.included(base)
+        base.class_eval do
+          parameter :usage_limit_type_1
+          parameter :usage_limit_period_1
+          parameter :usage_limit_value_1
+          parameter :usage_limit_type_2
+          parameter :usage_limit_period_2
+          parameter :usage_limit_value_2
+        end
+      end
+    end
+
+    class RecipientPipeline < Pipeline
+      parameter :caller_reference
+      parameter :max_fixed_fee
+      parameter :max_variable_fee
+      parameter :payment_method
+      parameter :recipient_pays_fee
+      # BJM: missing??
+      # PHB: Amazon only documents this parameter as being part of responses, never as part of a request.
+      #       Not sure if it is a documentation oversight.
+      #       I am sure the documentation is terrible (with four fingers pointed back at me).
+      parameter :payment_reason
+
+      include ValidityPeriod
+
+      def pipeline_name
+        Remit::PipelineName::RECIPIENT
+      end
+    end
+
+    class SenderPipeline < Pipeline
+      # I think these should be moved down to the subclasses, or perhaps, all sender pipeline requests
+      parameter :address_name
+      parameter :address_line_1
+      parameter :address_line_2
+      parameter :city
+      parameter :state
+      parameter :zip
+      parameter :phone_number
+
+      def pipeline_name
+        raise NotImplementedError, 'SenderPipeline is abstract.  Use a concrete subclass.'
+      end
+    end
+
+    class SingleUsePipeline < SenderPipeline
+      parameter :caller_reference
+      parameter :collect_shipping_address
+      parameter :currency_code
+      parameter :discount
+      parameter :gift_wrapping
+      parameter :handling
+      parameter :item_total
+      parameter :payment_method
+      parameter :payment_reason
+      parameter :recipient_token
+      parameter :reserve
+      parameter :shipping
+      parameter :tax
+      parameter :transaction_amount
+
+      def pipeline_name
+        Remit::PipelineName::SINGLE_USE
+      end
+    end
+
+    class MultiUsePipeline < SenderPipeline
+      parameter :amount_type
+      parameter :caller_reference
+      parameter :collect_shipping_address
+      parameter :currency_code
+      parameter :global_amount_limit
+      parameter :is_recipient_cobranding
+      parameter :payment_method
+      parameter :payment_reason
+      parameter :recipient_token_list
+      parameter :transaction_amount
+
+      include ValidityPeriod
+      include UsageLimits
+
+      def pipeline_name
+        Remit::PipelineName::MULTI_USE
+      end
+    end
+    
+    class EditTokenPipeline < Pipeline
+      parameter :caller_reference
+      parameter :payment_method
+      parameter :token_id
+      
+      def pipeline_name
+        Remit::PipelineName::EDIT_TOKEN
+      end
+    end
+
+    class RecurringUsePipeline < SenderPipeline
+      parameter :caller_reference
+      parameter :collect_shipping_address
+      parameter :currency_code
+      parameter :is_recipient_cobranding
+      parameter :payment_method
+      parameter :payment_reason
+      parameter :recipient_token
+      parameter :recurring_period  
+      parameter :transaction_amount
+
+      include ValidityPeriod
+
+      def pipeline_name
+        Remit::PipelineName::RECURRING
+      end 
+    end
+
+    class PostpaidPipeline < SenderPipeline
+      parameter :caller_reference_sender
+      parameter :caller_reference_settlement
+      parameter :collect_shipping_address
+      parameter :credit_limit
+      parameter :currency_code
+      parameter :global_amount_limit
+      parameter :payment_method
+      parameter :payment_reason
+
+      include ValidityPeriod
+      include UsageLimits
+
+      def pipeline_name
+        Remit::PipelineName::SETUP_POSTPAID
+      end
+    end
+    
+    class PrepaidPipeline < SenderPipeline
+      parameter :caller_reference_funding
+      parameter :caller_reference_sender
+      parameter :collect_shipping_address
+      parameter :currency_code
+      parameter :funding_amount
+      parameter :payment_method
+      parameter :payment_reason
+
+      include ValidityPeriod
+
+      def pipeline_name
+        Remit::PipelineName::SETUP_PREPAID
+      end
+    end
+
+    class EditTokenPipeline < Pipeline
+      parameter :caller_reference
+      parameter :token_id
+      parameter :payment_method
+      
+      def pipeline_name
+        Remit::PipelineName::EDIT_TOKEN
+      end
+    end
+
+    def get_single_use_pipeline(options)
+      get_pipeline(Remit::GetPipeline::SingleUsePipeline, options)
+    end
+    def get_multi_use_pipeline(options)
+      get_pipeline(Remit::GetPipeline::MultiUsePipeline, options)
+    end
+    def get_recipient_pipeline(options)
+      get_pipeline(Remit::GetPipeline::RecipientPipeline, options)
+    end
+    def get_recurring_use_pipeline(options)
+      get_pipeline(Remit::GetPipeline::RecurringUsePipeline, options)
+    end
+    def get_postpaid_pipeline(options)
+      get_pipeline(Remit::GetPipeline::PostpaidPipeline, options)
+    end
+    def get_prepaid_pipeline(options)
+      get_pipeline(Remit::GetPipeline::PrepaidPipeline, options)
+    end
+    def get_edit_token_pipeline(options)
+      get_pipeline(Remit::GetPipeline::EditTokenPipeline, options)
+    end
+
+    def get_pipeline(pipeline_subclass, options)
+      # TODO: How does @pipeline_url work here?
+      #       instance variable is setup in initializer of class.
+      pipeline_subclass.new(self, @pipeline_url, {
+        :caller_key => @access_key,
+        :signature_version=>Remit::API::SIGNATURE_VERSION,
+        :signature_method=>Remit::API::SIGNATURE_METHOD,
+        :version=>Remit::API::PIPELINE_VERSION
+      }.merge(options))
+    end
+  end
+end

data/lib/remit/inbound_request.rb

@@ -0,0 +1,85 @@
+require 'remit/common'
+
+module Remit
+
+  class InboundRequest
+    include ConvertKey
+    extend SignatureUtilsForOutbound
+
+    protected :convert_key
+
+    attr_reader :supplied_signature
+    attr_reader :allow_sigv1
+    
+    # BJM: need to access sometimes from the app
+    attr_reader :hash_params
+    # signature key name
+    SIGNATURE_KEY = 'signature'
+
+    ##
+    # +request_url+ is the full request path up to the query string, as from request.url in the controller
+    # +params+ is the full params hash from the controller
+    # +client+ is a fully instantiated Remit::API with access keys and sandbox settings
+    #
+    # Only clean params hash is params is sent as a hash.
+    # Assume caller has cleaned string if string is sent as params
+    def initialize(request_url, params, client, options = {})
+      if params.is_a?(String)
+        @string_params = params
+        @hash_params = Hash.from_url_params(params)
+      else
+        unless options.kind_of?(Hash)
+          options = {}
+        end
+        options[:skip_param_keys] ||= []
+        #this is a bit of helpful sugar for rails framework users
+        options[:skip_param_keys] |= ['action','controller']
+
+        if params.respond_to?(:reject)
+          params.reject! {|key, val| options[:skip_param_keys].include?(key) }
+        else
+          params = {}
+        end
+        @hash_params      = params
+        @string_params    = InboundRequest.get_http_params(@hash_params)
+      end
+      #puts "Params are: #{params.inspect}"
+      @request_url        = request_url
+      @client             = client
+      @supplied_signature = @hash_params[self.class::SIGNATURE_KEY]
+      @allow_sigv1        = options[:allow_sigv1] || false
+    end
+    
+    def valid?
+      if @hash_params['signatureVersion'].to_i == 2
+        #puts "\nhash_params: #{@hash_params.inspect}\n"
+        #puts "\nstring_params: #{@string_params.inspect}\n"
+        return false unless InboundRequest.check_parameters(@hash_params)
+        verify_request = Remit::VerifySignature::Request.new(
+          :url_end_point => @request_url,#InboundRequest.urlencode(@request_url),
+          :version => Remit::API::API_VERSION,
+          :http_parameters => @string_params
+        )
+        #puts "\nurl_end_point#{@request_url.inspect}\n"
+        #puts "\nhttp_parameters: #{verify_request.http_parameters.inspect}\n"
+        result = @client.verify_signature(verify_request)
+        #puts "\nresult: #{result.raw.inspect}\n"
+        result.verify_signature_result.verification_status == 'Success'
+      elsif @hash_params['signatureVersion'].nil? and self.allow_sigv1
+        self.supplied_signature == Remit::API.signature_v1(URI.parse(@request_url).path, @hash_params, @client.secret_key).gsub('+', ' ')
+      else
+        false
+      end
+    end
+    
+    def method_missing(method, *args, &block) #:nodoc:
+      return @hash_params[method.to_s] if @hash_params.has_key?(method.to_s)
+      return @hash_params[method.to_sym] if @hash_params.has_key?(method.to_sym)
+      key = self.convert_key(method)
+      return @hash_params[key] if @hash_params.has_key?(key)
+      return @hash_params[key.to_s] if @hash_params.has_key?(key.to_s)
+      super
+    end
+  end
+
+end