paytrace 0.1.23 → 1.0.0

data/lib/paytrace/customer.rb

@@ -1,9 +1,9 @@
 module PayTrace
   # Abstracts the idea of a merchant's customer. Also provides numerous helper methods to aid in managing customers.
   class Customer
+    # :nodoc:
     attr :id, :customer_id
 
-    # :nodoc:
     CREATE_CUSTOMER = "CreateCustomer"
     UPDATE_CUSTOMER = "UpdateCustomer"
     DELETE_CUSTOMER = "DeleteCustomer"
@@ -11,29 +11,53 @@ module PayTrace
     EXPORT_INACTIVE_CUSTOMERS = "ExportInactiveCustomers"
     EXPORT_CUSTOMERS_RESPONSE = "CUSTOMERRECORD"
 
+    BILLING_AND_SHIPPING_ADDRESS_FIELDS = [
+      :billing_name,
+      :billing_address,
+      :billing_address2,
+      :billing_city,
+      :billing_state,
+      :billing_postal_code,
+      :billing_country,
+      :shipping_name,
+      :shipping_address,
+      :shipping_address2,
+      :shipping_city,
+      :shipping_state,
+      :shipping_postal_code,
+      :shipping_region,
+      :shipping_country
+    ]
+
+    CUSTOMER_OPTIONAL_PARAMS = BILLING_AND_SHIPPING_ADDRESS_FIELDS + [
+      :email,
+      :customer_phone,
+      :customer_fax,
+      :customer_password,
+      :account_number,
+      :routing_number,
+      :discretionary_data
+    ]
+    
     # :doc:
-    # Initializer. Only param is:
-    # *customer_id* -- the merchant-generated customer ID, if present
-    def initialize(customer_id = nil)
-      @customer_id = customer_id
-    end
 
     # See http://help.paytrace.com/api-update-customer-profile
+    #
+    # Updates the customer's information from parameters hash.
+    #
+    # Required parameters:
+    #
+    # * *:customer_id* -- the customer ID of the profile to update
+    #
     # Updates the customer's information from parameters hash. See the self.from_cc_info and self.from_transaction_id for
     # information on the permitted parameters. Immediately updates the profile.
-    def update(params = {})
-      send_request(UPDATE_CUSTOMER, params)
-    end
-
-    # See http://help.paytrace.com/api-delete-customer-profile
-    # Sends a request to the server to delete a given customer. No parameters; the customer ID is assumed to be set on
-    # this object.
-    def delete
-      request = PayTrace::API::Request.new
-      request.set_param(:method, DELETE_CUSTOMER)
-      request.set_param(:customer_id, @customer_id)
-      gateway = PayTrace::API::Gateway.new
-      gateway.send_request(request)
+    def self.update(params = {})
+      PayTrace::API::Gateway.send_request(UPDATE_CUSTOMER, params, [:customer_id], CUSTOMER_OPTIONAL_PARAMS + [
+        :card_number,
+        :expiration_month,
+        :expiration_year,
+        :new_customer_id
+      ])
     end
 
     # See http://help.paytrace.com/api-exporting-customer-profiles for more information.
@@ -43,49 +67,54 @@ module PayTrace
     # * *:transaction_user* -- the user name of the PayTrace user who created or processed the customer or transaction you are trying to export
     # * *:return_bin* -- if set to "Y", card numbers from ExportTranx and ExportCustomers requests will include the first 6 and last 4 digits of the card number
     def self.export(params = {})
