spook_and_pay 0.2.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 91f5461e5cc5382b312c2e0d9c7a1ddf576a14e2
+  data.tar.gz: 78f8ef0364586a4f8d22283b8ccbf79925068d66
+SHA512:
+  metadata.gz: 6061677abfdec2995ad03ef6de15d48308f2685f2cd91cbfff58f4a7fc19ef04a2a1adbf626efa3df1af88d951855661af4f49a24d634d21102965376ea479ea
+  data.tar.gz: 4b34cc7037809402145583ee019751230ebd3b4bbe04903d9794486c92530236a80a9d2e95c2318c44cdbaad565dd4b5b7e7da1ff56633c2ae8cc2e22d961fb9

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright © 2013 Spook and Puff
+
+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.md

@@ -0,0 +1,52 @@
+# Spook and Pay
+
+A small library which wraps payment and credit card vaulting providers that support transparent redirect.
+
+The aim is to make switching between providers easy or even support multiple providers within the same application.
+
+Initially this library will support Braintree and SpreedlyCore, with more added as needed.
+
+## Alpha Warning
+
+This library is currently in-flight; you're welcome to hack on it, but it's unlikely to be usable.
+
+## Usage
+
+All actions are run via an instance of a `SpookAndPay::Providers::Base` subclass. Configuration is dependent on the particular provider you are using. For example, here is how you would configure Braintree:
+
+```
+provider = SpookAndPay::Providers::Braintree.new(
+  :development,
+  :merchant_id => "...",
+  :public_key => "...",
+  :secret_key => "...",
+)
+```
+
+You can then use the provider instance to interrogate Braintree and to perform actions.
+
+```
+transaction = provider.transaction('...')
+transaction.status # => :settling
+transaction.can_refund? # => false
+transaction.can_void? # => true
+
+result = transaction.void!
+result.successful? # => true
+```
+
+### Workflow
+
+Currently SpookAndPay does not support the direct submission of payment details — credit card numbers etc — but instead relies on payment providers which feature transparent redirect/post for submission of details.
+
+Direct submission of details will _never_ be supported, since it raises the specter of PCI-compliance.
+
+### Transparent Redirect
+
+TBD
+
+## Todo
+
+* Normalise transaction statuses across providers
+* Normalise errors across providers
+* Implement actions on CreditCard e.g. update, delete

data/lib/spook_and_pay.rb

@@ -0,0 +1,19 @@
+module SpookAndPay
+
+end
+
+require 'cgi'
+require 'digest'
+require 'openssl'
+require 'net/http'
+
+require 'braintree'
+
+require 'spook_and_pay/submission_error'
+require 'spook_and_pay/missing_value_error'
+require 'spook_and_pay/erroring_reader'
+require 'spook_and_pay/credit_card'
+require 'spook_and_pay/result'
+require 'spook_and_pay/transaction'
+require 'spook_and_pay/adapters'
+require 'spook_and_pay/providers'

data/lib/spook_and_pay/adapters.rb

@@ -0,0 +1 @@
+require 'spook_and_pay/adapters/braintree'

data/lib/spook_and_pay/adapters/braintree.rb

