amazon_flex_pay 0.9.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Lance Ivy
+
+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.rdoc

@@ -0,0 +1,41 @@
+= AmazonFlexPay
+
+Library for Amazon's Flexible Payment Service.
+
+== CONFIGURE
+
+In config/initializers/amazon_flex_pay.rb, do the following:
+
+  AmazonFlexPay.access_key = 'your access key'
+  AmazonFlexPay.secret_key = 'your secret key'
+  AmazonFlexPay.go_live! # if you're done with the sandbox
+
+== EXAMPLES
+
+Note that while the examples are shown using Rails methods, the only Rails requirement is ActiveSupport's inflector.
+
+1. Construct a single-use pipeline for the user. This is where the user will agree to pay a certain amount to a specific recipient.
+
+     pipeline = AmazonFlexPay.single_use_pipeline('mypipeline3292', :recipient_token => 'RTOKEN', :transaction_amount => '12.99')
+     redirect_to pipeline.url('http://example.com/return')
+
+2. Then on the return page, take the sender token and run a Pay request:
+
+     response = AmazonFlexPay.pay('12.99', 'USD', 'STOKEN', 'myrequest3292')
+     if response.error?
+       flash[:error] = "Sorry, something went wrong."
+       response.errors.each do |error|
+         # notify yourself about error.code and error.message
+       end
+     else
+       flash[:notice] = "Thanks! Your payment is processing."
+     end
+     redirect_to product_path
+
+3. Then wait for a IPN to your registered listening URL and check that it's successful.
+
+== LEARN MORE
+
+All methods required for integrating API calls and Pipeline requests are found in the AmazonFlexPay module.
+
+Copyright (c) 2011 Lance Ivy, released under the MIT license.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the AmazonFlexPay plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the AmazonFlexPay plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'AmazonFlexPay'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/amazon_flex_pay/api/base.rb

@@ -0,0 +1,86 @@
+module AmazonFlexPay::API #:nodoc:
+  class Base < AmazonFlexPay::Model
+    # This compiles an API request object into a URL, sends it to Amazon, and processes
+    # the response.
+    def submit
+      url = AmazonFlexPay.api_endpoint + '?' + AmazonFlexPay.query_string(self.to_params)
+      response = begin
+        self.class::Response.from_xml(RestClient.get(url).body)
+      rescue RestClient::BadRequest, RestClient::Unauthorized, RestClient::Forbidden => e
+        ErrorResponse.from_xml(e.response.body)
+      end
+      response.request = self
+      response
+    end
+
+    # Converts the API request object into parameters and signs them.
+    def to_params
+      params = self.to_hash.merge(
+        'Action' => action_name,
+        'AWSAccessKeyId' => AmazonFlexPay.access_key,
+        'Version' => AmazonFlexPay::API_VERSION,
+        'Timestamp' => format_value(Time.now)
+      )
+
+      params['SignatureVersion'] = 2
+      params['SignatureMethod'] = 'HmacSHA256'
+      params['Signature'] = AmazonFlexPay.signature(AmazonFlexPay.api_endpoint, params)
+
+      params
+    end
+
+    class BaseResponse < AmazonFlexPay::Model
+      attribute :request
+      attribute :request_id
+
+      # Check response.error? to determine whether it's an ErrorResponse or not.
+      def error?
+        false
+      end
+
+      # Parses Amazon's XML response to REST requests and instantiates the response.
+      def self.from_xml(xml)
+        response = MultiXml.parse(xml)
+
+        response_key = response.keys.find{|k| k.match(/Response$/)}
+        hash = response[response_key]['ResponseMetadata']
+
+        result_key = response[response_key].keys.find{|k| k.match(/Result$/)}
+        hash.merge!(response[response_key][result_key]) if response[response_key][result_key] # not all APIs have a result object
+
+        new(hash)
+      end
+    end
+
+    class ErrorResponse < AmazonFlexPay::Model #:nodoc:
+      # Re-implements the XML parsing because ErrorResponse does not inherit from BaseResponse.
+      def self.from_xml(xml)
+        new(MultiXml.parse(xml)['Response'])
+      end
+
+      # Check response.error? to determine whether Amazon accepted the request.
+      def error?
+        true
+      end
+
+      attribute :request
+      attribute :request_id
+
+      attr_reader :errors
+      def errors=(val)
+        @errors = [val['Error']].flatten.map{|e| Error.new(e)}
+      end
+
+      class Error < AmazonFlexPay::Model #:nodoc:
+        attribute :code
+        attribute :message
+      end
+    end
+
+    protected
+
+    def action_name #:nodoc:
+      self.class.to_s.split('::').last
+    end
+  end
+end

