remit 0.0.1 → 0.0.2

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2008 Tyler Hunt
+Copyright (c) 2007-2009 Tyler Hunt
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.markdown

@@ -0,0 +1,91 @@
+Remit
+=====
+
+This API provides access to the Amazon Flexible Payment Service (FPS). After
+trying to get the SOAP version of the API written, I began working on this REST
+version to provide a cohesive means of access to all of the functionality of
+the FPS without having to get dirty dealing with SOAP requests.
+
+I hope you enjoy using it as much as I've enjoyed writing it. I'm interested to
+hear what sort of uses you find for it. If you find any bugs, let me know (or
+better yet, submit a patch).
+
+
+Sandbox
+-------
+
+Amazon provides a testing environment for the FPS called a sandbox. You may
+(and should) use the sandbox while testing your application. It can be enabled
+by passing a value of true to the last argument of the API constructor.
+
+
+Getting Started
+---------------
+
+The following example shows how to load up the API, initialize the service, and
+make a simple call to get the tokens stored on the account:
+
+    gem 'remit'
+    require 'remit'
+
+    ACCESS_KEY = '<your AWS access key>'
+    SECRET_KEY = '<your AWS secret key>'
+
+    # connect using the API's sandbox mode
+    remit = Remit::API.new(ACCESS_KEY, SECRET_KEY, true)
+
+    response = remit.get_tokens
+    puts response.tokens.first.token_id
+
+
+Using with Rails
+----------------
+
+To use Remit in a Rails application, you must first specify a dependency on the
+Remit gem in your config/environment.rb file:
+
+    config.gem 'remit', :version => '~> 0.0.1'
+
+Then you should create an initializer to configure your Amazon keys. Create the
+file config/initializers/remit.rb with the following contents:
+
+    config_file = File.join(Rails.root, 'config', 'amazon_fps.yml')
+    config = YAML.load_file(config_file)[RAILS_ENV].symbolize_keys
+
+    FPS_ACCESS_KEY = config[:access_key]
+    FPS_SECRET_KEY = config[:secret_key]
+
+Then create the YAML file config/amazon_fps.yml:
+
+    development: &sandbox
+      access_key: <your sandbox access key>
+      secret_key: <your sandbox secret key>
+
+    test:
+      <<: *sandbox
+    
+    production:
+      access_key: <your access key>
+      secret_key: <your secret key>
+
+To instantiate and use the Remit API in your application, you could define a
+method in your ApplicationController like this:
+
+    def remit
+      @remit ||= begin
+        sandbox = !Rails.env.production?
+        Remit::API.new(FPS_ACCESS_KEY, FPS_SECRET_KEY, sandbox)
+      end
+    end
+
+
+Sites Using Remit
+-----------------
+
+The following production sites are currently using Remit:
+
+  * http://www.storenvy.com/
+  * http://www.obsidianportal.com/
+
+
+Copyright (c) 2007-2009 Tyler Hunt, released under the MIT license

data/lib/remit/common.rb

@@ -11,30 +11,28 @@ module Remit
       parameter :action, :value => name
     end
 
-    protected
-
     def convert_key(key)
       key.to_s.gsub(/(^|_)(.)/) { $2.upcase }.to_sym
     end
+    protected :convert_key
   end
 
   class BaseResponse < Relax::Response
-    private
-
-    def node_name(name)
-      name.to_s.gsub(/(^|_)(.)/) { $2.upcase }
+    def node_name(name, namespace=nil)
+      super(name.to_s.gsub(/(^|_)(.)/) { $2.upcase }, namespace)
     end
   end
 
   class Response < BaseResponse
     parameter :request_id
+
     attr_accessor :status
     attr_accessor :errors
 
     def initialize(xml)
       super
 
-      if is?(:Response) and has?(:Errors)
+      if is?(:Response) && has?(:Errors)
         @errors = elements(:Errors).collect do |error|
           Error.new(error)
         end
@@ -42,7 +40,7 @@ module Remit
         @status = text_value(element(:Status))
         @errors = elements('errors/errors').collect do |error|
           ServiceError.new(error)
-        end if not successful?
+        end unless successful?
       end
     end
 
@@ -50,26 +48,26 @@ module Remit
       @status == ResponseStatus::SUCCESS
     end
 
-    private
-
-    def node_name(name)
-      name.to_s.gsub(/(^|_)(.)/) { $2.upcase }
+    def node_name(name, namespace=nil)
+      super(name.to_s.split('/').collect{ |tag|
+        tag.gsub(/(^|_)(.)/) { $2.upcase }
+      }.join('/'), namespace)
     end
   end
 
   class SignedQuery < Relax::Query
-    def initialize(uri, secret_key, query = {})
+    def initialize(uri, secret_key, query={})
       super(query)
       @uri = URI.parse(uri.to_s)
       @secret_key = secret_key
     end
 
     def sign
-      delete_if { |key, value| key == :awsSignature }
+      delete(:awsSignature)
       store(:awsSignature, Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, @secret_key, "#{@uri.path}?#{to_s(false)}".gsub('%20', '+'))).strip)
     end
 
-    def to_s(signed = true)
+    def to_s(signed=true)
       sign if signed
       super()
     end
