remit2 0.0.7

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Micah Wedemeyer
+
+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,26 @@
+Remit2
+======
+
+This API provides access to the Amazon Flexible Payment Service (FPS), using the
+2008-09-17 version of the API and Signature Version 2.
+
+Remit2 is forked from the original Remit library written by Tyler Hunt, which was
+built for the 2007-08-01 FPS API version and Signature Version 1. Due to serious
+incompatibilities between the two API versions, I decided to fork the library
+and give up backward compatibility with the older API version.
+
+Working with Remit2 should very closely resemble working with Remit, with the exception
+of the changed API parameter and function names. However, due to these same changes, it's
+almost never the case that Remit2 can be dropped in place of Remit without some changes
+to the client code. For example, the *Amount* parameter in the *Pay* operation has
+changed, and nearly every FPS client application will need to use *Pay*.
+
+**WARNING** - This gem should be considered very volatile and incomplete. I (Micah)
+am not looking to write a full wrapper around the FPS API. My only goal is to get it
+working for my needs. Therefore, many of the functions/API calls will be broken.
+Patches are welcome if you want to make additions.
+
+I have explicitly marked some files as "# Updated for API Version 2008-09-17". If
+you don't see this near the top of the file, assume that it doesn't work!
+
+Copyright (c) 2010 Micah Wedemeyer, released under the MIT license

data/lib/remit2.rb

@@ -0,0 +1,119 @@
+require 'uri'
+require 'openssl'
+require 'openssl/digest'
+require 'net/https'
+require 'date'
+require 'base64'
+require 'erb'
+require 'cgi'
+
+require 'rubygems'
+
+gem 'relax', '0.0.7'
+require 'relax'
+
+require 'remit2/signature'
+require 'remit2/request'
+require 'remit2/response'
+require 'remit2/data_types'
+require 'remit2/error_codes'
+require 'remit2/ipn_request'
+require 'remit2/get_pipeline'
+require 'remit2/pipeline_response'
+
+require 'remit2/operations/cancel_subscription_and_refund'
+require 'remit2/operations/cancel_token'
+require 'remit2/operations/discard_results'
+require 'remit2/operations/fund_prepaid'
+require 'remit2/operations/get_account_activity'
+require 'remit2/operations/get_account_balance'
+require 'remit2/operations/get_all_credit_instruments'
+require 'remit2/operations/get_all_prepaid_instruments'
+require 'remit2/operations/get_debt_balance'
+require 'remit2/operations/get_outstanding_debt_balance'
+require 'remit2/operations/get_payment_instruction'
+require 'remit2/operations/get_prepaid_balance'
+require 'remit2/operations/get_results'
+require 'remit2/operations/get_token_by_caller'
+require 'remit2/operations/get_token_usage'
+require 'remit2/operations/get_tokens'
+require 'remit2/operations/get_total_prepaid_liability'
+require 'remit2/operations/get_transaction'
+require 'remit2/operations/install_payment_instruction'
+require 'remit2/operations/pay'
+require 'remit2/operations/refund'
+require 'remit2/operations/reserve'
+require 'remit2/operations/retry_transaction'
+require 'remit2/operations/settle'
+require 'remit2/operations/settle_debt'
+require 'remit2/operations/write_off_debt'
+
+module Remit
+  class API < Relax::Service
+    include Signature
+    
+    include CancelSubscriptionAndRefund
+    include CancelToken
+    include DiscardResults
+    include FundPrepaid
+    include GetAccountActivity
+    include GetAccountBalance
+    include GetAllCreditInstruments
+    include GetAllPrepaidInstruments
+    include GetDebtBalance
+    include GetOutstandingDebtBalance
+    include GetPaymentInstruction
+    include GetPipeline
+    include GetPrepaidBalance
+    include GetResults
+    include GetTokenUsage
+    include GetTokens
+    include GetTokenByCaller
+    include GetTotalPrepaidLiability
+    include GetTransaction
+    include InstallPaymentInstruction
+    include Pay
+    include Refund
+    include Reserve
+    include RetryTransaction
+    include Settle
+    include SettleDebt
+    include WriteOffDebt
+
+    API_ENDPOINT = 'https://fps.amazonaws.com/'
+    API_SANDBOX_ENDPOINT = 'https://fps.sandbox.amazonaws.com/'
+    PIPELINE_URL = 'https://authorize.payments.amazon.com/cobranded-ui/actions/start'
+    PIPELINE_SANDBOX_URL = 'https://authorize.payments-sandbox.amazon.com/cobranded-ui/actions/start'
+    API_VERSION = "2008-09-17"
+    SIGNATURE_VERSION = 2
+    SIGNATURE_METHOD = "HmacSHA256"
+
+    attr_reader :access_key
+    attr_reader :secret_key
+    attr_reader :pipeline_url
+
+    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)
+    end
+
+    def default_query
+      Relax::Query.new({
+        :AWSAccessKeyId => @access_key,
+        :SignatureVersion => SIGNATURE_VERSION,
+        :SignatureMethod => SIGNATURE_METHOD,
+        :Version => API_VERSION,
+        :Timestamp => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+      })
+    end
+
+    def query(request)
+      query = super
+      query[:Signature] = sign(@secret_key, @endpoint, "GET", query)
+      query
+    end
+  end
+end

