remit 0.0.6 → 2.0.1

data/README.markdown

@@ -38,13 +38,18 @@ make a simple call to get the tokens stored on the account:
     puts response.tokens.first.token_id
 
 
+VerifySignature API
+-------------------
+See spec/integrations/verify_signature_spec.rb for examples on correct and incorrect usage!
+
+
 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:
+Remit gem in your Gemfile:
 
-    config.gem 'remit', :version => '~> 0.0.1'
+    gem 'remit', :git => "git://github.com/nyc-ruby-meetup/remit.git"
 
 Then you should create an initializer to configure your Amazon keys. Create the
 file config/initializers/remit.rb with the following contents:
@@ -84,8 +89,34 @@ Sites Using Remit
 
 The following production sites are currently using Remit:
 
-  * http://www.storenvy.com/
-  * http://www.obsidianportal.com/
-
+ * [Storyenvy](http://www.storenvy.com/)
+ * [ObsidianPortal](http://www.obsidianportal.com/)
+
+
+Amazon API Compliance 
+---------------------
+These are the changes summarized by Amazon from the previous API, and the level of compliance in this branch:
+
+1. You don't have to use InstallPaymentInstruction API to create Caller and Recipient tokens for your account. A Recipient token is now required only in Marketplace applications. We have completely removed the Caller token.
+  Compliance: Caller token references removed.
+2. We removed parameters that are not being used by you today. For example, we removed metadata and recipient description, but we retained sender description and caller description.
+  Compliance: DONE! recipient_description and metadata have been removed from the code.
+3. We simplified the transaction response object.
+  Compliance: The former Remit::TransactionResponse object has been accordingly simplified.
+4. We simplified the GetTransaction response by removing unnecessary parameters.
+  Compliance: ?
+5. By default, implicit retry and cancel will be the method used to handle temporary declines rather than the current explicit retry process.
+  Compliance: Removed deprecated statuses
+6. GetResults, DiscardResults are replaced with GetTransactionStatus API.
+  Compliance: GetResults and Discard Results are gone.  GetTransactionStatus takes their place.
+7. Temporary decline status is not exposed to customers as we provide a simpler way to handle this status.
+  Compliance: Temporary decline status can no longer be tested for, as it will never be a status.
+8. Web Service notification is removed and replaced with simplified IPN (Instant Payment Notification) mechanism.
+
+Running Specification Suite
+---------------------------
+1. Copy test.sh.example to test.sh
+2. Edit test.sh to have valid Amazon developer account access and secret keys
+3. Run ./test.sh from the command line.
 
 Copyright (c) 2007-2009 Tyler Hunt, released under the MIT license

data/lib/remit.rb

@@ -6,22 +6,27 @@ require 'uri'
 require 'date'
 require 'base64'
 require 'erb'
+require 'cgi'
 
 require 'rubygems'
 
 gem 'relax', '0.0.7'
 require 'relax'
 
-require 'remit/common'
+
 require 'remit/data_types'
+require 'remit/common'
 require 'remit/error_codes'
+require 'remit/signature_utils_for_outbound'
+require 'remit/verify_signature'
+require 'remit/inbound_request'
 require 'remit/ipn_request'
 require 'remit/get_pipeline'
 require 'remit/pipeline_response'
 
 require 'remit/operations/cancel_subscription_and_refund'
 require 'remit/operations/cancel_token'
-require 'remit/operations/discard_results'
+require 'remit/operations/cancel'
 require 'remit/operations/fund_prepaid'
 require 'remit/operations/get_account_activity'
 require 'remit/operations/get_account_balance'
@@ -31,17 +36,17 @@ require 'remit/operations/get_debt_balance'
 require 'remit/operations/get_outstanding_debt_balance'
 require 'remit/operations/get_payment_instruction'
 require 'remit/operations/get_prepaid_balance'
-require 'remit/operations/get_results'
+require 'remit/operations/get_recipient_verification_status'
 require 'remit/operations/get_token_by_caller'
 require 'remit/operations/get_token_usage'
 require 'remit/operations/get_tokens'
 require 'remit/operations/get_total_prepaid_liability'
 require 'remit/operations/get_transaction'
+require 'remit/operations/get_transaction_status'
 require 'remit/operations/install_payment_instruction'
 require 'remit/operations/pay'
 require 'remit/operations/refund'
 require 'remit/operations/reserve'
-require 'remit/operations/retry_transaction'
 require 'remit/operations/settle'
 require 'remit/operations/settle_debt'
 require 'remit/operations/subscribe_for_caller_notification'
@@ -50,9 +55,11 @@ require 'remit/operations/write_off_debt'
 
 module Remit
   class API < Relax::Service
+
+    include VerifySignature
     include CancelSubscriptionAndRefund
     include CancelToken
-    include DiscardResults
+    include Cancel
     include FundPrepaid
     include GetAccountActivity
     include GetAccountBalance
@@ -63,7 +70,7 @@ module Remit
     include GetPaymentInstruction
     include GetPipeline
     include GetPrepaidBalance
-    include GetResults
+    include GetRecipientVerificationStatus
     include GetTokenUsage
     include GetTokens
     include GetTokenByCaller
@@ -73,7 +80,6 @@ module Remit
     include Pay
     include Refund
     include Reserve
-    include RetryTransaction
     include Settle
     include SettleDebt
     include SubscribeForCallerNotification
@@ -84,53 +90,43 @@ module Remit
     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
+    API_VERSION = Date.new(2008, 9, 17).to_s.freeze
+    PIPELINE_VERSION = Date.new(2009, 1, 9).to_s.freeze
     SIGNATURE_VERSION = 2.freeze
+    SIGNATURE_METHOD = "HmacSHA256".freeze
 
+    #attr_reader :pipeline      # kickstarter
+    attr_reader :pipeline_url   # nyc
     attr_reader :access_key
     attr_reader :secret_key
-    attr_reader :pipeline_url
+    attr_reader :api_endpoint
 
     def initialize(access_key, secret_key, sandbox=false)
       @access_key = access_key
       @secret_key = secret_key
       @pipeline_url = sandbox ? PIPELINE_SANDBOX_URL : PIPELINE_URL
-
-      super(sandbox ? API_SANDBOX_ENDPOINT : API_ENDPOINT)
+      @api_endpoint = sandbox ? API_SANDBOX_ENDPOINT : API_ENDPOINT
+      super(@api_endpoint)
     end
-
-    def new_query(query={})
-      SignedQuery.new(@endpoint, @secret_key, query)
+    
+    # generates v1 signatures, for historical purposes.
+    def self.signature_v1(path, params, secret_key)
+      params = params.reject {|key, val| ['awsSignature', 'action', 'controller', 'id'].include?(key) }.sort_by{ |k,v| k.to_s.downcase }.map{|k,v| "#{CGI::escape(k)}=#{Remit::SignedQuery.escape_value(v)}"}.join('&')
+      signable = path + '?' + params
+      Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, secret_key, signable)).strip
     end