@@ -77,10 +75,12 @@ module Remit
     class << self
       def parse(uri, secret_key, query_string)
         query = self.new(uri, secret_key)
+
         query_string.split('&').each do |parameter|
-          key, value = parameter.split('=')
+          key, value = parameter.split('=', 2)
           query[key] = unescape_value(value)
         end
+
         query
       end
     end

data/lib/remit/data_types.rb

@@ -9,6 +9,16 @@ module Remit
     parameter :amount, :type => :float
   end
 
+  class TemporaryDeclinePolicy < BaseResponse
+    parameter :temporary_decline_policy_type
+    parameter :implicit_retry_timeout_in_mins
+  end
+
+  class DescriptorPolicy < BaseResponse
+    parameter :soft_descriptor_type
+    parameter :CS_number_of
+  end
+
   class ChargeFeeTo
     CALLER = 'Caller'
     RECIPIENT = 'Recipient'
@@ -80,6 +90,21 @@ module Remit
     parameter :status
     parameter :status_detail
     parameter :new_sender_token_usage, :type => TokenUsageLimit
+
+    %w(reserved success failure initiated reinitiated temporary_decline).each do |status_name|
+      define_method("#{status_name}?") do
+        self.status == Remit::TransactionStatus.const_get(status_name.sub('_', '').upcase)
+      end
+    end
+  end
+
+  class TransactionStatus
+    RESERVED          = 'Reserved'
+    SUCCESS           = 'Success'
+    FAILURE           = 'Failure'
+    INITIATED         = 'Initiated'
+    REINITIATED       = 'Reinitiated'
+    TEMPORARYDECLINE  = 'TemporaryDecline'
   end
 
   class TokenType
@@ -88,7 +113,7 @@ module Remit
     RECURRING = 'Recurring'
     UNRESTRICTED = 'Unrestricted'
   end
-  
+
   class PipelineName
     SINGLE_USE = 'SingleUse'
     MULTI_USE = 'MultiUse'
@@ -97,11 +122,43 @@ module Remit
     SETUP_PREPAID = 'SetupPrepaid'
     SETUP_POSTPAID = 'SetupPostpaid'
   end
-  
+
+  class PipelineStatusCode
+    CALLER_EXCEPTION  = 'CE'  # problem with your code
+    SYSTEM_ERROR      = 'SE'  # system error, try again
+    SUCCESS_ABT       = 'SA'  # successful payment with Amazon balance
+    SUCCESS_ACH       = 'SB'  # successful payment with bank transfer
+    SUCCESS_CC        = 'SC'  # successful payment with credit card
+    ABORTED           = 'A'   # user aborted payment
+    PAYMENT_METHOD_MISMATCH     = 'PE'  # user does not have payment method requested
+    PAYMENT_METHOD_UNSUPPORTED  = 'NP'  # account doesn't support requested payment method
+    INVALID_CALLER    = 'NM'  # you are not a valid 3rd party caller to the transaction
+    SUCCESS_RECIPIENT_TOKEN_INSTALLED = 'SR'
+  end
+
   module RequestTypes
     class Amount < Remit::Request
       parameter :amount
       parameter :currency_code
     end
+
+    class TemporaryDeclinePolicy < Remit::Request
+      parameter :temporary_decline_policy_type
+      parameter :implicit_retry_timeout_in_mins
+    end
+
+    class DescriptorPolicy < Remit::Request
+      parameter :soft_descriptor_type
+      parameter :CS_number_of
+    end
+  end
+
+  class Operation
+    PAY             = "Pay"
+    REFUND          = "Refund"
+    SETTLE          = "Settle"
+    SETTLE_DEBT     = "SettleDebt"
+    WRITE_OFF_DEBT  = "WriteOffDebt"
+    FUND_PREPAID    = "FundPrepaid"
   end
 end

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

@@ -33,12 +33,11 @@ module Remit
       attr_reader :api
       
       parameter :pipeline_name
-      parameter :return_URL
+      parameter :return_url
       parameter :caller_key
 
-      def initialize(api, pipeline, options)
+      def initialize(api, options)
         @api = api
-        @pipeline = pipeline
         
         options.each do |k,v|
           self.send("#{k}=", v)
@@ -46,7 +45,7 @@ module Remit
       end
 
       def url
-        uri = URI.parse(@pipeline)
+        uri = URI.parse(@api.pipeline_url)
         
         query = {}
         self.class.parameters.each do |p|
@@ -61,7 +60,7 @@ module Remit
         # Remove any unused optional parameters
         query.reject! { |key, value| value.nil? }
 
-        uri.query = SignedQuery.new(@api.pipeline, @api.secret_key, query).to_s
+        uri.query = SignedQuery.new(@api.pipeline_url, @api.secret_key, query).to_s
         uri.to_s
       end
     end
@@ -72,6 +71,48 @@ module Remit
       parameter :payment_method
       parameter :transaction_amount
       parameter :recipient_token