data/lib/remit2/data_types.rb

@@ -0,0 +1,142 @@
+module Remit
+  class Amount < BaseResponse
+    parameter :currency_code
+    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'
+  end
+
+  class Error < BaseResponse
+    parameter :code
+    parameter :message
+  end
+
+  class InstrumentStatus
+    ALL = 'ALL'
+    ACTIVE = 'Active'
+    INACTIVE = 'Inactive'
+  end
+
+  class PaymentMethods
+    BALANCE_TRANSFER = 'abt'
+    BANK_ACCOUNT = 'ach'
+    CREDIT_CARD = 'credit card'
+    PREPAID = 'prepaid'
+    DEBT = 'Debt'
+  end
+
+  class Token < BaseResponse
+    parameter :token_id
+    parameter :friendly_name
+    parameter :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 TransactionResponse < BaseResponse
+    parameter :transaction_id
+    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 RefundResult < BaseResponse
+    parameter :transaction_id
+    parameter :transaction_status
+  end
+
+  class TransactionStatus
+    RESERVED          = 'Reserved'
+    SUCCESS           = 'Success'
+    FAILURE           = 'Failure'
+    INITIATED         = 'Initiated'
+    REINITIATED       = 'Reinitiated'
+    TEMPORARYDECLINE  = 'TemporaryDecline'
+  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'
+  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 :value
+      parameter :currency_code
+    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/remit2/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/remit2/get_pipeline.rb

@@ -0,0 +1,195 @@
+# Updated for API Version 2008-09-17
+module Remit
+  module GetPipeline
+    class Pipeline
+      include Signature
+      
+      @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.to_s.gsub(/_(.)/) { $1.upcase }.to_sym
+        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
+      
+      parameter :pipeline_name
+      parameter :return_url
+      parameter :caller_key
+      parameter :version
+      parameter :address_name
+      parameter :address_line_1
+      parameter :address_line_2
+      parameter :city
+      parameter :state
+      parameter :zip
+      parameter :country
+      parameter :phone_number
+
+      def initialize(api, options)
+        @api = api
+        
+        options.each do |k,v|
+          self.send("#{k}=", v)
+        end
+      end
+
+      def url
+        uri = URI.parse(@api.pipeline_url)
+        
+        query = {
+          "signatureVersion" => "2",
+          "signatureMethod" => "HmacSHA256",
+          "version" => "2009-01-09"
+        }
+        
+        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.to_s)] = val
+        end
+
+        # Remove any unused optional parameters
+        query.reject! { |key, value| value.nil? || (value.is_a?(String) && value.empty?) }
+        
+        signature = sign(@api.secret_key, @api.pipeline_url, "GET", query)
+        uri.query = query.merge('signature' => signature).collect {|k,v| "#{CGI::escape(k.to_s)}=#{CGI::escape(v.to_s)}"}.join("&")
+        
+        uri.to_s
+      end
+    end
+    
+    class SingleUsePipeline < Pipeline
+      parameter :caller_reference
+      parameter :payment_reason
+      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
+      parameter :caller_reference
+      parameter :payment_reason
+      parameter :recipient_token
+      parameter :transaction_amount
+      parameter :validity_start # Time or seconds from Epoch
+      parameter :validity_expiry # Time or seconds from Epoch
+      parameter :payment_method
+      parameter :recurring_period  
+      
+      def pipeline_name
+        Remit::PipelineName::RECURRING
+      end 
+    end
+    
+    class PostpaidPipeline < Pipeline
+      parameter :caller_reference_sender
+      parameter :caller_reference_settlement
+      parameter :payment_reason
+      parameter :payment_method
+      parameter :validity_start # Time or seconds from Epoch
+      parameter :validity_expiry # Time or seconds from Epoch
+      parameter :credit_limit
+      parameter :global_amount_limit
+      parameter :usage_limit_type1
+      parameter :usage_limit_period1
+      parameter :usage_limit_value1
+      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)
+    end
+    
+    def get_postpaid_pipeline(options)
+      self.get_pipeline(PostpaidPipeline, options)
+    end
+    
+    def get_pipeline(pipeline_subclass, options)
+      pipeline = pipeline_subclass.new(self, {
+        :caller_key => @access_key
+      }.merge(options))
+    end
+  end
+end