braintree 1.0.0

data/lib/braintree/http.rb

@@ -0,0 +1,105 @@
+module Braintree
+  module Http # :nodoc:
+    
+    def self.delete(path)
+      response = _http_do Net::HTTP::Delete, path
+      if response.code.to_i == 200
+        true
+      else
+        Util.raise_exception_for_status_code(response.code)
+      end
+    end
+    
+    def self.get(path)
+      response = _http_do Net::HTTP::Get, path
+      if response.code.to_i == 200
+        Xml.hash_from_xml(_body(response))
+      else
+        Util.raise_exception_for_status_code(response.code)
+      end
+    end
+    
+    def self.post(path, params = nil)
+      response = _http_do Net::HTTP::Post, path, _build_xml(params)
+      if response.code.to_i == 200 || response.code.to_i == 201 || response.code.to_i == 422
+        Xml.hash_from_xml(_body(response))
+      else
+        Util.raise_exception_for_status_code(response.code)
+      end
+    end
+    
+    def self.put(path, params = nil)
+      response = _http_do Net::HTTP::Put, path, _build_xml(params)
+      if response.code.to_i == 200 || response.code.to_i == 201 || response.code.to_i == 422
+        Xml.hash_from_xml(_body(response))
+      else
+        Util.raise_exception_for_status_code(response.code)
+      end
+    end
+
+    def self._build_xml(params)
+      return nil if params.nil?
+      Braintree::Xml.hash_to_xml params
+    end
+    
+    def self._http_do(http_verb, path, body = nil)
+      connection = Net::HTTP.new(Configuration.server, Configuration.port)
+      if Configuration.ssl?
+        connection.use_ssl = true
+        connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        connection.ca_file = Configuration.ca_file
+        connection.verify_callback = proc { |preverify_ok, ssl_context| _verify_ssl_certificate(preverify_ok, ssl_context) }
+      end
+      connection.start do |http|
+        request = http_verb.new("#{Configuration.base_merchant_path}#{path}")
+        request["Accept"] = "application/xml"
+        request["User-Agent"] = "Braintree Ruby Gem #{Braintree::Version::String}"
+        request["Accept-Encoding"] = "gzip"
+        request["X-ApiVersion"] = Configuration::API_VERSION
+        request.basic_auth Configuration.public_key, Configuration.private_key
+        Configuration.logger.debug "[Braintree] [#{_current_time}] #{request.method} #{path}"
+        if body
+          request["Content-Type"] = "application/xml"
+          request.body = body
+          Configuration.logger.debug _format_and_sanitize_body_for_log(body)
+        end
+        response = http.request(request)
+        Configuration.logger.info "[Braintree] [#{_current_time}] #{request.method} #{path} #{response.code}"
+        Configuration.logger.debug "[Braintree] [#{_current_time}] #{response.code} #{response.message}"
+        if Configuration.logger.level == Logger::DEBUG
+          Configuration.logger.debug _format_and_sanitize_body_for_log(_body(response))
+        end
+        response
+      end
+    end
+
+    def self._body(response)
+      if response.header["Content-Encoding"] == "gzip"
+        Zlib::GzipReader.new(StringIO.new(response.body)).read
+      else
+        raise UnexpectedError, "expected a gzip'd response"
+      end
+    end
+    
+    def self._current_time
+      Time.now.utc.strftime("%d/%b/%Y %H:%M:%S %Z")
+    end
+    
+    def self._format_and_sanitize_body_for_log(input_xml)
+      formatted_xml = input_xml.gsub(/^/, "[Braintree] ")
+      formatted_xml = formatted_xml.gsub(/<number>(.{6}).+?(.{4})<\/number>/, '<number>\1******\2</number>')
+      formatted_xml = formatted_xml.gsub(/<cvv>.+?<\/cvv>/, '<cvv>***</cvv>')
+      formatted_xml
+    end
+
+    def self._verify_ssl_certificate(preverify_ok, ssl_context)
+      if preverify_ok != true || ssl_context.error != 0
+        err_msg = "SSL Verification failed -- Preverify: #{preverify_ok}, Error: #{ssl_context.error_string} (#{ssl_context.error})"
+        Configuration.logger.error err_msg
+        raise SSLCertificateError.new(err_msg)
+      end
+      true
+    end
+  end
+end
+

data/lib/braintree/paged_collection.rb