-    private :new_query
 
-    def default_query
-      new_query({
+    private
+
+    # called from Relax::Service#call
+    def query(request)
+      params = request.to_query.merge(
         :AWSAccessKeyId => @access_key,
-        :SignatureVersion => SIGNATURE_VERSION,
-        Amazon::FPS::SignatureUtils::SIGNATURE_METHOD_KEYNAME => Amazon::FPS::SignatureUtils::HMAC_SHA256_ALGORITHM,
         :Version => API_VERSION,
         :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
+      )
+      ApiQuery.new(@endpoint, @secret_key, params)
     end
-    private :query
-
-    def sign(values)
-      signature = Amazon::FPS::SignatureUtils.sign_parameters({
-                                              :parameters => values,
-                                              :aws_secret_key => @secret_key,
-                                              :host => @endpoint.host,
-                                              :verb => "GET",
-                                              :uri  => @endpoint.path })
-      return signature
-    end
-    private :sign
   end
 end
+

data/lib/remit/common.rb

@@ -9,14 +9,19 @@ require File.dirname(__FILE__) + '/../amazon/fps/signatureutils'
 require File.dirname(__FILE__) + '/../amazon/fps/signatureutilsforoutbound'
 
 module Remit
+
+  module ConvertKey
+    def convert_key(key)
+      key.to_s.gsub(/(^|_)(.)/) { $2.upcase }.to_sym
+    end
+  end
+
   class Request < Relax::Request
     def self.action(name)
       parameter :action, :value => name
     end
 
-    def convert_key(key)
-      key.to_s.gsub(/(^|_)(.)/) { $2.upcase }.to_sym
-    end
+    include ConvertKey
     protected :convert_key
   end
 
@@ -26,24 +31,38 @@ module Remit
     end
   end
 
+  class ResponseMetadata < BaseResponse
+    # Amazon FPS returns a RequestId element for every API call accepted for processing
+    # that means not *every* call will have a request ID.
+    parameter :request_id#, :required => true
+    parameter :signature_version
+    parameter :signature_method
+  end  
+
   class Response < BaseResponse
-    parameter :request_id
+    parameter :response_metadata, :type => Remit::ResponseMetadata, :required => true
 
     attr_accessor :status
     attr_accessor :errors
 
+    def request_id
+      self.response_metadata.respond_to?(:request_id) ? self.response_metadata.request_id : nil
+    end
+
     def initialize(xml)
       super
 
-      if is?(:Response) && has?(:Errors)
-        @errors = elements(:Errors).collect do |error|
+      # TODO: How to differentiate between Error and Service Error properly? - pboling
+      # TODO: Is this ServiceError still relevant? - pboling
+      if is?(:Response) and has?(:Errors)
+        @errors = elements('errors/error').collect do |error|
           Error.new(error)
         end
       else
         @status = text_value(element(:Status))
-        @errors = elements('Errors/Errors').collect do |error|
+        @errors = elements('errors/errors').collect do |error|
           ServiceError.new(error)
-        end unless successful?
+        end if not successful?
       end
     end
 
@@ -59,42 +78,78 @@ module Remit
   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
+      sign
     end
 
     def sign
-      self[Amazon::FPS::SignatureUtils::SIGNATURE_VERSION_KEYNAME] = Remit::API::SIGNATURE_VERSION
-      self[Amazon::FPS::SignatureUtils::SIGNATURE_METHOD_KEYNAME] = Amazon::FPS::SignatureUtils::HMAC_SHA256_ALGORITHM
-
-      signature = Amazon::FPS::SignatureUtils.sign_parameters({
-                                              :parameters => self,
-                                              :aws_secret_key => @secret_key,
-                                              :host => @uri.host,
-                                              :verb => "GET",
-                                              :uri  => @uri.path })
+      store(:signatureVersion, Remit::API::SIGNATURE_VERSION)
+      store(:signatureMethod, Remit::API::SIGNATURE_METHOD)
+      store(:signature, signature)
+    end
 
-      store(Amazon::FPS::SignatureUtilsForOutbound::SIGNATURE_KEYNAME.to_sym, signature)
+    def signature
+      Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, @secret_key, signable_string)).strip
     end
 
