bigcharger 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 John Grimes
+
+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.markdown

@@ -0,0 +1,149 @@
+# BigCharger - eWAY Token Payments Client
+
+The idea of this project is to build a lightweight Ruby library for
+interfacing with the [eWAY Token Payments
+API](http://www.eway.com.au/Developer/eway-api/token-payments.aspx).
+
+## Installation
+
+```ruby
+gem install bigcharger
+```
+
+## Setup
+
+```ruby
+client = BigCharger.new(
+  '87654321', 
+  'test@eway.com.au', 
+  'test123'
+)
+```
+
+## Create a new customer
+
+```ruby
+client.create_customer({
+  'CustomerRef' => 'Test 123',
+  'Title' => 'Mr.',
+  'FirstName' => 'Jo',
+  'LastName' => 'Smith',
+  'Company' => 'company',
+  'JobDesc' => 'Analyst',
+  'Email' => 'test@eway.com.au',
+  'Address' => '15 Dundas Court',
+  'Suburb' => 'phillip',
+  'State' => 'act',
+  'PostCode' => '2606',
+  'Country' => 'au',
+  'Phone' => '02111111111',
+  'Mobile' => '04111111111',
+  'Fax' => '111122222',
+  'URL' => 'http://eway.com.au',
+  'Comments' => 'Comments',
+  'CCNameOnCard' => 'Jo Smith',
+  'CCNumber' => '444433XXXXXX1111',
+  'CCExpiryMonth' => '08',
+  'CCExpiryYear' => '15'
+})
+# => "9876543211000" (managedCustomerID of new customer)
+```
+
+## Process a payment
+
+```ruby
+client.process_payment(
+  9876543211000,
+  1000,
+  'INV-80251',
+  'Pants alteration'
+)
+# => {
+#   'ewayTrxnError' => '00,Transaction Approved(Test Gateway)', 
+#   'ewayTrxnStatus' => 'True', 
+#   'ewayTrxnNumber' => '10498', 
+#   'ewayReturnAmount' => '1000', 
+#   'ewayAuthCode' => '123456'
+# }
+
+# Alternatively, improve security by requiring a CVN/CVV
+client.process_payment_with_cvn(
+  9876543211000,
+  1000,
+  '123',
+  'INV-80251',
+  'Pants alteration'
+)
+```
+
+## Find a customer
+
+```ruby
+# Find a customer using the managed customer ID
+client.query_customer(9876543211000)
+# => {
+#   'ManagedCustomerID' => '9876543211000', 
+#   'CustomerRef' => 'Test 123', 
+#   'CustomerTitle' => 'Mr.', 
+#   'CustomerFirstName' => 'Jo', 
+#   'CustomerLastName' => 'Smith', 
+#   'CustomerCompany' => 'company', 
+#   'CustomerJobDesc' => nil, 
+#   'CustomerEmail' => 'test@eway.com.au', 
+#   'CustomerAddress' => '15 Dundas Court', 
+#   'CustomerSuburb' => 'phillip', 
+#   'CustomerState' => 'act', 
+#   'CustomerPostCode' => '2606', 
+#   'CustomerCountry' => 'au', 
+#   'CustomerPhone1' => '02111111111', 
+#   'CustomerPhone2' => '04111111111', 
+#   'CustomerFax' => '111122222', 
+#   'CustomerURL' => 'http://eway.com.au', 
+#   'CustomerComments' => 'Comments', 
+#   'CCName' => 'Jo Smith', 
+#   'CCNumber' => '444433XXXXXX1111', 
+#   'CCExpiryMonth' => '08', 
+#   'CCExpiryYear' => '15'
+# }
+
+# Find a customer using the reference you supplied when you created the
+# customer
+client.query_customer_by_reference('Test 123')
+```
+
+## Get list of payments for a customer
+
+```ruby
+client.query_payment(9876543211000)
+# => [
+#   {
+#     'TotalAmount' => '1000', 
+#     'Result' => '1', 
+#     'ResponseText' => 'Approved', 
+#     'TransactionDate' => '2012-02-20T00:00:00+11:00', 
+#     'ewayTrxnNumber' => '1'
+#   }, 
+#   {
+#     'TotalAmount' => '1008', 
+#     'Result' => '1', 
+#     'ResponseText' => 'Approved', 
+#     'TransactionDate' => '2012-02-20T00:00:00+11:00', 
+#     'ewayTrxnNumber' => '2'
+#   }
+# ]
+```
+
+## Update a customer
+
+```ruby
+client.update_customer(
+  9876543211000,
+  {
+    'CCNameOnCard' => 'Jo Smith',
+    'CCNumber' => '444433XXXXXX2222',
+    'CCExpiryMonth' => '06',
+    'CCExpiryYear' => '22'
+  }
+)
+# => true
+```

data/lib/bigcharger.rb

@@ -0,0 +1,21 @@
+require File.dirname(__FILE__) + '/bigcharger/config'
+require File.dirname(__FILE__) + '/bigcharger/utils'
+require File.dirname(__FILE__) + '/bigcharger/ops'
+
+class BigCharger
+  attr_accessor :logger
+
+  def initialize(customer_id, username, password, test_mode = false, logger = Logger.new('/dev/null'))
+    @credentials = { 
+      :customer_id => customer_id,
+      :username => username,
+      :password => password
+    }
+    @client = Curl::Easy.new
+    @endpoint = test_mode ? TEST_ENDPOINT : ENDPOINT
+    @logger = logger
+    set_request_defaults
+  end
+
+  class Error < Exception; end
+end

data/lib/bigcharger/config.rb

@@ -0,0 +1,32 @@
+class BigCharger
+  SOAP_NAMESPACE = 'http://schemas.xmlsoap.org/soap/envelope/'
+  SERVICE_NAMESPACE = 'https://www.eway.com.au/gateway/managedpayment'
+  ENDPOINT = 'https://www.eway.com.au/gateway/ManagedPaymentService/managedCreditCardPayment.asmx'
+  TEST_ENDPOINT = 'https://www.eway.com.au/gateway/ManagedPaymentService/test/managedCreditCardPayment.asmx'
+
+  # List of fields (with significant ordering as per WSDL) for customer 
+  # requests
+  CUSTOMER_REQUEST_FIELDS = [
+    'Title',
+    'FirstName',
+    'LastName',
+    'Address',
+    'Suburb',
+    'State',
+    'Company',
+    'PostCode',
+    'Country',
+    'Email',
+    'Fax',
+    'Phone',
+    'Mobile',
+    'CustomerRef',
+    'JobDesc',
+    'Comments',
+    'URL',
+    'CCNumber',
+    'CCNameOnCard',
+    'CCExpiryMonth',
+    'CCExpiryYear'
+  ]
+end

data/lib/bigcharger/ops.rb

@@ -0,0 +1,148 @@
+require 'nokogiri'
+require 'curb'
+
+class BigCharger
+  # Creates a new managed customer on the eWAY server.
+  # @param customer_fields Title, FirstName, LastName, Address, Suburb, 
+  #   State, Company, PostCode, Country, Email, Fax, Phone, Mobile, 
+  #   CustomerRef, JobDesc, Comments, URL, CCNumber, CCNameOnCard, 
+  #   CCExpiryMonth, CCExpiryYear
+  # @return [String] Managed customer ID of new customer.
+  def create_customer(customer_fields = {})
+    log_operation(:create_customer, customer_fields)
+    raise Error, 'customer_fields is not a Hash' unless customer_fields.class == Hash
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].CreateCustomer {
+        CUSTOMER_REQUEST_FIELDS.each do |field|
+          xml['man'].send(field, customer_fields[field]) if customer_fields[field]
+        end
+      }
+    end
+    response = post(envelope, 'CreateCustomer')
+    result = response.xpath('//man:CreateCustomerResult', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? result.text : false
+  end
+
+  # Processes a payment of a given amount for the specified customer.
+  # @param [#to_s] managed_customer_id
+  # @param [Integer] amount The amount of the payment, in cents. (e.g. 
+  #   1000 = $10)
+  # @param invoice_ref An optional field that you can use to identify 
+  #   the corresponding  invoice within your system.
+  # @param invoice_desc An optional field to describe the subject of the 
+  #   payment.
+  # @return [Hash] ewayTrxnError, ewayTrxnStatus, ewayTrxnNumber, 
+  #   ewayReturnAmount, ewayAuthCode
+  def process_payment(managed_customer_id, amount, invoice_ref = nil, invoice_desc = nil)
+    log_operation(:process_payment, managed_customer_id, amount, invoice_ref, invoice_desc)
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].ProcessPayment {
+        xml['man'].managedCustomerID managed_customer_id
+        xml['man'].amount amount
+        xml['man'].invoiceReference invoice_ref if invoice_ref
+        xml['man'].invoiceDescription invoice_desc if invoice_desc
+      }
+    end
+    response = post(envelope, 'ProcessPayment')
+    result = response.xpath('//man:ProcessPaymentResponse/man:ewayResponse', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? node_to_hash(result) : false
+  end
+
+  # Identical to {#process_payment} except that it accepts a CVN/CVV for 
+  # greater security.
+  def process_payment_with_cvn(managed_customer_id, amount, cvn = nil, invoice_ref = nil, invoice_desc = nil)
+    log_operation(:process_payment_with_cvn, managed_customer_id, amount, cvn, invoice_ref, invoice_desc)
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].ProcessPaymentWithCVN {
+        xml['man'].managedCustomerID managed_customer_id
+        xml['man'].amount amount
+        xml['man'].invoiceReference invoice_ref if invoice_ref
+        xml['man'].invoiceDescription invoice_desc if invoice_desc
+        xml['man'].cvn cvn if cvn
+      }
+    end
+    response = post(envelope, 'ProcessPaymentWithCVN')
+    result = response.xpath('//man:ProcessPaymentWithCVNResponse/man:ewayResponse', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? node_to_hash(result) : false
+  end
+
+  # Returns the eWAY record for a specific managed customer ID.
+  # @param [#to_s] managed_customer_id
+  # @return [Hash] ManagedCustomerID, CustomerRef, CustomerTitle, 
+  #   CustomerFirstName, CustomerLastName, CustomerCompany, 
+  #   CustomerJobDesc, CustomerEmail, CustomerAddress, CustomerSuburb, 
+  #   CustomerState, CustomerPostCode, CustomerCountry, CustomerPhone1, 
+  #   CustomerPhone2, CustomerFax, CustomerURL, CustomerComments
+  def query_customer(managed_customer_id)
+    log_operation(:query_customer, managed_customer_id)
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].QueryCustomer {
+        xml['man'].managedCustomerID managed_customer_id
+      }
+    end
+    response = post(envelope, 'QueryCustomer')
+    result = response.xpath('//man:QueryCustomerResult', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? node_to_hash(result) : false
+  end
+
+  # Returns the eWAY customer record with the specified customer 
+  # reference.
+  # @param [#to_s] customer_ref
+  # @return [Hash] ManagedCustomerID, CustomerRef, CustomerTitle, 
+  #   CustomerFirstName, CustomerLastName, CustomerCompany, 
+  #   CustomerJobDesc, CustomerEmail, CustomerAddress, CustomerSuburb, 
+  #   CustomerState, CustomerPostCode, CustomerCountry, CustomerPhone1, 
+  #   CustomerPhone2, CustomerFax, CustomerURL, CustomerComments
+  def query_customer_by_reference(customer_ref)
+    log_operation(:query_customer_by_reference, customer_ref)
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].QueryCustomerByReference {
+        xml['man'].CustomerReference customer_ref
+      }
+    end
+    response = post(envelope, 'QueryCustomerByReference')
+    result = response.xpath('//man:QueryCustomerByReferenceResult', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? node_to_hash(result) : false
+  end
+
+
+  # Returns all the payment records associated with a specified managed 
+  # customer ID.
+  # @param [#to_s] customer_ref
+  # @return [Array of Hashes] TotalAmount, Result, ResponseText, 
+  #   TransactionDate, ewayTrxnNumber
+  def query_payment(managed_customer_id)
+    log_operation(:query_payment, managed_customer_id)
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].QueryPayment {
+        xml['man'].managedCustomerID managed_customer_id
+      }
+    end
+    response = post(envelope, 'QueryPayment')
+    result = response.xpath('//man:QueryPaymentResult', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? node_collection_to_array(result) : false
+  end
+
+  # Update details of an eWAY customer record.
+  # @param [#to_s] managed_customer_id
+  # @param customer_fields Title, FirstName, LastName, Address, Suburb, 
+  #   State, Company, PostCode, Country, Email, Fax, Phone, Mobile, 
+  #   CustomerRef, JobDesc, Comments, URL, CCNumber, CCNameOnCard, 
+  #   CCExpiryMonth, CCExpiryYear
+  # @return [Boolean] Success or otherwise
+  def update_customer(managed_customer_id, customer_fields = {})
+    log_operation(:update_customer, managed_customer_id, customer_fields)
+    raise Error, 'customer_fields is not a Hash' unless customer_fields.class == Hash
+    envelope = wrap_in_envelope do |xml|
+      xml['man'].UpdateCustomer {
+        xml['man'].managedCustomerID managed_customer_id
+        CUSTOMER_REQUEST_FIELDS.each do |field|
+          xml['man'].send(field, customer_fields[field]) if customer_fields[field]
+        end
+      }
+    end
+    response = post(envelope, 'UpdateCustomer')
+    result = response.xpath('//man:UpdateCustomerResult', { 'man' => SERVICE_NAMESPACE }).first
+    return result ? result.text == 'true' : false
+  end
+end

data/lib/bigcharger/utils.rb

@@ -0,0 +1,115 @@
+require 'logger'
+
+class BigCharger
+  private
+
+  def set_request_defaults
+    @client.verbose = false
+    @client.url = @endpoint
+    @client.headers['Content-Type'] = 'text/xml'
+  end
+
+  def wrap_in_envelope(&block)
+    envelope = Nokogiri::XML::Builder.new do |xml|
+      xml.Envelope('xmlns:soap' => SOAP_NAMESPACE,
+          'xmlns:man' => SERVICE_NAMESPACE) {
+        xml.parent.namespace = xml.parent.namespace_definitions.find { |ns| ns.prefix == 'soap' }
+        xml['soap'].Header {
+          xml['man'].eWAYHeader {
+            xml['man'].eWAYCustomerID @credentials[:customer_id]
+            xml['man'].Username @credentials[:username]
+            xml['man'].Password @credentials[:password]
+          }
+        }
+        xml['soap'].Body {
+          yield xml
+        }
+      }
+    end
+  end
+
+  def post(envelope, action_name)
+    @client.headers['SOAPAction'] = "#{SERVICE_NAMESPACE}/#{action_name}"
+    record_request(@client, envelope.to_xml)
+    @client.http_post @last_request[:body]
+    log_last_request
+    record_response(@client)
+    log_last_response
+    check_last_response_for_faults
+    check_last_response_for_errors
+    return @last_response[:body_document]
+  end
+
+  def record_request(request, body)
+    @last_request = {}
+    @last_request[:headers] = request.headers.clone
+    @last_request[:body] = body
+  end
+
+  def record_response(response)
+    @last_response = {}
+    @last_response[:header_string] = response.header_str.clone
+    @last_response[:body] = response.body_str.clone
+    @last_response[:body_document] = Nokogiri::XML(response.body_str)
+  end
+
+  def log_operation(name, *args)
+    log_string = "BigCharger##{name} called with: "
+    log_string << args.map { |x| x.inspect }.join(', ')
+    @logger.debug log_string
+  end
+
+  def log_last_request
+    header_output = @last_request[:headers].map { |k,v| "#{k}: #{v}" }.join("\n")
+    log_string = "BigCharger - Request sent to eWAY server\n"
+    log_string << "#{header_output}\n#{@last_request[:body]}"
+    @logger.debug log_string
+  end
+
+  def log_last_response
+    body_output = @last_response[:body_document].serialize(:encoding => 'UTF-8') do |config|
+      config.format.as_xml
+    end
+    log_string = "BigCharger - Response received from eWAY server\n"
+    log_string << "#{@last_response[:header_string]}\n#{body_output}"
+    @logger.debug log_string
+  end
+
+  def check_last_response_for_faults
+    faults = @last_response[:body_document].xpath('//soap:Fault', { 'soap' => SOAP_NAMESPACE })
+    unless faults.empty?
+      fault = faults.first
+      fault_code = fault.xpath('faultcode').first.text
+      fault_message = fault.xpath('faultstring').first.text
+      raise Error, "eWAY server responded with \"#{fault_message}\" (#{fault_code})"
+    end
+  end
+
+  def check_last_response_for_errors
+    status_info = @last_response[:header_string].match(/HTTP\/[\d\.]+ (\d{3}) ([\w\s]+)[\r\n]/)
+    status_code, status_reason = status_info[1].strip, status_info[2].strip
+    unless ['200', '100'].include? status_code
+      raise Error, "eWAY server responded with \"#{status_reason}\" (#{status_code})"
+    end
+  end
+
+  def node_to_hash(node)
+    hash = {}
+    node.children.each do |node|
+      if node.type == Nokogiri::XML::Node::ELEMENT_NODE
+        hash[node.name] = node.text.empty? ? nil : node.text
+      end
+    end
+    return hash
+  end
+
+  def node_collection_to_array(node)
+    array = []
+    node.children.each do |node|
+      if node.type == Nokogiri::XML::Node::ELEMENT_NODE
+        array << node_to_hash(node)
+      end
+    end
+    return array
+  end
+end