-      # CUSTID, EMAIL, USER, RETURNBIN
-      request = PayTrace::API::Request.new
-      request.set_param(:method, EXPORT_CUSTOMERS)
-      request.set_param(:customer_id, params[:customer_id])
-      request.set_param(:email, params[:email])
-      request.set_param(:transaction_user, params[:transaction_user])
-      request.set_param(:return_bin, params[:return_bin])
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request, [EXPORT_CUSTOMERS_RESPONSE])      
-
-      unless response.has_errors?
-        response.values[EXPORT_CUSTOMERS_RESPONSE]
-      end
+      response = PayTrace::API::Gateway.send_request(EXPORT_CUSTOMERS, params, [], [:customer_id, :email, :transaction_user, :return_bin])
+      response.parse_records(EXPORT_CUSTOMERS_RESPONSE)
     end
 
     # See http://help.paytrace.com/api-exporting-inactive-customers
     # Exports the profiles of customers who have been inactive for a certain length of time. Params:
     # *:days_inactive* -- the number of days of inactivity to search for
     def self.export_inactive(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, EXPORT_INACTIVE_CUSTOMERS)
-      request.set_param(:days_inactive, params[:days_inactive])
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request, [EXPORT_CUSTOMERS_RESPONSE])
-
-      unless response.has_errors?
-        response.values[EXPORT_CUSTOMERS_RESPONSE]
-      end
+      response = PayTrace::API::Gateway.send_request(EXPORT_INACTIVE_CUSTOMERS, params, [:days_inactive], [])
+      response.parse_records(EXPORT_CUSTOMERS_RESPONSE)
     end
 
     # See http://help.paytrace.com/api-delete-customer-profile
     # Performs the same functionality as Customer.delete, but saves a step by not requiring the user to instantiate a new Customer object first. Params:
     # *customer_id* -- the merchant-assigned customer ID of the profile to delete
     def self.delete(customer_id)
-      Customer.new(customer_id).delete
+      PayTrace::API::Gateway.send_request(DELETE_CUSTOMER, {customer_id: customer_id}, [:customer_id])
     end
 
     # See http://help.paytrace.com/api-create-customer-profile
-    # Creates a new customer profile from credit card information. Params:
-    # *:customer_id* -- customer ID to use
-    # *:billing_address* -- a PayTrace::Address object; at minimum the billing name must be filled out
-    # *:credit_card* -- a PayTrace::CreditCard object
-    # *:shipping_address* -- a PayTrace::Address object representing the shipping address
+    #
+    # Creates a new customer profile from credit card information.
+    #
+    # Required parameters:
+    #
+    # * *:customer_id* -- customer ID to use
+    # * *:billing_name* -- the billing name for this transaction
+    # * *:card_number* -- a credit card number
+    # * *:expiration_month* -- the expiration month for the credit card
+    # * *:expiration_year* -- the expiration year for the credit card
+    #
+    # Optional parameters:
+    #
+    # * *:billing_name* -- the billing name for this transaction
+    # * *:billing_address* -- the billing street address for this transaction
+    # * *:billing_address2* -- the billing street address second line (e.g., apartment, suite) for this transaction
+    # * *:billing_city* -- the billing city for this transaction
+    # * *:billing_state* -- the billing state for this transaction
+    # * *:billing_postal_code* -- the billing zip code for this transaction
+    # * *:billing_country* -- the billing country for this transaction
+    # * *:shipping_name* -- the shipping name for this transaction
+    # * *:shipping_address* -- the shipping street address for this transaction
+    # * *:shipping_address2* -- the shipping street address second line (e.g., apartment, suite) for this transaction
+    # * *:shipping_city* -- the shipping city for this transaction
+    # * *:shipping_state* -- the shipping state for this transaction
+    # * *:shipping_postal_code* -- the shipping zip code for this transaction
+    # * *:shipping_region* -- the shipping region (e.g. county) for this transaction
+    # * *:shipping_country* -- the shipping country for this transaction
     # *:email* -- the customer's email address
     # *:customer_phone* -- the customer's phone number
     # *:customer_fax* -- the customer's fax number
@@ -94,60 +123,29 @@ module PayTrace
     # *:routing_number* -- a bank routing number to use
     # *:discretionary_data* -- discretionay data (if any) for the customer, expressed as a hash
     def self.from_cc_info(params = {})