+      
+      def pipeline_name
+        Remit::PipelineName::SINGLE_USE
+      end
+    end
+    
+    class MultiUsePipeline < Pipeline
+      parameter :caller_reference
+      parameter :payment_reason
+      parameter :recipient_token_list
+      parameter :amount_type
+      parameter :transaction_amount
+      parameter :validity_start
+      parameter :validity_expiry
+      parameter :payment_method
+      parameter :global_amount_limit
+      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
+      parameter :is_recipient_cobranding
+      
+      def pipeline_name
+        Remit::PipelineName::MULTI_USE
+      end
+    end
+    
+    class RecipientPipeline < Pipeline
+      parameter :caller_reference
+      parameter :validity_start # Time or seconds from Epoch
+      parameter :validity_expiry # Time or seconds from Epoch
+      parameter :payment_method
+      parameter :recipient_pays_fee
+      parameter :caller_reference_refund
+      parameter :max_variable_fee
+      parameter :max_fixed_fee
+      
+      def pipeline_name
+        Remit::PipelineName::RECIPIENT
+      end
     end
 
     class RecurringUsePipeline < Pipeline
@@ -82,7 +123,11 @@ module Remit
       parameter :validity_start # Time or seconds from Epoch
       parameter :validity_expiry # Time or seconds from Epoch
       parameter :payment_method
-      parameter :recurring_period
+      parameter :recurring_period  
+      
+      def pipeline_name
+        Remit::PipelineName::RECURRING
+      end 
     end
     
     class PostpaidPipeline < Pipeline
@@ -100,11 +145,23 @@ module Remit
       parameter :usage_limit_type2
       parameter :usage_limit_period2
       parameter :usage_limit_value2
+      
+      def pipeline_name
+        Remit::PipelineName::SETUP_POSTPAID
+      end
     end
     
     def get_single_use_pipeline(options)
       self.get_pipeline(SingleUsePipeline, options)
     end
+
+    def get_multi_use_pipeline(options)
+      self.get_pipeline(MultiUsePipeline, options)
+    end
+
+    def get_recipient_pipeline(options)
+      self.get_pipeline(RecipientPipeline, options)
+    end
     
     def get_recurring_use_pipeline(options)
       self.get_pipeline(RecurringUsePipeline, options)
@@ -115,7 +172,7 @@ module Remit
     end
     
     def get_pipeline(pipeline_subclass, options)
