simplepay-rails4 0.4.0

data/lib/simplepay/services/donation.rb

@@ -0,0 +1,90 @@
+module Simplepay
+  module Services
+  
+    ##
+    # The Amazon Simple Pay Donation service is used to facilitate the collection 
+    # of donations to your organization, or another's organization via the 
+    # marketplace functionality.  When used through the marketplace functionality,
+    # you may charge a commission fee for brokering the exchange.
+    # 
+    # Note that donation recipients must accept your marketplace fee policy before
+    # the payment buttons for their donations may be generated.   This can be 
+    # accomplished using the +MarketplacePolicy+ service with the form helper 
+    # (see examples).
+    # 
+    # === Simple Pay Donation Fields
+    # 
+    # ==== Required Fields
+    # 
+    # The following attributes are required when generating a Simple Pay Donation
+    # form (in addition to those listed in +SimplePay::Service+):
+    # 
+    # amount:: The dollar value you'd like to collect
+    # 
+    # ==== Optional Fields
+    # 
+    # immediate_return:: Immediately returns the customer to your +return_url+ directly after payment.
+    # ipn_url:: Fully-qualified URL to which Amazon will POST instant payment notifications.
+    # process_immediately:: Instructs Amazon to immediately process the payment.
+    # reference_id:: A custom string your can set to identify this transaction, it will be returned with the IPNs and other returned data.
+    # return_url:: Fully-qualified URL for where to send your customer following payment.
+    # 
+    # ===== Marketplace Fields
+    # 
+    # recipient_email:: The email address of the donation recipient (important and must be correct)
+    # fixed_marketplace_fee::  The fixed marketplace fee to add to each transaction
+    # variable_marketplace_fee:: The variable marketplace fee to add to each transaction
+    # 
+    # === Example
+    # 
+    #     (in your view, sellers need to accept the marketplace fee policy using the form helper)
+    #
+    #     <%= simplepay_form_for(:marketplace_policy, {
+    #       :max_fixed_fee    => 10.00,
+    #       :max_variable_fee => 5,
+    #       :return_url       => 'http://yourservice.com'
+    #     }) %>
+    #
+    #     (in your view, payment form generated for end users using the form helper)
+    #     
+    #     <%= simplepay_form_for(:donation, {
+    #       :amount                   => 34.95,
+    #       :description              => "Mutual profit!",
+    #       :recipient_email          => 'seller@gmail.com',
+    #       :fixed_marketplace_fee    => 10.00,
+    #       :variable_marketplace_fee => 5
+    #     }) %>
+    # 
+    class Donation < Service
+
+      required_field :access_key
+      required_field :signature
+      required_field :signature_method, :value => 'HmacSHA256'
+      required_field :signature_version, :value => '2'
+      
+
+      required_field :description
+      required_field :amount,               :class  => Support::Amount
+      required_field :cobranding_style,     :value  => 'logo'
+      required_field :donation_widget,      :as     => :is_donation_widget,
+                                            :value  => '1'
+      
+      field :reference_id
+      field :immediate_return,              :class  => Support::Boolean
+      field :collect_shipping_address,      :class  => Support::Boolean
+      field :process_immediately,           :class  => Support::Boolean,
+                                            :as     => :process_immediate
+
+      field :return_url
+      field :ipn_url
+      field :abandon_url
+      
+      # Marketplace inputs (recipient email required when using)
+      field :fixed_marketplace_fee,         :class  => Support::Amount
+      field :variable_marketplace_fee
+      field :recipient_email
+      
+    end
+    
+  end
+end

data/lib/simplepay/services/marketplace.rb