-      customer = Customer.new(params[:customer_id])
-      customer.send_request(CREATE_CUSTOMER, params)
+      PayTrace::API::Gateway.send_request(CREATE_CUSTOMER, params, [
+        :customer_id,
+        :billing_name,
+        :card_number,
+        :expiration_month,
+        :expiration_year], CUSTOMER_OPTIONAL_PARAMS)
     end
 
     # See http://help.paytrace.com/api-create-customer-profile
-    # Creates a new customer profile from credit card information. Params are the same as from_cc_info, with the exception that *:transaction_id* is used to reference a previous sale transaction instead of a credit card.
+    #
+    # Creates a new customer profile from a previous transaction.
+    #
+    # Required parameters:
+    #
+    # * *:customer_id* -- customer ID to use
+    # * *:billing_name* -- the billing name for this transaction
+    # * *:card_number* -- a credit card number
+    # * *:expiration_month* -- the expiration month for the credit card
+    # * *:expiration_year* -- the expiration year for the credit card
+    #
+    # Optional parameters are the same as *:from_cc_info*
     def self.from_transaction_id(params = {})
-      customer = Customer.new(params[:customer_id])
-      customer.send_request(CREATE_CUSTOMER, params)
-    end
-
-    # :nodoc:
-    # Internal helper method; not meant to be called directly.
-    def send_request(method, params)
-      request ||= PayTrace::API::Request.new
-      request.set_param(:method, method)
-      if params[:billing_address]
-        params[:billing_address].name = nil if (method == CREATE_CUSTOMER && params[:transaction_id])
-      end
-      set_request_data(params, request)
-
-      gateway = PayTrace::API::Gateway.new
-      response = gateway.send_request(request)
-      unless response.has_errors?
-        values = response.values
-        @id = values["CUSTID"]
-        @customer_id = values["CUSTOMERID"]
-        self
-      else
-        nil
-      end
-    end
-
-    # :nodoc:
-    # Internal helper method; not meant to be called directly.
-    def set_request_data(params, request = nil)
-      request ||= PayTrace::API::Request.new
-      request.set_params([
-        :customer_id,
-        :new_customer_id,
-        :transaction_id,
-        :email,
-        [:customer_phone, :phone],
-        [:customer_fax, :fax],
-        :customer_password,
-        :account_number,
-        :routing_number
-        ], params)
-
-      params[:billing_address].set_request(request) if params[:billing_address]
-      params[:shipping_address].set_request(request) if params[:shipping_address]
-      params[:credit_card].set_request_data(request) if params[:credit_card]
-
-      request.set_discretionary(params[:discretionary_data])
+      PayTrace::API::Gateway.send_request(CREATE_CUSTOMER, params, [:customer_id, :transaction_id], CUSTOMER_OPTIONAL_PARAMS)
     end
   end
 end

data/lib/paytrace/debug.rb

@@ -1,4 +1,5 @@
 require 'paytrace'
+require 'minitest/autorun'
 
 module PayTrace
   # Useful helper methods for debugging.
@@ -25,6 +26,11 @@ module PayTrace
       puts ">>>>>>           #{msg}"
     end
 
+    # split a raw request string into an array of name-value tuples
+    def self.split_request_string(raw)
+      raw.split('|').map {|kv_pair| kv_pair.split('~')}
+    end
+
     # Helper method to dump a request response pair. Usage:
     # Usage: 
     #  PayTrace::Debug.trace do
@@ -54,5 +60,35 @@ module PayTrace
         config.domain = domain
       end
     end
+
+    # verify whether two requests match
+    def self.diff_requests(expected_raw, actual_raw, case_sensitive = false)
+      whats_wrong = []
+
+      expected = PayTrace::Debug.split_request_string(expected_raw).map {|tuple| case_sensitive ? tuple : [tuple[0].upcase, tuple[1]]}
+      actual = PayTrace::Debug.split_request_string(actual_raw).map {|tuple| case_sensitive ? tuple : [tuple[0].upcase, tuple[1]]}
+
+      expected_remaining = []
+      actual_extra = actual.dup
+
+      expected.each do |tuple|
+        idx = actual_extra.find_index(tuple)
+        if idx.nil?
+          expected_remaining << tuple
+        else
+          actual_extra.delete_at(idx)
+        end
+      end
+
+      expected_remaining.each do |tuple|
+        whats_wrong << "Missing expected property #{tuple[0]}~#{tuple[1]}"
+      end
+
+      actual_extra.each do |tuple|
+        whats_wrong << "Extra unexpected property #{tuple[0]}~#{tuple[1]}"
+      end
+
+      whats_wrong
+    end
   end
 end