-    def to_s(signed=true)
-      sign if signed
-      super()
+    def signable_string
+      [ 'GET',
+        @uri.host,
+        @uri.path,
+        to_s # the query string, sans :signature (but with :signatureVersion and :signatureMethod)
+      ].join("\n")
     end
 
     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('=', 2)
           query[key] = unescape_value(value)
         end
-
         query
       end
+
+      UNSAFE = /[^A-Za-z0-9_.~-]/
+      # Amazon is very specific about what chars should be escaped, and which should not.
+      def escape_value(value)
+        # note that URI.escape(' ') => '%20', and CGI.escape(' ') => '+'
+        URI.escape(value.to_s, UNSAFE)
+      end
+    end
+  end
+
+  # Frustratingly enough, API requests want the signature params with slightly different casing.
+  class ApiQuery < SignedQuery
+    def sign
+      store(:SignatureVersion, Remit::API::SIGNATURE_VERSION)
+      store(:SignatureMethod, 'HmacSHA256')
+      store(:Signature, signature)
+    end
+  end
+end
+
+#Hack on Hash to make it s rocket
+class Hash
+  def to_url_params
+    elements = []
+    keys.size.times do |i|
+      elements << "#{(keys[i])}=#{Remit::SignedQuery.escape_value(values[i])}"
+    end
+    elements.join('&')
+  end
+
+  def self.from_url_params(url_params)
+    result = {}
+    url_params.split('&').each do |element|
+      element = element.split('=')
+      # BJM - need to unescape the values in the param string
+      #result[element[0]] = element[1]
+      result[element[0]] = CGI.unescape(element[1])
     end