@@ -0,0 +1,88 @@
+module Simplepay
+  module Services
+  
+    ##
+    # The Amazon Simple Pay Marketplace service is used to facilitate payments for others.
+    # Use it to charge a commission fee for brokering the exchange between buyers and sellers.
+    #
+    # Note that sellers must accept your marketplace fee policy before the payment buttons
+    # for their products can be generated. This can be accomplished using the +MarketplacePolicy+
+    # service with the form helper (see examples).
+    # 
+    # === Simple Pay Marketplace Fields
+    # 
+    # ==== Required Fields
+    # 
+    # The following attributes are required when creating a Simple Pay 
+    # Marketplace form (in addition to those listed in +Simplepay::Service+):
+    # 
+    # amount:: The dollar value you'd like to collect.
+    # description:: A summary of the reason for the payment, this is displayed to your customer during checkout.
+    # recipient_email:: The e-mail address of the seller (important and must be correct).
+    # fixed_marketplace_fee:: The fixed marketplace fee to add to each transaction.
+    # variable_marketplace_fee:: The variable percentage fee to add to each transaction.
+    # 
+    # ==== Optional Fields
+    # 
+    # abandon_url:: The fully-qualified URL to send your custom if they cancel during payment.
+    # cobranding_style:: Defines the type of cobranding to use during the checkout process.
+    # collect_shipping_address:: Tells Amazon whether or not to ask for shipping address and contact information.
+    # immediate_return:: Immediately returns the customer to your +return_url+ directly after payment.
+    # ipn_url:: Fully-qualified URL to which Amazon will POST instant payment notifications.
+    # process_immediately:: Instructs Amazon to immediately process the payment.
+    # reference_id:: A custom string your can set to identify this transaction, it will be returned with the IPNs and other returned data.
+    # return_url:: Fully-qualified URL for where to send your customer following payment.
+    # 
+    # === Example
+    # 
+    #     (in your view, sellers need to accept the marketplace fee policy using the form helper)
+    #
+    #     <%= simplepay_form_for(:marketplace_policy, {
+    #       :max_fixed_fee    => 10.00,
+    #       :max_variable_fee => 5,
+    #       :return_url       => 'http://yourservice.com'
+    #     }) %>
+    #
+    #     (in your view, payment form generated for end users using the form helper)
+    #     
+    #     <%= simplepay_form_for(:standard, {
+    #       :amount                   => 34.95,
+    #       :description              => "Mutual profit!",
+    #       :recipient_email          => 'seller@gmail.com',
+    #       :fixed_marketplace_fee    => 10.00,
+    #       :variable_marketplace_fee => 5
+    #     }) %>
+    # 
+    class Marketplace < Service
+      
+      required_field :access_key
+      required_field :signature
+      required_field :signature_method, :value => 'HmacSHA256'
+      required_field :signature_version, :value => '2'
+      
+      
+      required_field :description
+      required_field :amount,                   :class  => Support::Amount
+      required_field :fixed_marketplace_fee,    :class  => Support::Amount
+      required_field :variable_marketplace_fee
+      required_field :cobranding_style,         :value  => 'logo'
+      required_field :recipient_email
+      
+      field :reference_id
+      field :immediate_return,                  :class  => Support::Boolean
+      field :collect_shipping_address,          :class  => Support::Boolean
+      field :process_immediately,               :class  => Support::Boolean,
+                                                :as     => :process_immediate
+
+      field :return_url
+      field :ipn_url
+      field :abandon_url
+      
+      # These fields are not currently utilized by the service
+      field :donation_widget,               :as     => :is_donation_widget,
+                                            :value  => '0'
+      
+    end
+    
+  end
+end

data/lib/simplepay/services/marketplace_policy.rb