-      pipeline = pipeline_subclass.new(self, @pipeline, {
+      pipeline = pipeline_subclass.new(self, {
         :caller_key => @access_key
       }.merge(options))
     end

data/lib/remit/get_results.rb

@@ -11,12 +11,13 @@ module Remit
     class Response < Remit::Response
       class TransactionResults < Remit::BaseResponse
         parameter :transaction_id
-        parameter :operation_type
+        parameter :operation_type, :element => :operation
         parameter :caller_reference
-        parameter :transaction_status
+        parameter :transaction_status, :element => :status
       end
 
-      parameter :transaction_results, :type => TransactionResults
+      parameter :transaction_results, :collection => TransactionResults
+      parameter :number_pending, :type => :integer
     end
 
     def get_results(request = Request.new)

data/lib/remit/ipn_request.rb

@@ -0,0 +1,56 @@
+require 'base64'
+require 'openssl/digest'
+
+module Remit
+  
+  ##
+  # Encapsulates the logic for IPN request validation and attribute retrieval.
+  # 
+  class IpnRequest
+    
+    # Signature key name used by AmazonFPS IPNs
+    SIGNATURE_KEY = 'signature'
+    
+    ##
+    # +params+ should be your controllers request parameters.
+    # 
+    def initialize(params, secret_key)
+      raise ArgumentError, "Expected the request params hash, received: #{params.inspect}" unless params.kind_of?(Hash)
+      @params             = strip_keys_from(params, 'action', 'controller')
+      @supplied_signature = @params.delete(SIGNATURE_KEY)
+      @secret_key         = secret_key
+    end
+    
+    def valid?
+      return false unless @supplied_signature
+      generate_signature_for(@params) == @supplied_signature
+    end
+    
+    def method_missing(method, *args) #:nodoc:
+      if @params.has_key?(method.to_s)
+        @params[method.to_s]
+      else
+        super(method, *args)
+      end
+    end
+    
+    
+    private
+    
+    
+    def generate_signature_for(params)
+      query   = params.sort_by { |k,v| k.downcase }
+      digest  = OpenSSL::Digest::Digest.new('sha1')
+      hmac    = OpenSSL::HMAC.digest(digest, @secret_key, query.to_s)
+      encoded = Base64.encode64(hmac).chomp
+    end
+    
+    def strip_keys_from(params, *ignore_keys)
+      parsed = params.dup
+      ignore_keys.each { |key| parsed.delete(key) }
+      parsed
+    end
+    
+  end
+  
+end

data/lib/remit/pay.rb

@@ -8,6 +8,9 @@ module Remit
       parameter :caller_reference
       parameter :caller_token_id
       parameter :charge_fee_to
+      parameter :descriptor_policy, :type => Remit::RequestTypes::DescriptorPolicy
+      parameter :marketplace_fixed_fee, :type => Remit::RequestTypes::Amount
+      parameter :marketplace_variable_fee
       parameter :meta_data
       parameter :recipient_description
       parameter :recipient_reference
@@ -15,16 +18,14 @@ module Remit
       parameter :sender_description
       parameter :sender_reference
       parameter :sender_token_id
+      parameter :temporary_decline_policy, :type => Remit::RequestTypes::TemporaryDeclinePolicy
       parameter :transaction_amount, :type => Remit::RequestTypes::Amount
       parameter :transaction_date
     end
 
     class Response < Remit::Response
-      # FIXME: Due to an issue with Hpricot, Relax-0.0.4, and namespaces, the
-      # transaction_response parameter is not parsed correctly and will always
-      # be nil (http://groups.google.com/group/remit/t/1e0af072200d1bb3).
-      # The suggested course of action is to operate on the raw XML.
-      parameter :transaction_response, :type => TransactionResponse
+      parser :rexml
+      parameter :transaction_response, :namespace => 'ns3', :type => TransactionResponse
     end
 
     def pay(request = Request.new)

data/lib/remit/pipeline_response.rb

@@ -0,0 +1,62 @@
+module Remit
+  
+  class PipelineResponse
+    
+    def initialize(uri, secret_key)
+      @uri        = URI.parse(uri)
+      @secret_key = secret_key
+    end
+    
+    ##
+    # Returns +true+ if the response is correctly signed (awsSignature).
+    # 
+    #--
+    # The unescape_value method is used here because the awsSignature value
+    # pulled from the request is filtered through the same method.
+    #++
+    # 
+    def valid?
+      return false unless given_signature
+      Relax::Query.unescape_value(correct_signature) == given_signature
+    end
+    
+    ##
+    # Returns +true+ if the response returns a successful state.
+    # 
+    def successful?
+      [
+        Remit::PipelineStatusCode::SUCCESS_ABT,
+        Remit::PipelineStatusCode::SUCCESS_ACH,
+        Remit::PipelineStatusCode::SUCCESS_CC,
+        Remit::PipelineStatusCode::SUCCESS_RECIPIENT_TOKEN_INSTALLED
+      ].include?(request_query[:status])
+    end
+    
+    
+    def method_missing(method, *args) #:nodoc:
+      if request_query.has_key?(method.to_sym)
+        request_query[method.to_sym]
+      else
+        super
+      end
+    end
+    
+    
+    private
+    
+    
+    def request_query(reload = false)
+      @query ||= Remit::SignedQuery.parse(@uri, @secret_key, @uri.query || '')
+    end
+    
+    def given_signature
+      request_query[:awsSignature]
+    end
+    
+    def correct_signature
+      Remit::SignedQuery.new(@uri.path, @secret_key, request_query).sign
+    end
+    
+  end
+  
+end

data/lib/remit.rb

@@ -8,6 +8,8 @@ require 'base64'
 require 'erb'
 
 require 'rubygems'
+
+gem 'relax', '0.0.6'
 require 'relax'
 
 require 'remit/common'
@@ -15,6 +17,7 @@ require 'remit/data_types'
 
 require 'remit/cancel_token'
 require 'remit/discard_results'
+require 'remit/error_codes'
 require 'remit/fund_prepaid'
 require 'remit/get_account_activity'
 require 'remit/get_account_balance'
@@ -32,7 +35,9 @@ require 'remit/get_token_by_caller'
 require 'remit/get_total_prepaid_liability'
 require 'remit/get_transaction'
 require 'remit/install_payment_instruction'
+require 'remit/ipn_request'
 require 'remit/pay'
+require 'remit/pipeline_response'
 require 'remit/refund'
 require 'remit/reserve'
 require 'remit/retry_transaction'
@@ -73,29 +78,29 @@ module Remit
     include UnsubscribeForCallerNotification
     include WriteOffDebt
 
-    API_ENDPOINT = 'https://fps.amazonaws.com/'
-    API_SANDBOX = 'https://fps.sandbox.amazonaws.com/'
-    PIPELINE_ENDPOINT = 'https://authorize.payments.amazon.com/cobranded-ui/actions/start'
-    PIPELINE_SANDBOX = 'https://authorize.payments-sandbox.amazon.com/cobranded-ui/actions/start'
-    API_VERSION = Date.new(2007, 1, 8).to_s
-    SIGNATURE_VERSION = 1
+    API_ENDPOINT = 'https://fps.amazonaws.com/'.freeze
+    API_SANDBOX_ENDPOINT = 'https://fps.sandbox.amazonaws.com/'.freeze
+    PIPELINE_URL = 'https://authorize.payments.amazon.com/cobranded-ui/actions/start'.freeze
+    PIPELINE_SANDBOX_URL = 'https://authorize.payments-sandbox.amazon.com/cobranded-ui/actions/start'.freeze
+    API_VERSION = Date.new(2007, 1, 8).to_s.freeze
+    SIGNATURE_VERSION = 1.freeze
 
-    attr_reader :pipeline
     attr_reader :access_key
     attr_reader :secret_key
+    attr_reader :pipeline_url
 
-    def initialize(access_key, secret_key, sandbox = false)
-      super((not sandbox) ? API_ENDPOINT : API_SANDBOX)
-      @pipeline = ((not sandbox) ? PIPELINE_ENDPOINT : PIPELINE_SANDBOX)
+    def initialize(access_key, secret_key, sandbox=false)
       @access_key = access_key
       @secret_key = secret_key
-    end
+      @pipeline_url = sandbox ? PIPELINE_SANDBOX_URL : PIPELINE_URL
 
-    private
+      super(sandbox ? API_SANDBOX_ENDPOINT : API_ENDPOINT)
+    end
 
-    def new_query(query = {})
+    def new_query(query={})
       SignedQuery.new(@endpoint, @secret_key, query)
     end
+    private :new_query
 
     def default_query
       new_query({
@@ -105,19 +110,24 @@ module Remit
         :Timestamp => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
       })
     end
+    private :default_query
 
     def query(request)
       query = super
       query[:Signature] = sign(query)
       query
     end
+    private :query
 
     def sign(values)
       keys = values.keys.sort { |a, b| a.to_s.downcase <=> b.to_s.downcase }
+
       signature = keys.inject('') do |signature, key|
         signature += key.to_s + values[key].to_s
       end
+
       Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, @secret_key, signature)).strip
     end