data/lib/amazon_flex_pay/api/cancel.rb

@@ -0,0 +1,11 @@
+module AmazonFlexPay::API #:nodoc:
+  class Cancel < Base #:nodoc:
+    attribute :transaction_id
+    attribute :description
+
+    class Response < BaseResponse #:nodoc:
+      attribute :transaction_id
+      attribute :transaction_status, :enumeration => :transaction_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/cancel_token.rb

@@ -0,0 +1,9 @@
+module AmazonFlexPay::API #:nodoc:
+  class CancelToken < Base #:nodoc:
+    attribute :token_id
+    attribute :reason_text
+
+    class Response < BaseResponse #:nodoc:
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_account_activity.rb

@@ -0,0 +1,21 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetAccountActivity < Base #:nodoc:
+    attribute :start_date # required
+    attribute :end_date
+    attribute :'FPSOperation', :enumeration => :fps_operation
+    attribute :max_batch_size
+    attribute :payment_method, :enumeration => :payment_method
+    attribute :response_group
+    attribute :role, :enumeration => :transactional_role
+    attribute :sort_order_by_date, :enumeration => :sort_order_by_date
+    attribute :status, :type => :transaction_status
+
+    class Response < BaseResponse #:nodoc:
+      attribute :batch_size
+      attribute :start_time_for_next_transaction
+      attribute :transaction, :collection => :transaction
+
+      alias_method :transactions, :transaction
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_account_balance.rb

@@ -0,0 +1,8 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetAccountBalance < Base #:nodoc:
+
+    class Response < BaseResponse #:nodoc:
+      attribute :account_balance, :type => :account_balance
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_recipient_verification_status.rb

@@ -0,0 +1,9 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetRecipientVerificationStatus < Base #:nodoc:
+    attribute :recipient_token_id
+
+    class Response < BaseResponse #:nodoc:
+      attribute :recipient_verification_status, :enumeration => :recipient_verification_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_token_by_caller.rb

@@ -0,0 +1,10 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetTokenByCaller < Base #:nodoc:
+    attribute :token_id
+    attribute :caller_reference
+
+    class Response < BaseResponse #:nodoc:
+      attribute :token, :type => :token
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_token_usage.rb

@@ -0,0 +1,9 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetTokenUsage < Base #:nodoc:
+    attribute :token_id
+
+    class Response < BaseResponse #:nodoc:
+      attribute :token_usage_limits, :collection => :token_usage_limit
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_tokens.rb

@@ -0,0 +1,13 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetTokens < Base #:nodoc:
+    attribute :caller_reference
+    attribute :token_status
+    attribute :token_type
+
+    class Response < BaseResponse #:nodoc:
+      attribute :token, :collection => :token
+
+      alias_method :tokens, :token
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_transaction.rb

@@ -0,0 +1,9 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetTransaction < Base #:nodoc:
+    attribute :transaction_id
+
+    class Response < BaseResponse #:nodoc:
+      attribute :transaction, :type => :transaction_detail
+    end
+  end
+end

data/lib/amazon_flex_pay/api/get_transaction_status.rb

@@ -0,0 +1,13 @@
+module AmazonFlexPay::API #:nodoc:
+  class GetTransactionStatus < Base #:nodoc:
+    attribute :transaction_id
+
+    class Response < BaseResponse #:nodoc:
+      attribute :caller_reference
+      attribute :status_code
+      attribute :status_message
+      attribute :transaction_id
+      attribute :transaction_status, :enumeration => :transaction_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/pay.rb

@@ -0,0 +1,20 @@
+module AmazonFlexPay::API #:nodoc:
+  class Pay < Base #:nodoc:
+    attribute :caller_description
+    attribute :caller_reference # required
+    attribute :charge_fee_to, :enumeration => :charge_fee_to
+    attribute :descriptor_policy, :type => :descriptor_policy
+    attribute :marketplace_fixed_fee, :type => :amount
+    attribute :marketplace_variable_fee
+    attribute :recipient_token_id
+    attribute :sender_description
+    attribute :sender_token_id # required
+    attribute :transaction_amount, :type => :amount # required
+    attribute :transaction_timeout_in_mins
+
+    class Response < BaseResponse #:nodoc:
+      attribute :transaction_id
+      attribute :transaction_status, :enumeration => :transaction_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/refund.rb