@@ -0,0 +1,109 @@
+module SpookAndPay
+  module Adapters
+    # A class which wraps the existing Braintree client and lets us use it in
+    # a sane way. Specifically, it lets us have multiple sets of credentials,
+    # whereas the default behaviour in the lib is to have them global
+    class Braintree
+      # Accessor for the Braintree::Gateway instance. In general should not be
+      # accessed externally, but is put here for debugging etc.
+      attr_reader :gateway
+
+      # Constructs an instance of the Braintree gateway which it then acts as 
+      # a proxy to.
+      #
+      # @param [:development, :test, :production] environment
+      # @param String merchant_id
+      # @param String public_key
+      # @param String private_key
+      def initialize(environment, merchant_id, public_key, private_key)
+        _environment = case environment
+        when :production then :production
+        when :development, :test then :sandbox
+        end
+
+        config = ::Braintree::Configuration.new(
+          :custom_user_agent  => ::Braintree::Configuration.instance_variable_get(:@custom_user_agent),
+          :endpoint           => ::Braintree::Configuration.instance_variable_get(:@endpoint),
+          :environment        => _environment,
+          :logger             => ::Braintree::Configuration.logger,
+          :merchant_id        => merchant_id,
+          :private_key        => private_key,
+          :public_key         => public_key
+        )
+
+        @gateway = ::Braintree::Gateway.new(config)
+      end
+
+      # Looks up the transaction from Braintree.
+      #
+      # @param String id
+      # @return [nil, Braintree::Transaction]
+      def transaction(id)
+        gateway.transaction.find(id)
+      end
+
+      # Looks up credit card details from Braintree. It squashes NotFoundError
+      # and just returns nil instead.
+      #
+      # @param String id
+      # @return [Braintree::CreditCard, nil]
+      def credit_card(id)
+        begin
+          gateway.credit_card.find(id)
+        rescue ::Braintree::NotFoundError => e
+          nil
+        end
+      end
+
+      # Generates the hash and query string that needs to be embedded inside 
+      # of a form in order to interact with Braintree's transparent redirect.
+      #
+      # @param Hash data
+      #
+      # @return String
+      def transaction_data(data)
+        gateway.transparent_redirect.transaction_data(data)
+      end
+
+      # Used to confirm the submission of purchase or authorize transactions 
+      # via transparent redirect.
+      #
+      # @param String query_string
+      # @return [Braintree::SuccessfulResult, Braintree::ErrorResult]
+      def confirm(query_string)
+        gateway.transparent_redirect.confirm(query_string)
+      end
+
+      # Captures the funds in an authorized transaction.
+      #
+      # @param String id
+      # @return [Braintree::SuccessfulResult, Braintree::ErrorResult]
+      def capture(id)
+        gateway.transaction.submit_for_settlement(id)
+      end
+
+      # Refunds the funds in a settled transaction.
+      #
+      # @param String id
+      # @return [Braintree::SuccessfulResult, Braintree::ErrorResult]
+      def refund(id)
+        gateway.transaction.refund(id)
+      end
+
+      # Voids a transaction.
+      #
+      # @param String id
+      # @return [Braintree::SuccessfulResult, Braintree::ErrorResult]
+      def void(id)
+        gateway.transaction.void(id)
+      end
+
+      # The target URL for transparent redirects.
+      #
+      # @return String
+      def transparent_redirect_url
+        gateway.transparent_redirect.url
+      end
+    end
+  end
+end

data/lib/spook_and_pay/credit_card.rb

@@ -0,0 +1,96 @@
+module SpookAndPay
+  # A simple, generic class which wraps the card details retrieved from a
+  # provider. This class is entirely read only, since it is only used to
+  # as part of inspecting a payment or handling errors.
+  class CreditCard
+    # This module adds the ::attr_erroring_reader to this class
+    extend SpookAndPay::ErroringReader
+
+    # The basic attributes of the credit card.
+    attr_reader :provider, :id
+
+    # The fields required for a credit card
+    FIELDS = [:number, :expiration_month, :expiration_year, :cvv, :card_type, :name, :valid, :expired].freeze
+
+    # Define readers for all the fields
+    attr_reader *FIELDS
+
+    # Define a subset of the readers as erroring
+    attr_erroring_reader :valid, :expired
+
+    # Construct a new credit card using the ID from the provider and a hash
+    # containing the values of the card.
+    #
+    # @param SpookAndPay::Providers::Base provider
+    # @param [Numeric, String] id
+    # @param Hash vals
+    # @option vals String :number
+    # @option vals [String, Numeric] :expiration_month
+    # @option vals [String, Numeric] :expiration_year
+    # @option vals [String, Numeric] :cvv
+    # @option vals String :card_type
+    # @option vals String :name
+    # @option vals [true, false] :expired
+    # @option vals [true, false] :valid
+    def initialize(provider, id, vals)
+      @provider = provider
+      @id = id
+      FIELDS.each {|f| instance_variable_set(:"@#{f}", vals[f]) if vals.has_key?(f)}
+    end
+
+    # A getter which takes the card number stored and generates a nice masked 
+    # version. It also handles the case where the number isn't available and 
+    # just returns nil instead.
+    #
+    # @return String
+    def number
+      if @number.nil? or @number.empty?
+        nil
+      else
+        case card_type
+        when 'american_express' then "XXXX-XXXXXX-#{@number}"
+        else "XXXX-XXXX-XXXX-#{@number}"
+        end
+      end
+    end
+
+    # Authorizes a payment of the specified amount. This generates a new
+    # transaction that must be later settled.
+    #
+    # @param [String, Numeric] amount
+    # @return SpookAndPay::Result
+    def authorize!(amount)
+      provider.authorize_via_credit_card(self, amount)
+    end
+
+    # Generates a payment of the specified amount.
+    #
+    # @param [String, Numeric] amount
+    # @return SpookAndPay::Result
+    def purchase!(amount)
+      provider.purchase_via_credit_card(self, amount)
+    end
+
+    # Deletes the credit card from the provider's vault.
+    #
+    # @return [true, false]
+    def delete!
+      provider.delete_credit_card(self)
+    end
+
+    # Indicates if the card details are valid.
+    #
+    # @return [true, false]
+    def valid?
+      valid
+    end
+
+    # Indicates if the card is expired. This is not calculated, but instead
+    # determined by the provider.
+    #
+    # @return [true, false]
+    def expired?
+      expired
+    end
+  end
+end