data/lib/paytrace/email_receipt_request.rb

@@ -2,40 +2,16 @@ module PayTrace
   # Methods to request an email receipt for a transaction
   class EmailReceiptRequest
     # :nodoc:
-    TRANSACTION_METHOD = "EmailReceipt"
-    attr_accessor :email, :transaction_id, :check_id
+    EMAIL_RECEIPT_METHOD = "EmailReceipt"
     # :doc:
 
-    # Initializer. Params:
+    # Send the request. Params:
     # *:email* -- the email address to send the receipt to
     # *:transaction_id* -- the transaction ID of the transaction to email
     # *:check_id* -- the check ID of the transaction to email
     # _Note:_ only use *:transaction_id* _or_ *:check_id* -- not both.
-    def initialize(params = {})
-      email, id, id_is_check_id = false
-      @email = params[:email]
-      @transaction_id = params[:transaction_id]
-      @check_id = params[:check_id]
-    end
-
-    # :nodoc:
-    def set_request(request = nil)
-      request ||= PayTrace::API::Request.new
-      request.set_param(:method, TRANSACTION_METHOD)
-      request.set_param(:check_id, @check_id)
-      request.set_param(:transaction_id, @transaction_id)
-      request.set_param(:email, @email)
-
-      request
-    end
-    # :doc:
-
-    # Sends the request for the transaction. Accepts an existing request object, or creates one if needed.
-    def send_request(request = nil)
-      request ||= set_request
-
-      gateway = PayTrace::API::Gateway.new
-      gateway.send_request(request)
+    def self.create(params = {})
+      PayTrace::API::Gateway.send_request(EMAIL_RECEIPT_METHOD, params, [:email], [:check_id, :transaction_id])
     end
   end
 end

data/lib/paytrace/recurring_transaction.rb

@@ -4,29 +4,25 @@ module PayTrace
   # Manages recurring transactions
   class RecurringTransaction
     # :nodoc:
-    attr :id, :amount, :customer_id, :next, :total_count, :current_count, :repeat, :description
-
     CREATE_METHOD = "CreateRecur"
     DELETE_METHOD = "DeleteRecur"
     UPDATE_METHOD = "UpdateRecur"
     EXPORT_APPROVED_METHOD = "ExportCustomerRecur"
     EXPORT_SCHEDULED_METHOD = "ExportRecur"
 
-    def initialize(raw_response)
-      response_map = Hash[raw_response.split('+').map {|pair| pair.split('=')}]
-      @id = response_map["RECURID"].to_i
-      @amount = response_map["AMOUNT"].to_f
-      @customer_id = response_map["CUSTID"]
-      @next = response_map["NEXT"]
-      @total_count = response_map["TOTALCOUNT"].to_i
-      @current_count = response_map["CURRENTCOUNT"].to_i
-      @repeat = response_map["REPEAT"].to_i
-      @description = response_map["DESCRIPTION"]
-    end
-
-    def inspect
-      "<RecurringTransaction:#{@id},customer id:#{@customer_id},amount: #{@amount},next: #{@next}>"
-    end
+    RECURRING_TRANSACTION_PARAMS = [
+      :recur_id,
+      :customer_id,
+      :recur_frequency,
+      :recur_start,
+      :recur_next,
+      :recur_count,
+      :amount,
+      :transaction_type,
+      :description,
+      :recur_receipt,
+      :recur_type
+    ]
 
     # :doc:
 
