class ActiveMerchant::Billing::EvoCaGateway

EVO Canada payment gateway.

EVO returns two different identifiers for most transactions, the authcode and the transactionid. Since transactionid is used more often (i.e. for {#capture}, {#refund}, {#void} and {#update}) we store it in the Response#authorization attribute. The authcode from the merchant account is accessible via {Response#params}.

Two different but related response messages are also returned from EVO. The message indicated by EVO's response_code parameter is returned as {Response#message} (Those messages can be seen in the {MESSAGES} hash.) The other, shorter message is available via {Response#params}.

It's recommended to save the contents of the {Response#params} in your transaction log for future reference.

Sample Use

gateway = ActiveMerchant::Billing::EvoCaGateway.new(username: 'demo', password: 'password')

response = gateway.authorize(1000, credit_card, options)

puts response.authorization          # the transactionid
puts response.params['authcode']     # the authcode from the merchant account
puts response.message                # the 'pretty' response message
puts response.params['responsetext'] # the 'terse' response message

gateway.capture(1000, response.authorization)
gateway.update(response.authorization, shipping_carrier: 'fedex')
gateway.refund(500, response.authorization)

Constants

ERROR
MESSAGES

Public Class Methods

new(options = {}) click to toggle source

This gateway requires that a valid username and password be passed in the options hash.

Required Options

  • :username

  • :password

Calls superclass method ActiveMerchant::Billing::Gateway::new
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 89
def initialize(options = {})
  requires!(options, :username, :password)
  super
end

Public Instance Methods

authorize(money, credit_card, options = {}) click to toggle source

Transaction authorizations are authorized immediately but are not flagged for settlement. These transactions must be flagged for settlement using the capture transaction type. Authorizations typically remain activate for three to seven business days.

Payment source must be a {CreditCard}.

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 123
def authorize(money, credit_card, options = {})
  post = {}
  add_invoice(post, options)
  add_order(post, options)
  add_paymentmethod(post, credit_card)
  add_address(post, options)
  add_customer_data(post, options)
  commit('auth', money, post)
end
capture(money, authorization, options = {}) click to toggle source

Transaction captures flag existing authorizations for settlement. Only authorizations can be captured. Captures can be submitted for an amount equal to or less than the original authorization.

The authorization parameter is the transaction ID, retrieved from Response#authorization. See EvoCaGateway#purchase for the options.

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 140
def capture(money, authorization, options = {})
  post = {
    :amount         => amount(money),
    :transactionid  => authorization
  }
  add_order(post, options)
  commit('capture', money, post)
end
credit(money, credit_card, options = {}) click to toggle source

Transaction credits apply a negative amount to the cardholder's card. In most situations credits are disabled as transaction refunds should be used instead.

Note that this is different from a {#refund} (which is usually what you'll be looking for).

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 166
def credit(money, credit_card, options = {})
  post = {}
  add_invoice(post, options)
  add_order(post, options)
  add_paymentmethod(post, credit_card)
  add_address(post, options)
  add_customer_data(post, options)
  commit('credit', money, post)
end
purchase(money, credit_card_or_check, options = {}) click to toggle source

Transaction sales are submitted and immediately flagged for settlement. These transactions will automatically be settled.

Payment source can be either a {CreditCard} or {Check}.

Additional Options

In addition to the standard options, this gateway supports

  • :tracking_number - Shipping tracking number

  • :shipping_carrier - ups/fedex/dhl/usps

  • :po_number - Purchase order

  • :tax - Tax amount

  • :shipping - Shipping cost

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 107
def purchase(money, credit_card_or_check, options = {})
  post = {}
  add_invoice(post, options)
  add_order(post, options)
  add_paymentmethod(post, credit_card_or_check)
  add_address(post, options)
  add_customer_data(post, options)
  commit('sale', money, post)
end
refund(money, identification) click to toggle source

Transaction refunds will reverse a previously settled transaction. If the transaction has not been settled, it must be voided instead of refunded.

The identification parameter is the transaction ID, retrieved from {Response#authorization}.

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 155
def refund(money, identification)
  post = {:transactionid => identification}
  commit('refund', money, post)
end
update(identification, options) click to toggle source

Transaction updates can be used to update previous transactions with specific order information, such as a tracking number and shipping carrier. See EvoCaGateway#purchase for options.

The identification parameter is the transaction ID, retrieved from {Response#authorization}.

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 194
def update(identification, options)
  post = {:transactionid => identification}
  add_order(post, options)
  commit('update', nil, post)
end
void(identification) click to toggle source

Transaction voids will cancel an existing sale or captured authorization. In addition, non-captured authorizations can be voided to prevent any future capture. Voids can only occur if the transaction has not been settled.

The identification parameter is the transaction ID, retrieved from {Response#authorization}.

# File lib/active_merchant/billing/gateways/evo_ca.rb, line 183
def void(identification)
  post = {:transactionid => identification}
  commit('void', nil, post)
end

Private Instance Methods

add_address(post, options) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 207
def add_address(post, options)
  if address = options[:billing_address] || options[:address]
    post[:firstname]    = address[:first_name]
    post[:lastname]     = address[:last_name]
    post[:address1]     = address[:address1]
    post[:address2]     = address[:address2]
    post[:company]      = address[:company]
    post[:phone]        = address[:phone]
    post[:city]         = address[:city]
    post[:state]        = address[:state]
    post[:zip]          = address[:zip]
    post[:country]      = address[:country]
  end

  if address = options[:shipping_address]
    post[:shipping_firstname]   = address[:first_name]
    post[:shipping_lastname]    = address[:last_name]
    post[:shipping_address1]    = address[:address1]
    post[:shipping_address2]    = address[:address2]
    post[:shipping_company]     = address[:company]
    post[:shipping_zip]         = address[:zip]
    post[:shipping_city]        = address[:city]
    post[:shipping_state]       = address[:state]
    post[:shipping_country]     = address[:country]
  end
end
add_customer_data(post, options) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 202
def add_customer_data(post, options)
  post[:email]      = options[:email]
  post[:ipaddress]  = options[:ip]
end
add_invoice(post, options) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 240
def add_invoice(post, options)
  post[:orderdescription] = options[:description]
  post[:ponumber]         = options[:po_number]
  post[:shipping]         = amount(options[:shipping])
  post[:tax]              = amount(options[:tax])
end
add_order(post, options) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 234
def add_order(post, options)
  post[:orderid]          = options[:order_id]
  post[:tracking_number]  = options[:tracking_number]
  post[:shipping_carrier] = options[:shipping_carrier]
end
add_paymentmethod(post, payment) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 247
def add_paymentmethod(post, payment)
  if card_brand(payment)=='check'
    post[:payment]              = 'check'
    post[:checkname]            = payment.name
    post[:checkaba]             = payment.routing_number
    post[:checkaccount]         = payment.account_number
    post[:account_holder_type]  = payment.account_holder_type
    post[:account_type]         = payment.account_type
  else
    post[:payment]  = 'creditcard'
    post[:ccnumber] = payment.number
    post[:ccexp]    = "#{format(payment.month, :two_digits)}#{format(payment.year, :two_digits)}"
    post[:cvv]      = payment.verification_value
  end
end
commit(action, money, parameters) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 275
def commit(action, money, parameters)
  parameters[:amount] = amount(money) unless action == 'void'

  data = ssl_post self.live_url, post_data(action, parameters)
  response = parse(data)
  message = message_from(response)

  Response.new(success?(response), message, response,
    :test          => test?,
    :authorization => response['transactionid'],
    :avs_result    => { :code => response['avsresponse'] },
    :cvv_result    => response['cvvresponse']
  )
end
message_from(response) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 290
def message_from(response)
  MESSAGES.fetch(response['response_code'].to_i, false) || response['message']
end
parse(body) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 263
def parse(body)
  fields = {}
  CGI::parse(body).each do |k, v|
    fields[k.to_s] = v.kind_of?(Array) ? v[0] : v
  end
  fields
end
post_data(action, parameters = {}) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 294
def post_data(action, parameters = {})
  post = {:type => action}

  if test?
    post[:username] = 'demo'
    post[:password] = 'password'
  else
    post[:username] = options[:username]
    post[:password] = options[:password]
  end
  post.merge(parameters).collect { |key, value| "#{key}=#{CGI.escape(value.to_s)}" unless value.nil? }.compact.join('&')
end
success?(response) click to toggle source
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 271
def success?(response)
  response['response'].to_i == APPROVED
end