@@ -0,0 +1,53 @@
+module Simplepay
+  module Services
+  
+    ##
+    # The Amazon Simple Pay Marketplace Policy service is used to allow sellers to acknowledge marketplace policy fees.
+    # Only once a set policy has been agreed to will marketplace transactions be able to proceed.
+    #
+    # === Simple Pay Marketplace Policy Fields
+    # 
+    # ==== Required Fields
+    # 
+    # The following attributes are required when creating a Simple Pay Marketplace policy fee acceptance form
+    # (in addition to those listed in +Simplepay::Service+):
+    # 
+    # max_fixed_fee:: The maximum fixed fee that will be appended to transactions.
+    # max_variable_fee:: The maximum variable fee (%) that will be calculated and added to transactions.
+    # return_url:: Fully-qualified URL for where to send they buyer following payment.
+    # reference_id:: A custom string used to identify this transaction, it will be returned with return data.
+    #
+    # === Example
+    # 
+    #     (in your view, using the form helper)
+    #
+    #     <%= simplepay_form_for(:marketplace_policy, {
+    #       :max_fixed_fee => 10.00,
+    #       :max_variable_fee => 5,
+    #       :return_url => 'http://yourservice.com',
+    #       :reference_id => '123456789'
+    #     }) %>
+    #
+    class MarketplacePolicy < Service
+      
+      required_field :access_key, :as => :caller_key
+      required_field :signature,  :as => :signature
+      required_field :signature_method, :value => 'HmacSHA256'
+      required_field :signature_version, :value => '2'
+      
+      
+      required_field :max_fixed_fee
+      required_field :max_variable_fee
+      required_field :return_url
+
+      required_field :reference_id,          :as => :caller_reference
+      required_field :collect_email_address, :value => 'True'
+      required_field :pipeline_name,         :value => 'Recipient'
+
+      # These fields are not currently utilized by the service
+      required_field :recipient_pays_fee,    :value => 'True'
+      
+    end
+    
+  end
+end

data/lib/simplepay/services/standard.rb

@@ -0,0 +1,58 @@
+module Simplepay
+  module Services
+  
+    ##
+    # The Amazon Simple Pay Standard service is used for one-time payments.
+    # 
+    # === Simple Pay Standard Fields
+    # 
+    # ==== Required Fields
+    # 
+    # The following attributes are required when creating a Simple Pay 
+    # Standard form (in addition to those listed in +Simplepay::Service+):
+    # 
+    # amount:: The dollar value you'd like to collect.
+    # description:: A summary of the reason for the payment, this is displayed to your customer during checkout.
+    # 
+    # ==== Optional Fields
+    # 
+    # abandon_url:: The fully-qualified URL to send your custom if they cancel during payment.
+    # cobranding_style:: Defines the type of cobranding to use during the checkout process.
+    # collect_shipping_address:: Tells Amazon whether or not to ask for shipping address and contact information.
+    # immediate_return:: Immediately returns the customer to your +return_url+ directly after payment.
+    # ipn_url:: Fully-qualified URL to which Amazon will POST instant payment notifications.
+    # process_immediately:: Instructs Amazon to immediately process the payment.
+    # reference_id:: A custom string your can set to identify this transaction, it will be returned with the IPNs and other returned data.
+    # return_url:: Fully-qualified URL for where to send your customer following payment.
+    # 
+    # === Example
+    # 
+    #     (in your view, using the form helper)
+    #     
+    #     <%= simplepay_form_for(:standard, {
+    #       :amount       => 34.95,
+    #       :description  => "I want my money NOW!"
+    #     }) %>
+    # 
+    class Standard < Service
+
+      required_field :access_key
+      required_field :amount
+      required_field :description
+      required_field :signature
+      required_field :signature_method, :value => 'HmacSHA256'
+      required_field :signature_version, :value => '2'
+
+      field :abandon_url
+      field :cobranding_style, :value => 'logo'
+      field :collect_shipping_address, :class => Support::Boolean
+      field :immediate_return, :class => Support::Boolean
+      field :ipn_url
+      field :process_immediate, :class => Support::Boolean
+      field :reference_id
+      field :return_url
+      
+    end
+
+  end
+end

data/lib/simplepay/services/subscription.rb