@@ -0,0 +1,55 @@
+module Braintree
+  class PagedCollection
+    include BaseModule
+    include Enumerable
+    
+    attr_reader :current_page_number, :items, :next_page_number, :page_size, :previous_page_number, :total_items
+    
+    def initialize(attributes, &block) # :nodoc:
+      set_instance_variables_from_hash attributes
+      @paging_block = block
+    end
+
+    # Returns the item from the current page at the given +index+.
+    def [](index)
+      @items[index]
+    end
+   
+    # Yields each item on the current page. 
+    def each(&block)
+      @items.each(&block)
+    end  
+
+    # Returns the first item from the current page.
+    def first
+      @items.first
+    end
+
+    # Returns true if the page is the last page. False otherwise.
+    def last_page?
+      current_page_number == total_pages
+    end
+   
+    # Retrieves the next page of records. 
+    def next_page
+      if last_page?
+        return nil
+      end
+      @paging_block.call(next_page_number)
+    end
+   
+    # The next page number. Returns +nil+ if on the last page. 
+    def next_page_number
+      last_page? ? nil : current_page_number + 1
+    end
+   
+    # Returns the total number of pages. 
+    def total_pages
+      total = total_items / page_size 
+      if total_items % page_size != 0
+        total += 1
+      end  
+      total
+    end  
+  end
+end

data/lib/braintree/ssl_expiration_check.rb

@@ -0,0 +1,28 @@
+module Braintree
+  module SSLExpirationCheck # :nodoc:
+    class << self
+      attr_reader :ssl_expiration_dates_checked
+    end
+
+    def self.check_dates # :nodoc:
+      {
+        "QA" => qa_expiration_date,
+        "Sandbox" => sandbox_expiration_date
+      }.each do |host, expiration_date|
+        if Date.today + (3 * 30) > expiration_date
+          Configuration.logger.warn "[Braintree] The SSL Certificate for the #{host} environment will expire on #{expiration_date}. Please check for an updated client library."
+        end
+      end
+      @ssl_expiration_dates_checked = true
+    end
+
+
+    def self.sandbox_expiration_date # :nodoc:
+      Date.new(2010, 12, 1)
+    end
+
+    def self.qa_expiration_date # :nodoc:
+      Date.new(2010, 12, 1)
+    end
+  end
+end

data/lib/braintree/successful_result.rb

@@ -0,0 +1,38 @@
+module Braintree 
+  # A SuccessfulResult will be returned from non-bang methods when
+  # validations pass. It will provide access to the created resource.
+  # For example, when creating a customer, SuccessfulResult will
+  # respond to +customer+ like so:
+  #
+  #   result = Customer.create(:first_name => "John")
+  #   if result.success?
+  #     # have a SuccessfulResult
+  #     puts "Created customer #{result.customer.id}
+  #   else
+  #     # have an ErrorResult
+  #   end
+  class SuccessfulResult
+    include BaseModule
+  
+    def initialize(attributes = {}) # :nodoc:
+      @attrs = attributes.keys
+      singleton_class.class_eval do
+        attributes.each do |key, value|
+          define_method key do
+            value
+          end
+        end
+      end  
+    end
+
+    def inspect # :nodoc:
+      inspected_attributes = @attrs.map { |attr| "#{attr}:#{send(attr).inspect}" }
+      "#<#{self.class} #{inspected_attributes}>"
+    end
+
+    # Always returns true.
+    def success?
+      true
+    end
+  end
+end

data/lib/braintree/test/credit_card_numbers.rb

@@ -0,0 +1,50 @@
+module Braintree
+  module Test # :nodoc:
+    # The constants contained in the Braintree::Test::CreditCardNumbers module provide
+    # credit card numbers that should be used when working in the sandbox environment. The sandbox
+    # will not accept any credit card numbers other than the ones listed below.
+    module CreditCardNumbers
+      AmExes = %w[
+        378282246310005
+        371449635398431
+        378734493671000
+      ]
+      CarteBlanches = %w[30569309025904] # :nodoc:
+      DinersClubs = %w[38520000023237] # :nodoc:
+
+      Discovers = %w[
+        6011111111111117
+        6011000990139424
+      ]
+      JCBs = %w[3530111333300000 3566002020360505] # :nodoc:
+
+      MasterCard = "5555555555554444"
+      MasterCardInternational = "5105105105105100" # :nodoc:
+
+      MasterCards = %w[5105105105105100 5555555555554444]
+
+      Visa = "4012888888881881"
+      VisaInternational = "4009348888881881" # :nodoc:
+
+      Visas = %w[
+        4009348888881881
+        4012888888881881
+        4111111111111111
+        4222222222222
+      ]
+      Unknowns = %w[
+        1000000000000008
+      ]
+
+      module FailsSandboxVerification
+        AmEx       = "378734493671000"
+        Discover   = "6011000990139424"
+        MasterCard = "5105105105105100"
+        Visa       = "4222222222222"
+        Numbers    = [AmEx, Discover, MasterCard, Visa]
+      end
+  
+      All = AmExes + Discovers + MasterCards + Visas
+    end
+  end
+end