+    private :sign
   end
 end

data/spec/{get_account_activity_spec.rb → integrations/get_account_activity_spec.rb}

@@ -1,12 +1,12 @@
-require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/integrations_helper'
 
 describe 'a GetAccountActivity call' do
-  it_should_behave_like 'a successful request'
+  it_should_behave_like 'a successful response'
 
   before(:all) do
-    request = Remit::API::GetAccountActivityRequest.new
+    request = Remit::GetAccountActivity::Request.new
     request.start_date = Date.today - 7
-    @response = @remit.get_account_activity(request)
+    @response = remit.get_account_activity(request)
   end
 
   it 'should have a collection of transactions' do

data/spec/{get_tokens_spec.rb → integrations/get_tokens_spec.rb}

@@ -1,10 +1,10 @@
-require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/integrations_helper'
 
 describe 'a GetTokens call' do
-  it_should_behave_like 'a successful request'
+  it_should_behave_like 'a successful response'
 
   before(:all) do
-    @response = @remit.get_tokens
+    @response = remit.get_tokens
   end
 
   it 'should have a collection of tokens' do

data/spec/integrations/integrations_helper.rb

@@ -0,0 +1,8 @@
+ACCESS_KEY = ENV['AWS_ACCESS_KEY'] || ENV['AMAZON_ACCESS_KEY_ID']
+SECRET_KEY = ENV['AWS_SECRET_KEY'] || ENV['AMAZON_SECRET_ACCESS_KEY']
+
+unless ACCESS_KEY and SECRET_KEY
+  raise RuntimeError, "You must set your AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables to run integration tests"
+end
+
+require File.dirname(__FILE__) + '/../spec_helper'

data/spec/spec_helper.rb

@@ -1,19 +1,15 @@
+require 'rubygems'
 require 'spec'
 
 require File.dirname(__FILE__) + '/../lib/remit'
 
-fail unless ENV.include?('AWS_ACCESS_KEY') and ENV.include?('AWS_SECRET_KEY')
-
-ACCESS_KEY = ENV['AWS_ACCESS_KEY'] unless defined?(ACCESS_KEY)
-SECRET_KEY = ENV['AWS_SECRET_KEY'] unless defined?(SECRET_KEY)
-
-describe 'a successful request', :shared => true do
-  before(:all) do
-    @remit = Remit::API.new(ACCESS_KEY, SECRET_KEY, true)
-  end
+def remit
+  @remit ||= Remit::API.new(ACCESS_KEY, SECRET_KEY, true)
+end
 
+describe 'a successful response', :shared => true do
   it 'should return success' do
-    @response.status.should eql('Success')
+    @response.status.should == 'Success'
   end
 
   it 'should not have any errors' do
@@ -24,3 +20,17 @@ describe 'a successful request', :shared => true do
     @response.request_id.should_not be_nil
   end
 end
+
+describe 'a failed response', :shared => true do
+  it "is not successful" do
+    @response.should_not be_successful
+  end
+
+  it "has a request id" do
+    @response.request_id.should_not be_empty
+  end
+
+  it "has errors" do
+    @response.errors.should_not be_empty
+  end
+end

data/spec/{get_pipeline_spec.rb → units/get_pipeline_spec.rb}

@@ -1,17 +1,15 @@
-require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/units_helper'
 
 describe 'A pipeline', :shared => true do
   before do
-    @remit = Remit::API.new(ACCESS_KEY, SECRET_KEY, true)
-
     @pipeline_options = {
-      :return_URL => 'http://example.com/'
+      :return_url => 'http://example.com/'
     }
   end
 
   it 'should sign its URL' do
     uri = URI.parse(@pipeline.url)
-    pipeline = Remit::SignedQuery.parse(uri, @remit.secret_key, uri.query)
+    pipeline = Remit::SignedQuery.parse(uri, remit.secret_key, uri.query)
     query = Relax::Query.parse(uri)
 
     pipeline[:awsSignature].should == query[:awsSignature]