data/lib/spook_and_pay/erroring_reader.rb

@@ -0,0 +1,23 @@
+module SpookAndPay
+  module ErroringReader
+    # Defines a set of readers which will error if the underlying ivar is nil.
+    # It is intended to be used with a sub-set of readers which are important,
+    # but which may be nil. This is preferable to returning nil, which is falsy
+    # and will screw up any predicates.
+    #
+    # @param Symbol ivars
+    # @return nil
+    def attr_erroring_reader(*ivars)
+      ivars.each do |i|
+        class_eval %{
+          def #{i}
+            raise MissingValueError.new(:#{i}, self) unless defined?(@#{i})
+            @#{i}
+          end
+        }
+      end
+
+      nil
+    end
+  end
+end

data/lib/spook_and_pay/missing_value_error.rb

@@ -0,0 +1,25 @@
+module SpookAndPay
+  # A simple error class used to capture situations where the user is 
+  # attampting to access a value, but it is not available. This is
+  # unfortunately necessary due to the way some providers do or do not
+  # return certain fields. Rather than allow comparison with nil values
+  # we throw this error.
+  class MissingValueError < StandardError
+    # When instancing this error, it needs to have enough information to point 
+    # the user to the source.
+    #
+    # @param [String, Symbol] field
+    # @param Class record
+    def initialize(field, record)
+      @field = field
+      @record = record
+    end
+
+    # Human readable error message.
+    #
+    # @return String
+    def to_s
+      "The field #{@field} is missing for #{@record.class}"
+    end
+  end
+end

data/lib/spook_and_pay/providers.rb

@@ -0,0 +1,2 @@
+require 'spook_and_pay/providers/base'
+require 'spook_and_pay/providers/braintree'

data/lib/spook_and_pay/providers/base.rb

@@ -0,0 +1,203 @@
+module SpookAndPay
+  module Providers
+    # The abstract class from which other Provider classes should inherit. This
+    # class is intended to behave more as a template than anything else. It 
+    # provides very little in the way of actual implementation.
+    #
+    # To implement a provider all of the public methods of this class — 
+    # excluding #initialize — must be implemented.
+    #
+    # Some features may not be supported by a provider, in which case the 
+    # `NotSupportedError` should be raised in lieu of a real implementation.
+    class Base
+      # A hash which maps between the fields for a credit card and the actual
+      # form field names required by the provider.
+      #
+      # It should be over-ridden per provider.
+      FORM_FIELD_NAMES = {}.freeze
+
+      # An error used when validating the contents of an options hash. Since
+      # many of the methods on the provider classes take additional arguments 
+      # as a Hash, it's important to make sure we give good errors when they 
+      # are missing.
+      class InvalidOptionsError < StandardError
+        def initialize(errors)
+          @errors = errors
+        end
+
+        def to_s
+          "You have missed, or provided invalid options"
+        end
+      end
+
+      # An error for indicating actions that are not supported by a particular
+      # provider. In general, it will be the Base subclasses that define thier
+      # own versions of the the method that throw this error.
+      class NotSupportedError < StandardError
+        def to_s
+          "This action is not supported by this provider."
+        end
+      end
+
+      # Basic attributes
+      attr_reader :environment, :config
+
+      # @param [:production, :development, :test] env
+      # @param Hash config
+      #
+      # @return nil
+      def initialize(env, config)
+        @environment = env
+        @config = config
+
+        nil
+      end
+
+      # Retrieves the payment method details from the provider's vault.
+      #
+      # @param String id
+      #
+      # @return [SpookAndPay::CreditCard, nil]
+      def credit_card(id)
+        raise NotImplementedError
+      end
+
+      # Retrieves a credit card from the provider based on the transaction
+      # or transaction id provided. Some providers may not support this action.
+      #
+      # @param [String, SpookAndPay::Transaction] transaction_or_id
+      # @return [SpookAndPay::CreditCard, nil]
+      def credit_card_from_transaction(transaction_or_id)
+        raise NotSupportedError
+      end
+
+      # Retrieves the transaction details from the provider's vault.
+      #
+      # @param String id
+      #
+      # @return [SpookAndPay::Transaction, nil]
+      def transaction(id)
+        raise NotImplementedError
+      end
+
+      # Returns a hash containing the details necessary for making a 
+      # submission. If you know what you're doing, you can use this directly, 
+      # but otherwise you should be using the form helpers.
+      #
+      # The details generated by this method are for submitting card details to
+      # the provider for storage. Billing etc has to be handled via a separate
+      # step after submission.
+      # 
+      # The arguments for this are specific to each provider implementation,
+      # but they all return a Hash with the same keys, like so:
+      #   {
+      #     :url => "...",
+      #     :hidden_fields => {...},
+      #     :field_names => {...}
+      #   }
+      # 
+      # Where :url is the target URL, :hidden_fields should be embedded in a 
+      # form as they are and :field_names provide the mapping between known 
+      # keys like :number and :cvv to the input names required by the provider.
+      def prepare_payment_submission(*args)
+        raise NotImplementedError
+      end
+
+      # Confirms the submission of payment details to the provider.
+      #
+      # The arguments for this method are specific to a provider.
+      def confirm_payment_submission(*args)
+        raise NotImplementedError
+      end
+
+      # Captures funds that have been pre-authorized.
+      #
+      # This should not be called directly. Instead, use the #capture! method
+      # provided by a Transaction instance.
+      #
+      # @param [SpookAndPay::Transaction, String] id
+      # @return SpookAndPay::Result
+      def capture_transaction(id)
+        raise NotImplementedError
+      end
+
+      # Refunds the amount of money captured in a transaction.
+      #
+      # This should not be called directly. Instead, use the #refund! method
+      # provided by a Transaction instance.
+      #
+      # @param [SpookAndPay::Transaction, String] id
+      # @return SpookAndPay::Result
+      def refund_transaction(id)
+        raise NotImplementedError
+      end
+
+      # Voids an authorization. 
+      #
+      # This should not be called directly. Instead, use the #void! method
+      # provided by a Transaction instance.
+      #
+      # @param [SpookAndPay::Transaction, String] id
+      # @return SpookAndPay::Result
+      # @api private
+      # @abstract Subclass to implement
+      def void_transaction(id)
+        raise NotImplementedError
+      end
+
+      # Authorizes a payment against a credit card
+      #
+      # This should not be called directly. Instead, use the #authorize! method
+      # provided by a CreditCard instance.
+      #
+      # @param [SpookAndPay::CreditCard, String] id
+      # @param [String, Numeric] amount
+      # @return SpookAndPay::Result
+      # @api private
+      # @abstract Subclass to implement
+      def authorize_via_credit_card(id, amount)
+        raise NotImplementedError
+      end
+
+      # Creates a purchase against a credit card.
+      #
+      # This should not be called directly. Instead, use the #purchase! method
+      # provided by a CreditCard instance.
+      #
+      # @param [SpookAndPay::CreditCard, String] id
+      # @param [String, Numeric] amount
+      # @return SpookAndPay::Result
+      # @api private
+      # @abstract Subclass to implement
+      def purchase_via_credit_card(id, amount)
+        raise NotImplementedError
+      end
+
+      # Removes payment details from the provider's vault.
+      #
+      # This should not be called directly. Instead, use the #delete! method
+      # provided by a CreditCard instance.
+      #
+      # @param [SpookAndPay::CreditCard, String] id
+      # @return SpookAndPay::Result
+      # @api private
+      # @abstract Subclass to implement
+      def delete_credit_card(id)
+        raise NotImplementedError
+      end
+
+      private
+
+      # Extracts a transaction ID from it's target.
+      #
+      # @param [SpookAndPay::Transaction, String]
+      # @return String
+      def transaction_id(id)
+        case id
+        when SpookAndPay::Transaction then id.id
+        else id
+        end
+      end
+    end
+  end
+end

data/lib/spook_and_pay/providers/braintree.rb

@@ -0,0 +1,277 @@
+module SpookAndPay
+  module Providers
+    class Braintree < Base
+      FORM_FIELD_NAMES = {
+        :name             => "transaction[credit_card][cardholder_name]",
+        :number           => "transaction[credit_card][number]",
+        :expiration_month => "transaction[credit_card][expiration_month]",
+        :expiration_year  => "transaction[credit_card][expiration_year]",
+        :cvv              => "transaction[credit_card][cvv]"
+      }.freeze
+
+      attr_reader :adapter
+
+      # @param Hash config
+      # @option config String :merchant_id
+      # @option config String :public_key
+      # @option config String :private_key
+      def initialize(env, config)
+        @adapter = SpookAndPay::Adapters::Braintree.new(
+          env, 
+          config[:merchant_id], 
+          config[:public_key],
+          config[:private_key]
+        )
+
+        super(env, config)
+      end
+
+      # Braintree specific version of this method. Can be used to either 
+      # authorize a payment — and capture it later — or submit a payment for 
+      # settlement immediately. This is done via the type param.
+      #
+      # Because Braintree accepts payment details and processes payment in a 
+      # single step, this method must also be provided with an amount.
+      #
+      # @param [:purchase, :authorize] type
+      # @param String redirect_url
+      # @param [String, Numeric] amount
+      # @param Hash opts
+      # @option opts [true, false] :vault
+      # @return Hash
+      def prepare_payment_submission(type, redirect_url, amount, opts = {})
+        payload = {
+          :transaction  => {:type => 'sale', :amount => amount},
+          :redirect_url => redirect_url
+        }
+
+        if opts[:vault]
+          (payload[:transaction][:options] ||= {})[:store_in_vault] = true
+        end
+
+        if type == :purchase
+          (payload[:transaction][:options] ||= {})[:submit_for_settlement] = true
+        end
+
+        {
+          :url            => adapter.transparent_redirect_url,
+          :hidden_fields  => {:tr_data => adapter.transaction_data(payload)},
+          :field_names    => self.class::FORM_FIELD_NAMES
+        }
+      end
+
+      # Confirms the submission of payment details to the provider.
+      #
+      # @param String query_string
+      #
+      # @return SpookAndPay::Result
+      def confirm_payment_submission(query_string)
+        result = adapter.confirm(query_string)
+
+        case result
+        when ::Braintree::SuccessfulResult
+          SpookAndPay::Result.new(
+            true, 
+            result,
+            :credit_card => extract_credit_card(result.transaction.credit_card_details, true, false), 
+            :transaction => extract_transaction(result.transaction)
+          )
+        when ::Braintree::ErrorResult
+          SpookAndPay::Result.new(
+            false,
+            result,
+            :credit_card => extract_credit_card(result.params[:transaction][:credit_card], false, false),
+            :transaction => extract_transaction(result.params[:transaction]),
+            :errors => extract_errors(result)
+          )
+        end
+      end
+
+      def credit_card(id)
+        result = adapter.credit_card(id)
+        extract_credit_card(result, true, false) if result
+      end
+
+      def credit_card_from_transaction(id)
+        _id = id.is_a?(String) ? id : id.id
+        result = adapter.transaction(_id)
+        extract_credit_card(result.credit_card_details, true, false)
+      end
+
+      def transaction(id)
+        result = adapter.transaction(id)
+        extract_transaction(result) if result
+      end
+
+      def capture_transaction(id)
+        result = adapter.capture(transaction_id(id))
+        generate_result(result)
+      end
+
+      def refund_transaction(id)
+        result = adapter.refund(transaction_id(id))
+        generate_result(result)
+      end
+
+      def void_transaction(id)
+        result = adapter.void(transaction_id(id))
+        generate_result(result)
+      end
+
+      private
+
+      # Maps the error codes returned by Braintree to a triple of target, type 
+      # and field used by the SubmissionError class.
+      #
+      # The key is the error code from Braintree. The first entry in the triple
+      # is the specific portion of the transaction that has the error. The 
+      # second is the type of error and the third is the field — if any — it 
+      # applies to.
+      ERROR_CODE_MAPPING = {
+        "81715" => [:credit_card, :invalid_number, :number],
+        "81725" => [:credit_card, :number_required, :number],
+        "81703" => [:credit_card, :type_not_accepted, :card_type],
+        "81716" => [:credit_card, :wrong_length, :number],
+        "81712" => [:credit_card, :invalid_expiration_month, :expiration_month],
+        "81713" => [:credit_card, :invalid_expiration_year, :expiration_year],
+        "81707" => [:credit_card, :invalid_cvv, :cvv],
+        "91507" => [:transaction, :cannot_capture, :status],
+        "91506" => [:transaction, :cannot_refund, :status],
+        "91504" => [:transaction, :cannot_void, :status]
+      }.freeze
+
+      # Extracts errors from the collection returned by Brain tree and coerces
+      # them into an array of SubmissionError.
+      #
+      # @param Braintree:ErrorResult result
+      # @return Array<SpookAndPay::Providers::Base::SubmissionError>
+      def extract_errors(result)
+        result.errors.map do |e|
+          mapping = ERROR_CODE_MAPPING[e.code]
+          if mapping 
+            SubmissionError.new(*mapping, e)
+          else
+            SubmissionError.new(:unknown, :unknown, :unknown, e)
+          end
+        end
+      end
+
+      # A generic method for generating results on actions. It doesn't capture 
+      # anything action specific i.e. it might need to be replaced later.
+      #
+      # @param [Braintree::SuccessfulResult, Braintree:ErrorResult] result
+      # @return SpookAndPay::Result
+      def generate_result(result)
+        case result
+        when ::Braintree::SuccessfulResult
+          SpookAndPay::Result.new(
+            true, 
+            result, 
+            :credit_card => extract_credit_card(result.transaction.credit_card_details, true, false), 
+            :transaction => extract_transaction(result.transaction)
+          )
+        when ::Braintree::ErrorResult
+          SpookAndPay::Result.new(
+            false, 
+            result, 
+            :errors => extract_errors(result)
+          )
+        end
+      end
+
+      # Extracts credit card details from a payload extracted from a result.
+      # It could be either a Hash, Braintree::CreditCard or 
+      # Braintree::Transaction::CreditCardDetails. BOO!
+      #
+      # @param [Hash, Braintree::CreditCard, Braintree::Transaction::CreditCardDetails] card
+      # @param [true, false] valid
+      # @param [true, false] expired
+      # @return SpookAndPay::CreditCard
+      #
+      # @todo figure out validity and expiry ourselves
+      def extract_credit_card(card, valid, expired)
+        opts = case card
+        when Hash 
+          {
+            :token            => card[:token],
+            :card_type        => card[:card_type],
+            :number           => card[:last_4],
+            :name             => card[:cardholder_name],
+            :expiration_month => card[:expiration_month],
+            :expiration_year  => card[:expiration_year]
+          }
+        else
+          {
+            :token            => card.token,
+            :card_type        => card.card_type,
+            :number           => card.last_4,
+            :name             => card.cardholder_name,
+            :expiration_month => card.expiration_month,
+            :expiration_year  => card.expiration_year
+          }
+        end
+
+        SpookAndPay::CreditCard.new(self, opts.delete(:token), opts)
+      end
+
+      # Extracts transaction details from whatever payload is passed in. This 
+      # might be Hash or a Braintree:Transaction.
+      #
+      # @param [Hash, Braintree::Transaction] result
+      # @param [true, false] successful
+      # @param Hash payload
+      # @return SpookAndPay::Transaction
+      #
+      # @todo Coerce type into what we know is valid
+      def extract_transaction(result, payload = {})
+        case result
+        when Hash
+          SpookAndPay::Transaction.new(
+            self,
+            result[:id],
+            coerce_transaction_status(result[:status]),
+            result,
+            :type       => result[:type].to_sym,
+            :created_at => result[:created_at],
+            :amount     => result[:amount]
+          ) 
+        else
+          SpookAndPay::Transaction.new(
+            self,
+            result.id,
+            coerce_transaction_status(result.status),
+            result,
+            :type       => result.type.to_sym,
+            :created_at => result.created_at,
+            :amount     => result.amount
+          ) 
+        end
+      end
+
+      # Coerces the status into a value expected by the Transaction class.
+      #
+      # @param [String, nil] status
+      # @return [String, nil]
+      def coerce_transaction_status(status)
+        case status
+        when 'submitted_for_settlement' then 'settling'
+        else status
+        end
+      end
+
+      # Based on the status of a transaction, make some determination of how of
+      # whether or not is is successful.
+      #
+      # @param String status
+      # @return [true, false]
+      #
+      # @todo Expand this to be more robust.
+      def coerce_transaction_success(status)
+        case status
+        when 'authorized' then true
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/spook_and_pay/result.rb

@@ -0,0 +1,68 @@
+module SpookAndPay
+  # A small convenience class which wraps any results coming back from a 
+  # provider. This is never instanced directly, but instead instances are
+  # created by the Provider classes.
+  class Result
+    # Readers for the various portions of a result's payload. Depending on the
+    # type of request any of these may be nil.
+    attr_reader :transaction, :credit_card, :raw, :errors
+
+    # @param [true, false] successful
+    # @param Class raw
+    # @param Hash opts
+    def initialize(successful, raw, opts = {})
+      @successful   = successful
+      @raw          = raw
+      @transaction  = opts[:transaction] if opts.has_key?(:transaction)
+      @credit_card  = opts[:credit_card] if opts.has_key?(:credit_card)
+      @errors       = opts[:errors] || []
+    end
+
+    # Checks to see if a transaction is present.
+    #
+    # @return [true, false]
+    def transaction?
+      !transaction.nil?
+    end
+
+    # Checks to see if a credit card is present.
+    #
+    # @return [true, false]
+    def credit_card?
+      !credit_card.nil?
+    end
+
+    # Checks to see if any errors are present.
+    #
+    # @return [true, false]
+    def errors?
+      !errors.empty?
+    end
+
+    # Collects errors for a specific target, keyed by field.
+    # 
+    # @param Symbol target
+    # @return Hash
+    def errors_for(target)
+      errors.select{|e| e.target == target}.reduce({}) do |h, e|
+        h[e.field] ||= []
+        h[e.field] << e
+        h
+      end
+    end
+
+    # A nice alias for checking for success.
+    #
+    # @return [true, false]
+    def successful?
+      @successful
+    end
+
+    # A nice helper for checking for failure.
+    #
+    # @return [true, false]
+    def failure?
+      !@successful
+    end
+  end
+end

data/lib/spook_and_pay/submission_error.rb

@@ -0,0 +1,66 @@
+module SpookAndPay
+  # Class used to encapsulate the details of an error related to some 
+  # interaction with the provider. It is generic in that it might apply to
+  # a specific part of the payload or it might capture more general details.
+  #
+  # It will also attempt translate errors into a human readable string. Where 
+  # it cannot, it still exposes the raw results from the provider allowing 
+  # debugging.
+  class SubmissionError
+    # A constant which defines the acceptable types of errors and which is
+    # also used to generate specific messages. Where the error is unknown,
+    # the consumer of this library will be directed to use the raw error 
+    # generated by the underlying libraries.
+    ERROR_MESSAGES = {
+      :credit_card => {
+        :number_required          => "number is required",
+        :invalid_number           => "number is invalid",
+        :type_not_accepted        => "card type is not accepted by this merchant",
+        :wrong_length             => "number must be between 12 and 19 digits",
+        :invalid_expiration_month => "expiration month is invalid",
+        :invalid_expiration_year  => "expiration year is invalid",
+        :invalid_cvv              => "CVV must be three digits"
+      },
+      :transaction => {
+        :cannot_capture => "must be authorized in order to capture funds",
+        :cannot_refund  => "must be settled in order to refund",
+        :cannot_void    => "must be authorized or settled in order to void"
+      },
+      :unknown => {
+        :unknown => "please refer to the #raw attribute of this error"
+      }
+    }.freeze
+
+    # Basic attributes
+    attr_reader :error_type, :message, :target, :raw, :field
+
+    # Generates a new error. Based on the target and error type, it can
+    # generate the appropriate error messages or otherwise fall back.
+    #
+    # @param Symbol error_type
+    # @param Symbol target
+    # @param [Symbol, nil] field
+    # @param Class raw
+    def initialize(target, error_type, field, raw)
+      @error_type = error_type
+      @target = target
+      @field = field
+      @raw = raw
+    end
+
+    # Indicates if this is an error that we don't know anything about.
+    #
+    # @return [true, false]
+    def unknown?
+      @error_type == :unknown
+    end
+
+    # Generates a human readable error message based on the target and
+    # error type.
+    #
+    # @return String
+    def message
+      ERROR_MESSAGES[target][error_type]
+    end
+  end
+end

data/lib/spook_and_pay/transaction.rb

@@ -0,0 +1,149 @@
+module SpookAndPay
+  # A simple class representing an interaction with a provider. Each 
+  # interaction has an ID, a type and may be successful or not. It is 
+  # read-only.
+  class Transaction
+    # Basic attributes
+    attr_reader :provider, :id, :status, :raw
+
+    # Extra set of fields which may or may not be present depending on the 
+    # provider.
+    FIELDS = [:created_at, :updated_at, :amount, :credit_card, :type].freeze
+    attr_reader *FIELDS
+
+    # The basic types for transactions.
+    TYPES = [:purchase, :authorize, :capture, :credit, :void].freeze
+
+    # Acceptable set of statuses.
+    STATUSES = [:authorized, :settling, :settled, :voided, :refunded, :gateway_rejected].freeze
+
+    # An error thrown when attempting to perform an action that is not allowed
+    # given a transaction's status.
+    class InvalidActionError < StandardError
+      # @param String id
+      # @param Symbol action
+      # @param Symbol status
+      def initialize(id, action, status)
+        @id     = id
+        @action = action
+        @status = status
+      end
+
+      # Human readable message.
+      #
+      # @return String
+      def to_s
+        "Cannot perform the action '#{@action}' for transaction '#{@id}' while in status '#{@status}'"
+      end
+    end
+
+    # As a bare minimum the transaction captures the transaction ID, it's 
+    # status and the raw response from the provider. Optionally, it can receive
+    # other fields via the opts hash.
+    #
+    # @param SpookAndPay::Providers::Base provider
+    # @param String id
+    # @param [String, nil] status
+    # @param Class raw
+    # @param Hash opts
+    # @option opts SpookAndPay::CreditCard :credit_card
+    # @option opts Time :created_at
+    # @option opts Time :updated_at
+    # @option opts BigDecimal :amount
+    # @option opts String :type
+    def initialize(provider, id, status, raw, opts = {})
+      @provider   = provider
+      @id         = id
+      @status     = status.to_sym if status
+      @raw        = raw
+
+      FIELDS.each {|f| instance_variable_set(:"@#{f}", opts[f]) if opts.has_key?(f)}
+    end
+
+    # Implements value comparison i.e. if class and ID match, they are the 
+    # same.
+    #
+    # @param Class other
+    # @return [true, false]
+    def ==(other)
+      other.is_a?(SpookAndPay::Transaction) and other.id == id
+    end
+
+    # A simple predicate to see if the payment has been settled.
+    #
+    # @return [true, false]
+    def settled?
+      status == :settled
+    end
+
+    # A simple predicate which indicates if the payment is in the process of
+    # being settled.
+    #
+    # @return [true, false]
+    def settling?
+      status == :settling
+    end
+
+    # A simple predicate to check if the payment has been authorized.
+    #
+    # @return [true, false]
+    def authorized?
+      status == :authorized
+    end
+
+    # A predicate for checking if a transaction can be refunded. Only true if
+    # the status is :settled
+    #
+    # @return [true, false]
+    def can_refund?
+      status == :settled
+    end
+
+    # A predicate for checking if a transaction can be captured. Only true if
+    # the status is :authorized
+    #
+    # @return [true, false]
+    def can_capture?
+      status == :authorized
+    end
+
+    # A predicate for checking if a transaction can be voided. Only true if
+    # the status is :authorized or :submitted_for_settlement
+    #
+    # @return [true, false]
+    def can_void?
+      status == :authorized or status == :settling
+    end
+
+    # Refunds the transaction. The related credit card will be credited for
+    # the amount captured. It will only succeed for purchases or captured
+    # authorizations.
+    #
+    # @return SpookAndPay::Result
+    # @raises InvalidActionError
+    def refund!
+      raise InvalidActionError.new(id, :refund, status) unless can_refund?
+      provider.refund_transaction(self)
+    end
+
+    # Captures an authorized transaction. Will only capture the amount 
+    # authorized and will fail if the transaction is already captured.
+    #
+    # @return SpookAndPay::Result
+    # @raises InvalidActionError
+    def capture!
+      raise InvalidActionError.new(id, :capture, status) unless can_capture?
+      provider.capture_transaction(self)
+    end
+
+    # Voids a transaction. Can only be done when the transaction is in the 
+    # authorized status. Otherwise it must be refunded.
+    #
+    # @return SpookAndPay::Result
+    # @raises InvalidActionError
+    def void!
+      raise InvalidActionError.new(id, :void, status) unless can_void?
+      provider.void_transaction(self)
+    end
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: spook_and_pay
+version: !ruby/object:Gem::Version
+  version: 0.2.0.alpha
+platform: ruby
+authors:
+- Luke Sutton
+- Ben Hull
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: braintree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.25.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.25.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+- !ruby/object:Gem::Dependency
+  name: debugger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.6.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.6.1
+description: 
+email:
+- lukeandben@spookandpuff.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/spook_and_pay/adapters/braintree.rb
+- lib/spook_and_pay/adapters.rb
+- lib/spook_and_pay/credit_card.rb
+- lib/spook_and_pay/erroring_reader.rb
+- lib/spook_and_pay/missing_value_error.rb
+- lib/spook_and_pay/providers/base.rb
+- lib/spook_and_pay/providers/braintree.rb
+- lib/spook_and_pay/providers.rb
+- lib/spook_and_pay/result.rb
+- lib/spook_and_pay/submission_error.rb
+- lib/spook_and_pay/transaction.rb
+- lib/spook_and_pay.rb
+- README.md
+- LICENSE
+homepage: http://spookandpuff.com
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A library for handling online payments using services providing transparent
+  redirects.
+test_files: []