@@ -0,0 +1,95 @@
+module Simplepay
+  module Services
+  
+    ##
+    # A Simple Pay Subscription is an automatically recurring payment which is
+    # charged every interval (Simplepay::Support::BillingFrequency) until
+    # a limiting period (Simplepay::Support::SubscriptionPeriod) is met.
+    # 
+    # With this type of payment, for example, you may charge your customer:
+    # 
+    #     $10.00 every 3 days until 9 days.
+    #     $9.95 every 1 month until forever.
+    # 
+    # === Simple Pay Subscription Fields
+    # 
+    # === Required Fields
+    # 
+    # The following attributes are required when creating a Simple Pay 
+    # Subscription form (in addition to those listed in +Simplepay::Service+):
+    # 
+    # amount:: The dollar value you'd like to collect.
+    # description:: A summary of the reason for the payment, this is displayed to your customer during checkout.
+    # recurring_frequency:: Defines how often to charge your customer (ex. "1 month")
+    # 
+    # ==== Optional Fields
+    # 
+    # abandon_url:: The fully-qualified URL to send your custom if they cancel during payment.
+    # auto_renew:: Instructs Amazon to automatically renew the subscription after the +subscription_period+ ends.
+    # cobranding_style:: Defines the type of cobranding to use during the checkout process.
+    # collect_shipping_address:: Tells Amazon whether or not to ask for shipping address and contact information.
+    # immediate_return:: Immediately returns the customer to your +return_url+ directly after payment.
+    # ipn_url:: Fully-qualified URL to which Amazon will POST instant payment notifications.
+    # process_immediately:: Instructs Amazon to immediately process the payment.
+    # reference_id:: A custom string your can set to identify this transaction, it will be returned with the IPNs and other returned data.
+    # return_url:: Fully-qualified URL for where to send your customer following payment.
+    # start_date:: Instructs Amazon with the timestamp to start the recurring subscription charges.
+    # subscription_period:: Defines the expiration window of the subscription (i.e. charge +amount+ every +recurring_frequency+ for "36 months")
+    # 
+    # === Example
+    # 
+    #     (in your view, using the form helper)
+    #     
+    #     <%= simplepay_form_for(:subscription, {
+    #           :amount               => 12.95,
+    #           :recurring_frequency  => "1 year",
+    #           :description          => "My.Url Yearly Dues"
+    #     }) %>
+    # 
+    class Subscription < Service
+      
+      required_field :access_key
+      required_field :signature
+      required_field :signature_method,     :value => 'HmacSHA256'
+      required_field :signature_version,    :value => '2'
+      
+      
+      
+      required_field :recurring_frequency,  :class  => Support::BillingFrequency
+      required_field :description
+      required_field :amount,               :class  => Support::Amount
+      required_field :cobranding_style,     :value  => 'logo'
+      
+      field :subscription_period,           :class  => Support::SubscriptionPeriod
+      field :reference_id
+      field :immediate_return,              :class  => Support::Boolean
+
+      field :start_date,                    :class  => Support::Epoch,
+                                            :as     => :recurring_start_date
+      
+      field :collect_shipping_address,      :class  => Support::Boolean      
+      
+      field :process_immediately,           :class  => Support::Boolean,
+                                            :as     => :process_immediate
+
+      field :auto_renew,                    :class  => Support::Boolean,
+                                            :as     => :is_auto_renewal
+      
+      field :return_url
+      field :ipn_url
+      field :abandon_url
+      
+      # Used for trial periods
+      field :promotion_amount,              :class  => Support::Amount
+      field :number_of_promotion_transactions, :as  => :no_of_promotion_transactions
+      
+      # These fields are not currently utilized by the service
+      field :variable_marketplace_fee,      :value  => ''
+      field :donation_widget,               :as     => :is_donation_widget,
+                                            :value  => '0'
+      field :fixed_marketplace_fee,         :value  => ''
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/amount.rb