@@ -0,0 +1,14 @@
+module AmazonFlexPay::API #:nodoc:
+  class Refund < Base #:nodoc:
+    attribute :caller_description
+    attribute :caller_reference # required
+    attribute :refund_amount, :type => :amount
+    attribute :transaction_id # required
+    attribute :marketplace_refund_policy, :enumeration => :marketplace_refund_policy
+
+    class Response < BaseResponse #:nodoc:
+      attribute :transaction_id
+      attribute :transaction_status, :enumeration => :transaction_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/reserve.rb

@@ -0,0 +1,20 @@
+module AmazonFlexPay::API #:nodoc:
+  class Reserve < Base #:nodoc:
+    attribute :caller_description
+    attribute :caller_reference # required
+    attribute :charge_fee_to, :enumeration => :charge_fee_to
+    attribute :descriptor_policy, :type => :descriptor_policy
+    attribute :marketplace_fixed_fee, :type => :amount
+    attribute :marketplace_variable_fee
+    attribute :recipient_token_id
+    attribute :sender_description
+    attribute :sender_token_id # required
+    attribute :transaction_amount, :type => :amount # required
+    attribute :transaction_timeout_in_mins
+
+    class Response < BaseResponse #:nodoc:
+      attribute :transaction_id
+      attribute :transaction_status, :enumeration => :transaction_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/settle.rb

@@ -0,0 +1,11 @@
+module AmazonFlexPay::API #:nodoc:
+  class Settle < Base #:nodoc:
+    attribute :reserve_transaction_id
+    attribute :transaction_amount, :type => :amount
+
+    class Response < BaseResponse #:nodoc:
+      attribute :transaction_id
+      attribute :transaction_status, :enumeration => :transaction_status
+    end
+  end
+end

data/lib/amazon_flex_pay/api/verify_signature.rb

@@ -0,0 +1,14 @@
+module AmazonFlexPay::API #:nodoc:
+  class VerifySignature < Base #:nodoc:
+    attribute :url_end_point
+    attribute :http_parameters
+
+    class Response < BaseResponse #:nodoc:
+      attribute :verification_status
+
+      def verified?
+        verification_status == 'Success'
+      end
+    end
+  end
+end

data/lib/amazon_flex_pay/api.rb