+    result
   end
 end

data/lib/remit/data_types.rb

@@ -3,10 +3,32 @@ require 'relax'
 
 require 'remit/common'
 
+def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
+  if first_letter_in_uppercase
+    lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+  else
+    lower_case_and_underscored_word.first + camelize(lower_case_and_underscored_word)[1..-1]
+  end
+end
+
+module Relax
+  class Response
+    class << self
+      alias_method :alias_for_parameter, :parameter
+      def parameter(name, options = {})
+        opts = {
+          :element => camelize(name)
+        }.merge!(options)
+        alias_for_parameter(name, opts)
+      end
+    end
+  end
+end
+
 module Remit
   class Amount < BaseResponse
     parameter :currency_code
-    parameter :amount, :type => :float
+    parameter :value, :type => :float
   end
 
   class TemporaryDeclinePolicy < BaseResponse
@@ -16,7 +38,7 @@ module Remit
 
   class DescriptorPolicy < BaseResponse
     parameter :soft_descriptor_type
-    parameter :CS_number_of
+    parameter :CS_owner
   end
 
   class ChargeFeeTo
@@ -27,6 +49,12 @@ module Remit
   class Error < BaseResponse
     parameter :code
     parameter :message
+    def error_code
+      self.code
+    end
+    def reason_text
+      self.message
+    end
   end
 
   class InstrumentStatus
@@ -36,7 +64,7 @@ module Remit
   end
 
   class PaymentMethods
-    BALANCE_TRANSFER = 'abt'
+    BALANCE_aFER = 'abt'
     BANK_ACCOUNT = 'ach'
     CREDIT_CARD = 'credit card'
     PREPAID = 'prepaid'
@@ -63,9 +91,9 @@ module Remit
   class Token < BaseResponse
     parameter :token_id
     parameter :friendly_name
-    parameter :status
+    parameter :token_status
     parameter :date_installed, :type => :time
-    parameter :caller_installed
+    #parameter :caller_installed
     parameter :caller_reference
     parameter :token_type
     parameter :old_token_id
@@ -84,27 +112,65 @@ module Remit
     parameter :last_reset_count
     parameter :last_reset_time_stamp
   end
+  
+  class TransactionPart < Remit::BaseResponse
+    parameter :account_id
+    parameter :role
+    parameter :name
+    parameter :reference
+    parameter :description
+    parameter :fee_paid, :type => Amount
+  end
+    
+  class Transaction < BaseResponse
+    
+    parameter :caller_name
+    parameter :caller_reference
+    parameter :caller_description
+    parameter :caller_transaction_date, :type => :time
+    parameter :date_completed, :type => :time
+    parameter :date_received, :type => :time
+    parameter :error_code
+    parameter :error_message
+    parameter :fees, :element=>"FPSFees", :type => Amount
+    parameter :fps_fees_paid_by, :element=>"FPSFeesPaidBy"
+    parameter :fps_operation, :element=>"FPSOperation"
+    parameter :meta_data
+    parameter :payment_method
+    parameter :recipient_name
+    parameter :recipient_email
+    parameter :recipient_token_id
+    parameter :related_transactions
+    parameter :sender_email
+    parameter :sender_name
+    parameter :sender_token_id
+    parameter :transaction_status
+    parameter :status_code
+    parameter :status_history
+    parameter :status_message
+    parameter :transaction_amount, :type => Amount
+    parameter :transaction_id
+    parameter :transaction_parts, :collection => TransactionPart, :element=>"TransactionPart"
+  end
 
   class TransactionResponse < BaseResponse
     parameter :transaction_id
-    parameter :status
-    parameter :status_detail
-    parameter :new_sender_token_usage, :type => TokenUsageLimit
+    parameter :transaction_status
 