@@ -25,19 +23,74 @@ describe 'A single-use pipeline' do
     @pipeline_options.merge!({
       :transaction_amount => 10,
       :caller_reference => 'N2PCBEIA5864E27EL7C86PJL1FGUGPBL61QTJJM5GQK265SPEN8ZKIJPMQARDVJK',
-      :recipient_token => 'N5PCME5A5Q6FE2QEB7CD64JLGFTUGXBE61HTCJMGGAK2R5IPEQ8EKIVP3QAVD7JP',
-      :pipeline_name => Remit::PipelineName::SINGLE_USE
+      :recipient_token => 'N5PCME5A5Q6FE2QEB7CD64JLGFTUGXBE61HTCJMGGAK2R5IPEQ8EKIVP3QAVD7JP'
+    })
+
+    @pipeline = remit.get_single_use_pipeline(@pipeline_options)
+  end
+
+  it 'should ignore unused parameters' do
+    uri = URI.parse(@pipeline.url)
+    query = Relax::Query.parse(uri)
+
+    query[:paymentReason].should be_nil
+  end
+
+  it 'should have the right name' do
+    @pipeline.pipeline_name.should == Remit::PipelineName::SINGLE_USE
+  end
+end
+
+describe 'A multi-use pipeline' do
+  it_should_behave_like 'A pipeline'
+
+  before do
+    @pipeline_options.merge!({
+      :transaction_amount => 10,
+      :caller_reference => 'N2PCBEIA5864E27EL7C86PJL1FGUGPBL61QTJJM5GQK265SPEN8ZKIJPMQARDVJK',
+      :recipient_token_list => 'N5PCME5A5Q6FE2QEB7CD64JLGFTUGXBE61HTCJMGGAK2R5IPEQ8EKIVP3QAVD7JP'
     })
 
-    @pipeline = @remit.get_single_use_pipeline(@pipeline_options)
+    @pipeline = remit.get_multi_use_pipeline(@pipeline_options)
   end
 
   it 'should ignore unused parameters' do
     uri = URI.parse(@pipeline.url)
     query = Relax::Query.parse(uri)
-    
+
     query[:paymentReason].should be_nil
   end
+
+  it 'should have the right name' do
+    @pipeline.pipeline_name.should == Remit::PipelineName::MULTI_USE
+  end
+end
+
+describe 'A recipient pipeline' do
+  it_should_behave_like 'A pipeline'
+
+  before do
+    @validity_start   = Time.now + (3600 * 24) # 1 day from now
+    @validity_expiry  = Time.now + (2600 * 24 * 180) # ~6 months from now
+
+    @pipeline_options.merge!({
+      :validity_start => @validity_start,
+      :validity_expiry  => @validity_expiry,
+      :caller_reference => 'N2PCBEIA5864E27EL7C86PJL1FGUGPBL61QTJJM5GQK265SPEN8ZKIJPMQARDVJK',
+      :max_variable_fee => '0.25',
+      :recipient_pays_fee => true
+    })
+
+    @pipeline = remit.get_recipient_pipeline(@pipeline_options)
+  end
+
+  it 'should have the recipient pay marketplace fees' do
+    @pipeline.url.should match(/recipientPaysFee=true/)
+  end
+
+  it 'should have the right name' do
+    @pipeline.pipeline_name.should == Remit::PipelineName::RECIPIENT
+  end
 end
 
 describe 'A recurring-use pipeline' do
@@ -47,9 +100,8 @@ describe 'A recurring-use pipeline' do
     @validity_start = Time.now + (3600 * 24)  # 1 day from now
     @validity_expiry = Time.now + (3600 * 24 * 180) # ~6 months from now
     @recurring_period = '1 Month'
-    
+
     @pipeline_options.merge!({
-      :pipeline_name => Remit::PipelineName::RECURRING,
       :validity_start => @validity_start,
       :validity_expiry => @validity_expiry,
       :recurring_period => @recurring_period,
@@ -57,50 +109,57 @@ describe 'A recurring-use pipeline' do
       :caller_reference => 'N2PCBEIA5864E27EL7C86PJL1FGUGPBL61QTJJM5GQK265SPEN8ZKIJPMQARDVJK',
       :recipient_token => 'N5PCME5A5Q6FE2QEB7CD64JLGFTUGXBE61HTCJMGGAK2R5IPEQ8EKIVP3QAVD7JP'
     })
-    
-    @pipeline = @remit.get_recurring_use_pipeline(@pipeline_options)
+
+    @pipeline = remit.get_recurring_use_pipeline(@pipeline_options)
   end
 
   it 'should convert times to seconds from epoch' do
     uri = URI.parse(@pipeline.url)
     query = Relax::Query.parse(uri)
-    
+
     @validity_start.to_i.to_s.should == query[:validityStart]
     @validity_expiry.to_i.to_s.should == query[:validityExpiry]
   end
-  
+
   it 'should allow time in seconds' do
     options = @pipeline_options.merge({
       :validity_start => @validity_start.to_i,
       :validity_expiry => @validity_expiry.to_i
     })
-    @pipeline = @remit.get_recurring_use_pipeline(options)
-    
+    @pipeline = remit.get_recurring_use_pipeline(options)
+
     uri = URI.parse(@pipeline.url)
     query = Relax::Query.parse(uri)