@@ -0,0 +1,162 @@
+# load all api classes
+require 'amazon_flex_pay/api/base'
+Dir[File.dirname(__FILE__) + '/api/*'].each do |p| require "amazon_flex_pay/api/#{File.basename(p)}" end
+
+module AmazonFlexPay
+  class << self
+    # Cancels a transaction.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/Cancel.html
+    def cancel(transaction_id, options = {})
+      API::Cancel.new(options.merge(:transaction_id => transaction_id)).submit
+    end
+
+    # Cancels a token.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/CancelToken.html
+    def cancel_token(token_id, options = {})
+      API::CancelToken.new(options.merge(:token_id => token_id)).submit
+    end
+
+    # Searches through transactions on your account. Helpful if you want to compare vs your own records,
+    # or print an admin report.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAccountManagementGuide/GetAccountActivity.html
+    def get_account_activity(start_date, end_date, options = {})
+      API::GetAccountActivity.new(options.merge(:start_date => start_date, :end_date => end_date)).submit
+    end
+
+    # Gets your Amazon Payments account balance.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAccountManagementGuide/GetAccountBalance.html
+    def get_account_balance
+      API::GetAccountBalance.new.submit
+    end
+
+    # Returns the status of a recipient's Amazon account. This is a high-level status indicating whether
+    # the recipient can receive up to $10k per month (VerificationComplete) or has no receiving limitations
+    # at all (VerificationCompleteNoLimits).
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/GetRecipientVerificationStatus.html
+    def get_recipient_verification_status(recipient_token_id)
+      API::GetRecipientVerificationStatus.new(:recipient_token_id => recipient_token_id).submit
+    end
+
+    # Returns information about a token's state from a caller reference.
+    #
+    # This is the closest thing that Amazon's API has to getting the status of a pipeline. Provide the caller
+    # reference for your pipeline (you are saving caller references, right?), and if this returns a token you
+    # can assume the pipeline finished successfully.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/GetTokensByCaller.html
+    def get_token_by_caller_reference(ref)
+      API::GetTokenByCaller.new(:caller_reference => ref).submit
+    end
+
+    # Returns information about a token's state from a token id.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/GetTokensByCaller.html
+    def get_token_by_id(id)
+      API::GetTokenByCaller.new(:token_id => id).submit
+    end
+
+    # Returns information about how much of the token has been used, and what remains.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAccountManagementGuide/GetTokenUsage.html
+    def get_token_usage(id)
+      API::GetTokenUsage.new(:token_id => id).submit
+    end
+
+    # Returns all of your tokens. Note that when you send someone through a recipient pipeline, that registers
+    # a recipient token on _their_ account, not yours. And when you send someone through a single use pipeline,
+    # that registers a sender token on _their_account, not yours.
+    #
+    # So basically this will only return recipient tokens where _you_ are the recipient, or sender tokens where
+    # _you_ are the sender.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAccountManagementGuide/GetTokens.html
+    def get_tokens(options = {})
+      API::GetTokens.new(options).submit
+    end
+
+    # Returns all of Amazon's details about a transaction, such as its status and when it began and finished
+    # processing.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAccountManagementGuide/GetTransaction.html
+    def get_transaction(id)
+      API::GetTransaction.new(:transaction_id => id).submit
+    end
+
+    # Returns the current status of the transaction. Note that this information is also available from
+    # <tt>get_transaction</tt>.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAccountManagementGuide/GetTransactionStatus.html
+    def get_transaction_status(id)
+      API::GetTransactionStatus.new(:transaction_id => id).submit
+    end
+
+    # Begins a Pay request for a sender token. If you are not also the recipient (this is a three-party marketplace
+    # transaction) then you must also specify the recipient token.
+    #
+    # Sign up for Instant Payment Notifications to be told when this has finished.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/Pay.html
+    def pay(value, currency, sender_token_id, caller_reference, options = {})
+      API::Pay.new(options.merge(
+        :transaction_amount => {:value => value, :currency_code => currency},
+        :sender_token_id => sender_token_id,
+        :caller_reference => caller_reference
+      )).submit
+    end
+
+    # Begins a Reserve request for the sender token. Very similar to <tt>pay</tt>.
+    #
+    # Sign up for Instant Payment Notifications to be told when this has finished.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/Reserve.html
+    def reserve(value, currency, sender_token_id, caller_reference, options = {})
+      API::Reserve.new(options.merge(
+        :transaction_amount => {:value => value, :currency_code => currency},
+        :sender_token_id => sender_token_id,
+        :caller_reference => caller_reference
+      )).submit
+    end
+
+    # Refunds a transaction. By default it will refund the entire transaction, but you can
+    # provide an amount for partial refunds.
+    #
+    # Sign up for Instant Payment Notifications to be told when this has finished.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/Refund.html
+    def refund(transaction_id, caller_reference, options = {})
+      API::Refund.new(options.merge(:transaction_id => transaction_id, :caller_reference => caller_reference)).submit
+    end
+
+    # If you have a Reserve transaction, use this to Settle (capture) it.
+    #
+    # Sign up for Instant Payment Notifications to be told when this has finished.
+    #
+    # See http://docs.amazonwebservices.com/AmazonFPS/latest/FPSAdvancedGuide/Settle.html
+    def settle(transaction_id, options = {})
+      API::Settle.new(options.merge(:reserve_transaction_id => transaction_id)).submit
+    end
+
+    # This is how you verify IPNs and pipeline responses.
+    # Pass the entire request object.
+    def verify_request(request)
+      verify_signature(
+        # url without query string
+        request.protocol + request.host_with_port + request.path,
+        # raw parameters
+        request.get? ? request.query_string : request.raw_post
+      )
+    end
+
+    # Verifies the signature embedded in the params string for the given url.
+    #
+    # Please use <tt>verify_request</tt> instead to make sure the URL and params remain properly formatted.
+    def verify_signature(url, params)
+      API::VerifySignature.new(:url_end_point => url, :http_parameters => params).submit
+    end
+  end
+end