@@ -0,0 +1,55 @@
+require 'bigdecimal'
+
+module Simplepay
+  module Support
+    
+    ##
+    # Amazon often represents dollar values as a combination of a value and a 
+    # currency.  In several types of requests, the combination is required for
+    # communication.
+    # 
+    # At the present time, Amazon only uses USD.
+    # 
+    class Amount
+      
+      attr_reader :amount
+      attr_reader :currency
+      
+      def initialize(amount, currency = Simplepay::Currency::USD)
+        self.amount   = amount
+        self.currency = currency
+      end
+      
+      
+      ##
+      # Sets the amount of the currency value, such as "1" for 1 USD.  This
+      # amount cannot be negative.
+      # 
+      def amount=(amount)
+        raise(ArgumentError, "Amount cannot be nil") unless amount
+        raise(ArgumentError, "Amount cannot be negative") if amount < 0
+        @amount = BigDecimal.new(amount.to_s)
+      end
+      
+      ##
+      # Sets the type of currency to use in the transaction.  The parameter
+      # can either be a known currency code (see Simplepay::Currency) or a
+      # custom Simplepay::Currency::Currency instance.
+      # 
+      def currency=(currency)
+        raise(ArgumentError, "Invalid currency, expected Simplepay::Support::Currency or currency code string.") unless currency.kind_of?(Simplepay::Support::Currency) || currency.kind_of?(String)
+        if currency.kind_of?(String)
+          currency =  Simplepay::Currencies.detect { |c| c.code == currency } ||
+                      raise(ArgumentError, "Invalid currency, '#{currency}'. Must be one of: #{Simplepay::Currencies.join(', ')}")
+        end
+        @currency = currency
+      end
+      
+      def to_s
+        "#{currency.code} #{currency.format % amount}"
+      end
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/billing_frequency.rb

@@ -0,0 +1,14 @@
+require 'simplepay/support/interval'
+
+module Simplepay
+  module Support
+    
+    class BillingFrequency < Interval
+      ALLOWED_INTERVALS       = Simplepay::Intervals
+      
+      # Limited to 2 digits.
+      ALLOWED_QUANTITY_RANGE  = (1...100)
+    end
+    
+  end
+end

data/lib/simplepay/support/boolean.rb

@@ -0,0 +1,28 @@
+module Simplepay
+  module Support
+    
+    ##
+    # Acts as a delegator for Simplepay::Support::Field <tt>:class</tt>.
+    # 
+    # This class acts as a helper for sending boolean values to Amazon.  In
+    # their forms, booleans are expected to be either "0" or "1", for false or
+    # true, respectively.
+    # 
+    class Boolean
+      
+      def initialize(value)
+        @value = value
+      end
+      
+      ##
+      # Returns "1" if the boolean is true, "0" otherwise.
+      # 
+      def to_s
+        return '' if @value.nil?
+        @value ? Simplepay::Boolean::True : Simplepay::Boolean::False
+      end
+      
+    end
+    
+  end
+end

data/lib/simplepay/support/currency.rb

@@ -0,0 +1,21 @@
+module Simplepay
+  module Support
+    
+    ##
+    # Contains a name, recognized code, and basic formatting for a particular
+    # international monetary currency.
+    # 
+    class Currency
+      attr_reader :name, :code, :format
+      
+      def initialize(name, code, format)
+        @name, @code, @format = name, code, format
+      end
+      
+      def to_s
+        "#{code}"
+      end
+    end
+    
+  end
+end

data/lib/simplepay/support/epoch.rb

@@ -0,0 +1,39 @@
+module Simplepay
+  module Support
+    
+    ##
+    # Acts as a Simplepay::Support::Field <tt>:class</tt> delegator.
+    # 
+    # This class provides a means to have Time values returned as an integer
+    # since epoch (January 1, 1970).
+    # 
+    class Epoch
+      
+      def initialize(time)
+        @value = time ? parse(time) : Time.now
+      end
+      
+      ##
+      # Returns a String of Integers, representing seconds since epoch.
+      # 
+      def to_s
+        @value.to_i.to_s
+      end
+      
+      
+      private
+      
+      
+      def parse(time)
+        case time
+        when Time, Date, DateTime
+          time
+        else
+          Time.parse(time)
+        end
+      end
+      
+    end
+    
+  end
+end