-    
+
     @validity_start.to_i.to_s.should == query[:validityStart]
     @validity_expiry.to_i.to_s.should == query[:validityExpiry]
   end
+
+  it 'should have the right name' do
+    @pipeline.pipeline_name.should == Remit::PipelineName::RECURRING
+  end
 end
 
 describe 'A postpaid pipeline' do
   it_should_behave_like 'A pipeline'
-  
+
   before do
     @credit_limit = 100
     @global_amount_limit = 100
-    
+
     @pipeline_options.merge!({
-      :pipeline_name => Remit::PipelineName::SETUP_POSTPAID,
       :credit_limit => @credit_limit,
       :global_amount_limit => @global_amount_limit
     })
-    
-    @pipeline = @remit.get_postpaid_pipeline(@pipeline_options)
+
+    @pipeline = remit.get_postpaid_pipeline(@pipeline_options)
   end
-  
+
   it 'should create a PostpaidPipeline' do
     @pipeline.class.should == Remit::GetPipeline::PostpaidPipeline
   end
+
+  it 'should have the right name' do
+    @pipeline.pipeline_name.should == Remit::PipelineName::SETUP_POSTPAID
+  end
 end

data/spec/units/get_results_spec.rb

@@ -0,0 +1,49 @@
+require File.dirname(__FILE__) + '/units_helper'
+
+describe "the GetResults API" do
+  describe "a successful response" do
+    it_should_behave_like 'a successful response'
+
+    before do
+      doc = <<-XML
+        <?xml version=\"1.0\"?>
+        <ns3:GetResultsResponse xmlns:ns3=\"http://fps.amazonaws.com/doc/2007-01-08/\">
+          <TransactionResults>
+            <TransactionId>abc123</TransactionId>
+            <Operation>Pay</Operation>
+            <CallerReference>1827</CallerReference>
+            <Status>Success</Status>
+          </TransactionResults>
+          <NumberPending>1</NumberPending>
+          <Status>Success</Status>
+          <RequestId>f89727ba-9ff6-4ca8-87a3-0fd6c9de6b95:0</RequestId>
+        </ns3:GetResultsResponse>
+      XML
+
+      @response = Remit::GetResults::Response.new(doc)
+    end
+
+    it "has one result" do
+      @response.number_pending.should == 1
+      @response.transaction_results.size == "1"
+    end
+
+    describe "the result" do
+      before do
+        @result = @response.transaction_results.first
+      end
+
+      it "references a previous transaction" do
+        @result.transaction_id.should == "abc123"
+      end
+
+      it "references a pay transaction" do
+        @result.operation_type.should == 'Pay'
+      end
+
+      it "reports the transaction's new status" do
+        @result.transaction_status.should == 'Success'
+      end
+    end
+  end
+end

data/spec/units/ipn_request_spec.rb

@@ -0,0 +1,32 @@
+require File.dirname(__FILE__) + '/units_helper'
+
+describe 'an IPN request' do
+  before(:each) do
+    @request_params = {
+      "action"            => "notice",
+      "buyerName"         => "Fps Buyer",
+      "callerReference"   => "4-8-1-3.5",
+      "controller"        => "amazon_fps/ipn",
+      "operation"         => "PAY",
+      "paymentMethod"     => "CC",
+      "recipientEmail"    => "recipient@email.url",
+      "recipientName"     => "Fps Business",
+      "signature"         => "DA7ZbuQaBDt2/+Mty9XweJyqI1E=",
+      "status"            => "SUCCESS",
+      "transactionAmount" => "USD 3.50",
+      "transactionDate"   => "1224687134",
+      "transactionId"     => "13KIGL9RC25853BGPPOS2VSKBKF2JERR3HO"
+    }
+    @request = Remit::IpnRequest.new(@request_params, 'THISISMYTESTKEY')
+  end
+
+  it 'should be a valid request' do
+    @request.should be_valid
+  end
+
+  it 'should pass through access to given parameters' do
+    @request.status.should == 'SUCCESS'
+    @request.operation.should == 'PAY'
+    @request.transactionId.should == '13KIGL9RC25853BGPPOS2VSKBKF2JERR3HO'
+  end
+end

data/spec/units/pay_spec.rb