-    %w(reserved success failure initiated reinitiated temporary_decline).each do |status_name|
+    %w(cancelled failure pending reserved success).each do |status_name|
       define_method("#{status_name}?") do
-        self.status == Remit::TransactionStatus.const_get(status_name.sub('_', '').upcase)
+        self.transaction_status == Remit::TransactionStatus.const_get(status_name.sub('_', '').upcase)
       end
     end
   end
 
   class TransactionStatus
+    #For IPN operations these strings are upcased.  For Non-IPN operations they are not upcased
+    CANCELLED         = 'Cancelled'
+    FAILURE           = 'Failure'
+    PENDING           = 'Pending'
     RESERVED          = 'Reserved'
     SUCCESS           = 'Success'
-    FAILURE           = 'Failure'
-    INITIATED         = 'Initiated'
-    REINITIATED       = 'Reinitiated'
-    TEMPORARYDECLINE  = 'TemporaryDecline'
   end
 
   class TokenType
@@ -121,11 +187,13 @@ module Remit
     RECIPIENT = 'Recipient'
     SETUP_PREPAID = 'SetupPrepaid'
     SETUP_POSTPAID = 'SetupPostpaid'
+    EDIT_TOKEN = 'EditToken'
   end
 
   class PipelineStatusCode
     CALLER_EXCEPTION  = 'CE'  # problem with your code
     SYSTEM_ERROR      = 'SE'  # system error, try again
+    SUCCESS_UNCHANGED = 'SU'  # edit token pipeline finished, but token is unchanged
     SUCCESS_ABT       = 'SA'  # successful payment with Amazon balance
     SUCCESS_ACH       = 'SB'  # successful payment with bank transfer
     SUCCESS_CC        = 'SC'  # successful payment with credit card
@@ -138,10 +206,10 @@ module Remit
 
   module RequestTypes
     class Amount < Remit::Request
-      parameter :amount
+      parameter :value
       parameter :currency_code
     end
-
+    
     class TemporaryDeclinePolicy < Remit::Request
       parameter :temporary_decline_policy_type
       parameter :implicit_retry_timeout_in_mins
@@ -149,10 +217,42 @@ module Remit
 
     class DescriptorPolicy < Remit::Request
       parameter :soft_descriptor_type
-      parameter :CS_number_of
+      parameter :CS_owner
     end
+
+  end
+  
+  class SoftDescriptorType
+    STATIC = 'Static'
+    DYNAMIC = 'Dynamic'
+  end
+
+  #MarketplaceRefundPolicy is available in these APIs:
+  # Amazon FPS Advanced Quick Start
+  # Amazon FPS Marketplace Quick Start
+  # Amazon FPS Aggregated Payments Quick Start
+  # i.e. Not Basic Quick Start
+  #It really should be listed under Enumerated DataTypes:
+  #MarketplaceTxnOnly      Caller refunds his fee to the recipient.             String
+  #MasterAndMarketplaceTxn Caller and Amazon FPS refund their fees to the       String
+  #                        sender, and the recipient refunds his amount
+  #MasterTxnOnly           Caller does not refund his fee. Amazon FPS           String
+  #                        refunds its fee and the recipient refunds his amount
+  #                        plus the caller's fee to the sender.
+  class MarketplaceRefundPolicy
+    POLICY = {
+      :marketplace_txn_only => 'MarketplaceTxnOnly',
+      :master_and_marketplace_txn => 'MasterAndMarketplaceTxn',
+      :master_txn_only => 'MasterTxnOnly' #default if not specified, set by Amazon FPS
+    }
   end
 
+  class TemporaryDeclinePolicyType
+    EXPLICIT_RETRY = 'ExplicitRetry'
+    IMPLICIT_RETRY = 'ImplicitRetry'
+    FAILURE = 'Failure'
+  end
+    
   class Operation
     PAY             = "Pay"
     REFUND          = "Refund"
@@ -161,4 +261,5 @@ module Remit
     WRITE_OFF_DEBT  = "WriteOffDebt"
     FUND_PREPAID    = "FundPrepaid"
   end
+  
 end