@@ -36,14 +32,15 @@ module PayTrace
     # * *:customer_id* -- a customer ID to export
     # _Note:_ only supply a recurrence ID _or_ a customer ID, not both.
     def self.export_scheduled(params = {})
-      parse_response(set_request_data(EXPORT_SCHEDULED_METHOD, params))
+      response =  PayTrace::API::Gateway.send_request(EXPORT_SCHEDULED_METHOD, params, [], RECURRING_TRANSACTION_PARAMS)
+      response.parse_records('RECURRINGPAYMENT')
     end
 
     # See http://help.paytrace.com/api-exporting-a-recurring-transaction
     # Exports the single most recent recurring transaction for a given customer ID, Params: 
     # * *:customer_id* -- the customer ID to be exported for
     def self.export_approved(params = {})
-      set_request_data(EXPORT_APPROVED_METHOD, params)
+      PayTrace::API::Gateway.send_request(EXPORT_APPROVED_METHOD, params, [], RECURRING_TRANSACTION_PARAMS)
     end
 
     # See http://help.paytrace.com/api-create-recurring-transaction
@@ -58,7 +55,7 @@ module PayTrace
     # * *:recur_receipt* -- "Y" to send a receipt to the customer at each recurrence; default is "N"
     # * *:recur_type* -- default value is "C" which represents credit card number. Alternative is "A" which represents an ACH/check transaction
     def self.create(params = {})
-      parse_response(set_request_data(CREATE_METHOD, params))
+      PayTrace::API::Gateway.send_request(CREATE_METHOD, params, [], RECURRING_TRANSACTION_PARAMS)
     end
 
     # See http://help.paytrace.com/api-deleting-a-recurring-transaction
@@ -67,16 +64,8 @@ module PayTrace
     # * *:customer_id* -- a customer ID to export
     # _Note:_ only supply a recurrence ID _or_ a customer ID, not both.
     def self.delete(params = {})
-      request = PayTrace::API::Request.new
-      request.set_param(:method, DELETE_METHOD)
-      if params[:recur_id]
-        request.set_param(:recur_id, params[:recur_id])
-      else
-        request.set_param(:customer_id, params[:customer_id])
-      end
-
-      gateway = PayTrace::API::Gateway.new
-      parse_response(gateway.send_request(request))
+      fields = params.has_key?(:recur_id) ? [:recur_id] : [:customer_id]
+      response =  PayTrace::API::Gateway.send_request(DELETE_METHOD, params, [], fields)
     end
 
     # See http://help.paytrace.com/api-update-recurring-transaction
@@ -92,43 +81,7 @@ module PayTrace
     # * *:recur_receipt* -- "Y" to send a receipt to the customer at each recurrence; default is "N"
     # * *:recur_type* -- default value is "C" which represents credit card number. Alternative is "A" which represents an ACH/check transaction; _note:_ only use for check/ACH recurrences
     def self.update(params = {})
-      parse_response(set_request_data(UPDATE_METHOD, params))
-    end
-
-    # :nodoc:
-    def self.parse_response(response)
-      unless response.has_errors?
-        values = response.values
-
-        if values.has_key?("RECURRINGPAYMENT")
-          new(values["RECURRINGPAYMENT"])
-        else
-          values["RECURID"]
-        end
-      end
+      PayTrace::API::Gateway.send_request(UPDATE_METHOD, params, [], RECURRING_TRANSACTION_PARAMS)
     end
-
-    def self.set_request_data(method, params)
-      request = PayTrace::API::Request.new
-      request.set_param(:method, method)
-
-      request.set_params([
-        :recur_id,
-        :customer_id,
-        :recur_frequency,
-        :recur_start,
-        :recur_next,
-        :recur_count,
-        :amount,
-        :transaction_type,
-        :description,
-        :recur_receipt,
-        :recur_type
-        ], params)
-
-      gateway = PayTrace::API::Gateway.new
-      gateway.send_request(request)
-    end
-    # :doc:
   end
 end