data/lib/braintree/test/transaction_amounts.rb

@@ -0,0 +1,10 @@
+module Braintree
+  module Test # :nodoc:
+    # The constants in this module can be used to create transactions with
+    # the desired status in the sandbox environment.
+    module TransactionAmounts
+      Authorize = "1000.00"
+      Decline = "2000.00"
+    end
+  end
+end

data/lib/braintree/transaction.rb

@@ -0,0 +1,360 @@
+module Braintree
+  # == Creating a Transaction
+  #
+  # At minimum, an amount, credit card number, and credit card expiration date are required. Minimalistic
+  # example:
+  #  Braintree::Transaction.sale!(
+  #    :amount => "100.00",
+  #    :credit_card => {
+  #      :number => "5105105105105100",
+  #      :expiration_date => "05/2012"
+  #    }
+  #  ) 
+  #
+  # Full example:
+  #
+  #  Braintree::Transaction.sale!(
+  #    :amount => "100.00",
+  #    :order_id => "123",
+  #    :credit_card => {
+  #      # if :token is omitted, the gateway will generate a token
+  #      :token => "credit_card_123",
+  #      :number => "5105105105105100",
+  #      :expiration_date => "05/2011",
+  #      :cvv => "123"
+  #    },
+  #    :customer => {
+  #      # if :id is omitted, the gateway will generate an id
+  #      :id => "customer_123",
+  #      :first_name => "Dan",
+  #      :last_name => "Smith",
+  #      :company => "Braintree Payment Solutions",
+  #      :email => "dan@example.com",
+  #      :phone => "419-555-1234",
+  #      :fax => "419-555-1235",
+  #      :website => "http://braintreepaymentsolutions.com"
+  #    },
+  #    :billing => {
+  #      :first_name => "Carl",
+  #      :last_name => "Jones",
+  #      :company => "Braintree",
+  #      :street_address => "123 E Main St",
+  #      :extended_address => "Suite 403",
+  #      :locality => "Chicago",
+  #      :region => "IL",
+  #      :postal_code => "60622",
+  #      :country_name => "United States of America"
+  #    },
+  #    :shipping => {
+  #      :first_name => "Andrew",
+  #      :last_name => "Mason",
+  #      :company => "Braintree",
+  #      :street_address => "456 W Main St",
+  #      :extended_address => "Apt 2F",
+  #      :locality => "Bartlett",
+  #      :region => "IL",
+  #      :postal_code => "60103",
+  #      :country_name => "United States of America"
+  #    }
+  #  )
+  #
+  # == Storing in the Vault
+  #
+  # The customer and credit card information used for
+  # a transaction can be stored in the vault by setting
+  # <tt>transaction[options][store_in_vault]</tt> to true.
+  #
+  #   transaction = Braintree::Transaction.create!(
+  #     :customer => {
+  #       :first_name => "Adam",
+  #       :last_name => "Williams"
+  #     },
+  #     :credit_card => {
+  #       :number => "5105105105105100",
+  #       :expiration_date => "05/2012"
+  #     },
+  #     :options => {
+  #       :store_in_vault => true
+  #     }
+  #   )
+  #   transaction.customer_details.id
+  #   # => "865534"
+  #   transaction.credit_card_details.token
+  #   # => "6b6m"
+  #
+  # == Submitting for Settlement
+  #
+  # This can only be done when the transction's
+  # status is +authorized+. If +amount+ is not specified, the full authorized amount will be
+  # settled. If you would like to settle less than the full authorized amount, pass the
+  # desired amount. You cannot settle more than the authorized amount.
+  #
+  # A transaction can be submitted for settlement when created by setting
+  # transaction[options][submit_for_settlement] to true.
+  #
+  #   transaction = Braintree::Transaction.sale!(
+  #     :amount => "100.00",
+  #     :credit_card => {
+  #       :number => "5105105105105100",
+  #       :expiration_date => "05/2012"
+  #     },
+  #     :options => {
+  #       :submit_for_settlement => true
+  #     }
+  #   )
+  class Transaction
+    include BaseModule
+    
+    module Type # :nodoc:
+      Credit = "credit" # :nodoc:
+      Sale = "sale" # :nodoc:
+    end
+    
+    attr_reader :avs_error_response_code, :avs_postal_code_response_code, :avs_street_address_response_code
+    attr_reader :amount, :created_at, :credit_card_details, :customer_details, :id, :status
+    attr_reader :order_id
+    attr_reader :billing_details, :shipping_details
+    # The response code from the processor.
+    attr_reader :processor_response_code
+    # Will either be "sale" or "credit"
+    attr_reader :type
+    attr_reader :updated_at
+
+    def self.create(attributes)
+      Util.verify_keys(_create_signature, attributes)
+      _do_create "/transactions", :transaction => attributes
+    end
+    
+    def self.create!(attributes)
+      return_object_or_raise(:transaction) { create(attributes) }
+    end
+
+    def self.create_from_transparent_redirect(query_string)
+      params = TransparentRedirect.parse_and_validate_query_string query_string
+      _do_create("/transactions/all/confirm_transparent_redirect_request", :id => params[:id])
+    end
+
+    # The URL to use to create transactions via transparent redirect.
+    def self.create_transaction_url
+      "#{Braintree::Configuration.base_merchant_url}/transactions/all/create_via_transparent_redirect_request"
+    end
+   
+    # Creates a credit transaction. 
+    def self.credit(attributes)
+      create(attributes.merge(:type => 'credit'))
+    end
+    
+    def self.credit!(attributes)
+      return_object_or_raise(:transaction) { credit(attributes) }
+    end
+
+    # Finds the transaction with the given id. Raises a Braintree::NotFoundError
+    # if the transaction cannot be found.
+    def self.find(id)
+      response = Http.get "/transactions/#{id}"
+      new(response[:transaction])
+    rescue NotFoundError
+      raise NotFoundError, "transaction with id #{id.inspect} not found"
+    end
+
+    # Creates a sale transaction.
+    def self.sale(attributes)
+      create(attributes.merge(:type => 'sale'))
+    end
+    
+    def self.sale!(attributes)
+      return_object_or_raise(:transaction) { sale(attributes) }
+    end
+    
+    # Returns a PagedCollection of transactions matching the search query.
+    # If <tt>query</tt> is a string, the search will be a basic search.
+    # If <tt>query</tt> is a hash, the search will be an advanced search.
+    def self.search(query, options = {})
+      if query.is_a?(String)
+        _basic_search query, options
+      elsif query.is_a?(Hash)
+        _advanced_search query, options
+      else
+        raise ArgumentError, "expected query to be a string or a hash"
+      end
+    end
+
+    # Submits transaction with +transaction_id+ for settlement.
+    def self.submit_for_settlement(transaction_id, amount = nil)
+      raise ArgumentError, "transaction_id is invalid" unless transaction_id =~ /\A[0-9a-z]+\z/
+      response = Http.put "/transactions/#{transaction_id}/submit_for_settlement", :transaction => {:amount => amount}
+      if response[:transaction]
+        SuccessfulResult.new(:transaction => new(response[:transaction]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :transaction or :response"
+      end
+    end
+
+    def self.submit_for_settlement!(transaction_id, amount = nil)
+      return_object_or_raise(:transaction) { submit_for_settlement(transaction_id, amount) }
+    end
+
+    # Voids the transaction with the given <tt>transaction_id</tt>
+    def self.void(transaction_id)
+      response = Http.put "/transactions/#{transaction_id}/void"
+      if response[:transaction]
+        SuccessfulResult.new(:transaction => new(response[:transaction]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :transaction or :api_error_response"
+      end
+    end
+
+    def self.void!(transaction_id)
+      return_object_or_raise(:transaction) { void(transaction_id) }
+    end
+
+    def initialize(attributes) # :nodoc:
+      _init attributes
+    end
+    
+    # True if <tt>other</tt> has the same id.
+    def ==(other)
+      id == other.id
+    end
+    
+    def inspect # :nodoc:
+      first = [:id, :type, :amount, :status]
+      order = first + (self.class._attributes - first)
+      nice_attributes = order.map do |attr|
+        "#{attr}: #{send(attr).inspect}"
+      end
+      "#<#{self.class} #{nice_attributes.join(', ')}>"
+    end
+    
+    # Creates a credit transaction that refunds this transaction.
+    def refund
+      response = Http.post "/transactions/#{id}/refund"
+      if response[:transaction]
+        # TODO: need response to return original_transaction so that we can update status, updated_at, etc.
+        SuccessfulResult.new(:new_transaction => Transaction._new(response[:transaction]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :transaction or :api_error_response"
+      end
+    end
+    
+    # Returns true if the transaction has been refunded. False otherwise.
+    def refunded?
+      !@refund_id.nil?
+    end
+
+    # Submits the transaction for settlement.
+    def submit_for_settlement(amount = nil)
+      response = Http.put "/transactions/#{id}/submit_for_settlement", :transaction => {:amount => amount}
+      if response[:transaction]
+        _init(response[:transaction])
+        SuccessfulResult.new :transaction => self
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected transaction or api_error_response"
+      end
+    end
+
+    def submit_for_settlement!(amount = nil)
+      return_object_or_raise(:transaction) { submit_for_settlement(amount) }
+    end
+    
+    # If this transaction was stored in the vault, or created from vault records,
+    # vault_credit_card will return the associated Braintree::CreditCard. Because the
+    # vault credit card can be updated after the transaction was created, the attributes
+    # on vault_credit_card may not match the attributes on credit_card_details.
+    def vault_credit_card
+      return nil if credit_card_details.token.nil?
+      CreditCard.find(credit_card_details.token)
+    end
+    
+    # If this transaction was stored in the vault, or created from vault records,
+    # vault_customer will return the associated Braintree::Customer. Because the
+    # vault customer can be updated after the transaction was created, the attributes
+    # on vault_customer may not match the attributes on customer_details.
+    def vault_customer
+      return nil if customer_details.id.nil?
+      Customer.find(customer_details.id)
+    end
+    
+    # Voids the transaction.
+    def void
+      response = Http.put "/transactions/#{id}/void"
+      if response[:transaction]
+        _init response[:transaction]
+        SuccessfulResult.new(:transaction => self)
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :transaction or :api_error_response"
+      end
+    end
+
+    def void!
+      return_object_or_raise(:transaction) { void }
+    end
+
+    class << self
+      protected :new
+      def _new(*args) # :nodoc:
+        self.new *args
+      end  
+    end
+    
+    def self._do_create(url, params) # :nodoc:
+      response = Http.post url, params
+      if response[:transaction]
+        SuccessfulResult.new(:transaction => new(response[:transaction]))
+      elsif response[:api_error_response]
+        ErrorResult.new(response[:api_error_response])
+      else
+        raise UnexpectedError, "expected :transaction or :api_error_response"
+      end
+    end
+    
+    def self._advanced_search(query, options) # :nodoc:
+      page = options[:page] || 1
+      response = Http.post "/transactions/advanced_search?page=#{Util.url_encode(page)}", :search => query
+      attributes = response[:credit_card_transactions]
+      attributes[:items] = Util.extract_attribute_as_array(attributes, :transaction).map { |attrs| _new(attrs) }
+      PagedCollection.new(attributes) { |page_number| Transaction.search(query, :page => page_number) }      
+    end
+
+    def self._attributes # :nodoc:
+      [:amount, :created_at, :credit_card_details, :customer_details, :id, :status, :type, :updated_at]
+    end
+    
+    def self._basic_search(query, options) # :nodoc:
+      page = options[:page] || 1
+      response = Http.get "/transactions/all/search?q=#{Util.url_encode(query)}&page=#{Util.url_encode(page)}"
+      attributes = response[:credit_card_transactions]
+      attributes[:items] = Util.extract_attribute_as_array(attributes, :transaction).map { |attrs| _new(attrs) }
+      PagedCollection.new(attributes) { |page_number| Transaction.search(query, :page => page_number) }
+    end
+    
+    def self._create_signature # :nodoc:
+      [
+        :amount, :customer_id, :order_id, :payment_method_token, :type,
+        {:credit_card => [:token, :cvv, :expiration_date, :number]},
+        {:customer => [:id, :company, :email, :fax, :first_name, :last_name, :phone, :website]},
+        {:billing => [:first_name, :last_name, :company, :country_name, :extended_address, :locality, :postal_code, :region, :street_address]},
+        {:shipping => [:first_name, :last_name, :company, :country_name, :extended_address, :locality, :postal_code, :region, :street_address]},
+        {:options => [:store_in_vault, :submit_for_settlement]}
+      ]
+    end
+    
+    def _init(attributes) # :nodoc:
+      set_instance_variables_from_hash(attributes)
+      @credit_card_details = CreditCardDetails.new(@credit_card)
+      @customer_details = CustomerDetails.new(@customer)
+      @billing_details = AddressDetails.new(@billing)
+      @shipping_details = AddressDetails.new(@shipping)
+    end
+  end  
+end