@@ -0,0 +1,70 @@
+require File.dirname(__FILE__) + '/units_helper'
+
+describe "the Pay API" do
+  describe "a successful response" do
+    it_should_behave_like 'a successful response'
+
+    before do
+      doc = <<-XML
+        <ns3:PayResponse xmlns:ns3="http://fps.amazonaws.com/doc/2007-01-08/">
+          <ns3:TransactionResponse>
+            <TransactionId>abc123</TransactionId>
+            <Status>Initiated</Status>
+          </ns3:TransactionResponse>
+          <Status>Success</Status>
+          <RequestId>foo</RequestId>
+        </ns3:PayResponse>
+      XML
+
+      @response = Remit::Pay::Response.new(doc)
+    end
+
+    it "has a transaction response" do
+      @response.transaction_response.should_not be_nil
+    end
+
+    it "has a transaction id" do
+      @response.transaction_response.transaction_id.should == 'abc123'
+    end
+
+    it "has a transaction status" do
+      @response.transaction_response.status.should == 'Initiated'
+    end
+
+    it "has status shortcuts" do
+      @response.transaction_response.should be_initiated
+    end
+  end
+
+  describe "for a failed request" do
+    it_should_behave_like 'a failed response'
+
+    before do
+      doc = <<-XML
+        <ns3:PayResponse xmlns:ns3=\"http://fps.amazonaws.com/doc/2007-01-08/\">
+          <Status>Failure</Status>
+          <Errors>
+            <Errors>
+              <ErrorType>Business</ErrorType>
+              <IsRetriable>false</IsRetriable>
+              <ErrorCode>InvalidParams</ErrorCode>
+              <ReasonText>callerTokenId can not be empty</ReasonText>
+            </Errors>
+          </Errors>
+          <RequestId>7966a2d9-5ce9-4902-aefc-b01d254c931a:0</RequestId>
+        </ns3:PayResponse>
+      XML
+
+      @response = Remit::Pay::Response.new(doc)
+    end
+
+    it "has error details" do
+      error = @response.errors.first
+      error.should be_kind_of(Remit::ServiceError)
+      error.error_type.should == 'Business'
+      error.is_retriable.should == 'false'
+      error.error_code.should == 'InvalidParams'
+      error.reason_text.should == 'callerTokenId can not be empty'
+    end
+  end
+end

data/spec/units/units_helper.rb

@@ -0,0 +1,4 @@
+ACCESS_KEY = 'foo'
+SECRET_KEY = 'bar'
+
+require File.dirname(__FILE__) + '/../spec_helper'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: remit
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Tyler Hunt
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-28 00:00:00 -05:00
+date: 2009-02-03 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -29,7 +29,7 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.markdown
 - LICENSE
 files: 
 - lib/remit
@@ -37,6 +37,7 @@ files:
 - lib/remit/common.rb
 - lib/remit/data_types.rb
 - lib/remit/discard_results.rb
+- lib/remit/error_codes.rb
 - lib/remit/fund_prepaid.rb
 - lib/remit/get_account_activity.rb
 - lib/remit/get_account_balance.rb
@@ -54,7 +55,9 @@ files:
 - lib/remit/get_total_prepaid_liability.rb
 - lib/remit/get_transaction.rb
 - lib/remit/install_payment_instruction.rb
+- lib/remit/ipn_request.rb
 - lib/remit/pay.rb
+- lib/remit/pipeline_response.rb
 - lib/remit/refund.rb
 - lib/remit/reserve.rb
 - lib/remit/retry_transaction.rb
@@ -64,7 +67,7 @@ files:
 - lib/remit/unsubscribe_for_caller_notification.rb
 - lib/remit/write_off_debt.rb
 - lib/remit.rb
-- README
+- README.markdown
 - LICENSE
 has_rdoc: true
 homepage: http://tylerhunt.com/
@@ -93,7 +96,12 @@ signing_key:
 specification_version: 2
 summary: An API for using the Amazon Flexible Payment Service (FPS).
 test_files: 
-- spec/get_account_activity_spec.rb
-- spec/get_pipeline_spec.rb
-- spec/get_tokens_spec.rb
+- spec/integrations/get_account_activity_spec.rb
+- spec/integrations/get_tokens_spec.rb
+- spec/units/get_pipeline_spec.rb
+- spec/units/get_results_spec.rb
+- spec/units/ipn_request_spec.rb
+- spec/units/pay_spec.rb
+- spec/integrations/integrations_helper.rb
 - spec/spec_helper.rb
+- spec/units/units_helper.rb

data/README

@@ -1,47 +0,0 @@
-Remit
-=====
-
-This API provides access to the Amazon Flexible Payment Service (FPS). After
-trying to get the SOAP version of the API written, I began working on this REST
-version to provide a cohesive means of access to all of the functionality of
-the FPS without having to get dirty dealing with SOAP requests.
-
-I hope you enjoy using it as much as I've enjoyed writing it. I'm interested to
-hear what sort of uses you find for it. If you find any bugs, let me know (or
-better yet, submit a patch).
-
-
-Users
------
-
-The following sites are using Remit:
-
-  * http://www.storenvy.com/
-  * http://www.obsidianportal.com/
-
-
-Sandbox
--------
-Amazon provides a testing environment for the FPS called a sandbox. You may
-(and should) use the sandbox while testing your application. It can be enabled
-by passing a value of true to the last argument of the API constructor.
-
-
-Example
--------
-The following example shows how to load up the API, initialize the service, and
-make a simple call to get the tokens stored on the account:
-
-  require 'remit'
-
-  ACCESS_KEY = '<your AWS access key>'
-  SECRET_KEY = '<your AWS secret key>'
-
-  # connect using the API's sandbox mode
-  remit = Remit::API.new(ACCESS_KEY, SECRET_KEY, true)
-
-  response = remit.get_tokens
-  puts response.tokens.first.token_id
-
-
-Copyright (c) 2007-2008 Tyler Hunt, released under the MIT license