= exact4r
A gem which provides access to E-xact's Web Services API, allowing the submission
of financial transactions via REST, JSON or SOAP. 

== Getting Started

To submit requests to our transaction processing service, you must first have a Gateway ID,
and a password. Test logins are as follows:

  Account 1:  :gateway_id => "A00049-01", :password => "test1"
  Account 2:  :gateway_id => "A00427-01", :password => "testus"


=1. Submit a transaction

  require 'rubygems'
  require 'exact4r'
  
  # build a purchase request
  request = EWS::Transaction::Request.new({
    :transaction_type => :purchase,
    :amount => 10.50,
    :cardholder_name => "Simon Brown",
    :cc_number => "4111111111111111",
    :cc_expiry => "1012",             # MUST be MMYY format
    :gateway_id => "XXXXXXX",         # which gateway to submit the request to
    :password => "YYYYYY"             # your password for that gateway
  })
  
  transporter = EWS::Transporter.new
  response = transporter.submit(request)  # submits using REST (XML) by default

  # submit using JSON, or
  response = transporter.submit(request, :json)

  # submit using SOAP, or
  response = transporter.submit(request, :soap)

  # submit explicitly via REST
  response = transporter.submit(request, :rest)
  
  # The response object is independent of type of transport chosen.
  # We decode the payload into a regular object
  response.transaction_tag    # 1234
  response.exact_resp_code    # "00"
  response.exact_message      # "Transaction Normal"
  response.bank_resp_code     # "00"
  response.bank_message       # "APPROVED"

=2. Find information on an existing transaction

  require 'rubygems'
  require 'exact4r'

  # build a purchase request
  request = EWS::Transaction::Request.new({
    :transaction_type => :purchase,
    :amount => 10.50,
    :cardholder_name => "Simon Brown",
    :cc_number => "4111111111111111",
    :cc_expiry => "1012",             # MUST be MMYY format
    :gateway_id => "XXXXXXX",         # which gateway to submit the request to
    :password => "YYYYYY"             # your password for that gateway
  })

  transporter = EWS::Transporter.new
  response = transporter.submit(request)  # submits using REST (XML) by default

  # you need to know the transaction tag of the transaction you are looking for
  find_request = EWS::Transaction::Request.new({
    :transaction_type => :transaction_details,
    :transaction_tag => response.transaction_tag,
    :gateway_id => "XXXXXXX",
    :password => "YYYYYY"
  })
  
  find_response = transporter.submit(find_request, :json)  # again, can choose your transport type as before
  find_response.cc_number          # 4111111111111111
  find_response.amount             # 10.50
  
=3. Re-using a Transporter

  require 'rubygems'
  require 'exact4r'

  # The transporter object can be re-used across multiple transactions, so set it up once
  # and forget about it.
  # In this example, we will continue to use E-xact's default web-service URL, but we
  # will specify a default transport_type of :soap
  transporter = EWS::Transporter.new("https://api.e-xact.com/", {:transaction_type => :soap})

  # now let's submit do a recurring seed purchase...
  rsp_req = EWS::Transaction::Request.new({
    :transaction_type => :recurring_seed_purchase,
    :amount => 12.00,
    :cardholder_name => "Simon Brown",
    :cc_number => "4111111111111111",
    :cc_expiry => "1012",
    :gateway_id => "XXXXXX",
    :password => "YYYYYY"
  })
  
  rsp_resp = transporter.submit(rsp_req)
  raise "Seed Purchase failed" unless rsp_resp.approved?

  # ...then do multiple refunds against it
  1.upto(10) do
    rf_req = EWS::Transaction::Request.new({
      :transaction_type => :tagged_refund,
      :transaction_tag => rsp_resp.transaction_tag,   # need to know which transaction we're refunding against...
      :authorization_num => rsp_resp.authorization_num,           # and its authorization_num
      :amount => 1.00,                                # refund a dollar at a time  
      :gateway_id => "XXXXXX",
      :password => "YYYYYY"
    })
    rf_resp = transporter.submit(rf_req)
    raise "Refund failed: #{rf_resp.exact_resp_code}, #{rf_resp.exact_message}" unless rf_resp.approved?
  end
  
== Rake tasks

spec
  Run all test in spec/ folder (default)

rdoc
  Generate rdoc html in doc/

gem
  Build gem