revo-remit 0.2.3

data/LICENSE

@@ -0,0 +1,20 @@
+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
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,122 @@
+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
+
+
+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 Gemfile:
+
+    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:
+
+    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:
+
+ * [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

@@ -0,0 +1,132 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'openssl'
+require 'net/https'
+require 'uri'
+require 'date'
+require 'base64'
+require 'erb'
+require 'cgi'
+
+require 'rubygems'
+
+gem 'relax', '0.0.7'
+require 'relax'
+
+
+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/cancel'
+require 'remit/operations/fund_prepaid'
+require 'remit/operations/get_account_activity'
+require 'remit/operations/get_account_balance'
+require 'remit/operations/get_all_credit_instruments'
+require 'remit/operations/get_all_prepaid_instruments'
+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_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/settle'
+require 'remit/operations/settle_debt'
+require 'remit/operations/subscribe_for_caller_notification'
+require 'remit/operations/unsubscribe_for_caller_notification'
+require 'remit/operations/write_off_debt'
+
+module Remit
+  class API < Relax::Service
+
+    include VerifySignature
+    include CancelSubscriptionAndRefund
+    include CancelToken
+    include Cancel
+    include FundPrepaid
+    include GetAccountActivity
+    include GetAccountBalance
+    include GetAllCreditInstruments
+    include GetAllPrepaidInstruments
+    include GetDebtBalance
+    include GetOutstandingDebtBalance
+    include GetPaymentInstruction
+    include GetPipeline
+    include GetPrepaidBalance
+    include GetRecipientVerificationStatus
+    include GetTokenUsage
+    include GetTokens
+    include GetTokenByCaller
+    include GetTotalPrepaidLiability
+    include GetTransaction
+    include InstallPaymentInstruction
+    include Pay
+    include Refund
+    include Reserve
+    include Settle
+    include SettleDebt
+    include SubscribeForCallerNotification
+    include UnsubscribeForCallerNotification
+    include WriteOffDebt
+
+    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(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 :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
+      @api_endpoint = sandbox ? API_SANDBOX_ENDPOINT : API_ENDPOINT
+      super(@api_endpoint)
+    end
+    
+    # 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
+
+    # called from Relax::Service#call
+    def query(request)
+      params = request.to_query.merge(
+        :AWSAccessKeyId => @access_key,
+        :Version => API_VERSION,
+        :Timestamp => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+      )
+      ApiQuery.new(@endpoint, @secret_key, params)
+    end
+  end
+end
+

data/lib/remit/common.rb

@@ -0,0 +1,151 @@
+require 'base64'
+require 'erb'
+require 'uri'
+
+require 'rubygems'
+require 'relax'
+
+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
+
+    include ConvertKey
+    protected :convert_key
+  end
+
+  class BaseResponse < Relax::Response
+    def node_name(name, namespace=nil)
+      super(name.to_s.gsub(/(^|_)(.)/) { $2.upcase }, namespace)
+    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 :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
+
+      #TODO: How to differentiate between Error and Service Error
+      if is?(:Response) and has?(:Errors)
+        @errors = elements(:Errors).collect do |error|
+          Error.new(error)
+        end
+      else
+        @status = text_value(element(:Status))
+        @errors = elements('errors/errors').collect do |error|
+          ServiceError.new(error)
+        end if not successful?
+      end
+    end
+
+    def successful?
+      @status == ResponseStatus::SUCCESS
+    end
+
+    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 = {})
+      super(query)
+      @uri = URI.parse(uri.to_s)
+      @secret_key = secret_key
+      sign
+    end
+
+    def sign
+      store(:signatureVersion, Remit::API::SIGNATURE_VERSION)
+      store(:signatureMethod, Remit::API::SIGNATURE_METHOD)
+      store(:signature, signature)
+    end
+
+    def signature
+      Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, @secret_key, signable_string)).strip
+    end
+
+    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

@@ -0,0 +1,265 @@
+require 'rubygems'
+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 :value, :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_owner
+  end
+
+  class ChargeFeeTo
+    CALLER = 'Caller'
+    RECIPIENT = 'Recipient'
+  end
+
+  class Error < BaseResponse
+    parameter :code
+    parameter :message
+    def error_code
+      self.code
+    end
+    def reason_text
+      self.message
+    end
+  end
+
+  class InstrumentStatus
+    ALL = 'ALL'
+    ACTIVE = 'Active'
+    INACTIVE = 'Inactive'
+  end
+
+  class PaymentMethods
+    BALANCE_aFER = 'abt'
+    BANK_ACCOUNT = 'ach'
+    CREDIT_CARD = 'credit card'
+    PREPAID = 'prepaid'
+    DEBT = 'Debt'
+  end
+
+  class ServiceError < BaseResponse
+    parameter :error_type
+    parameter :is_retriable
+    parameter :error_code
+    parameter :reason_text
+
+    class ErrorType
+      SYSTEM = 'System'
+      BUSINESS = 'Business'
+    end
+  end
+
+  class ResponseStatus
+    SUCCESS = 'Success'
+    FAILURE = 'Failure'
+  end
+
+  class Token < BaseResponse
+    parameter :token_id
+    parameter :friendly_name
+    parameter :token_status
+    parameter :date_installed, :type => :time
+    #parameter :caller_installed
+    parameter :caller_reference
+    parameter :token_type
+    parameter :old_token_id
+    parameter :payment_reason
+
+    class TokenStatus
+      ACTIVE = 'Active'
+      INACTIVE = 'Inactive'
+    end
+  end
+
+  class TokenUsageLimit < BaseResponse
+    parameter :count
+    parameter :limit
+    parameter :last_reset_amount
+    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, :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 :transaction_status
+
+    %w(cancelled failure pending reserved success).each do |status_name|
+      define_method("#{status_name}?") do
+        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'
+  end
+
+  class TokenType
+    SINGLE_USE = 'SingleUse'
+    MULTI_USE = 'MultiUse'
+    RECURRING = 'Recurring'
+    UNRESTRICTED = 'Unrestricted'
+  end
+
+  class PipelineName
+    SINGLE_USE = 'SingleUse'
+    MULTI_USE = 'MultiUse'
+    RECURRING = 'Recurring'
+    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
+    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 :value
+      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_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"
+    SETTLE          = "Settle"
+    SETTLE_DEBT     = "SettleDebt"
+    WRITE_OFF_DEBT  = "WriteOffDebt"
+    FUND_PREPAID    = "FundPrepaid"
+  end
+  
+end