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
This gateway requires that a valid username and password be passed in the options
hash.
Required Options¶ ↑
-
:username
-
:password
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
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
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
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
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
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
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
# 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
# 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
# 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
# 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
# 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
# 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
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 293 def message_from(response) MESSAGES.fetch(response['response_code'].to_i, false) || response['message'] end
# 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
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 297 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
# File lib/active_merchant/billing/gateways/evo_ca.rb, line 271 def success?(response) response['response'].to_i == APPROVED end