class ActiveMerchant::Billing::TrustCommerceGateway

TO USE: First, make sure you have everything setup correctly and all of your dependencies in place with:

require 'rubygems'
require 'active_merchant'

ActiveMerchant expects amounts to be Integer values in cents

tendollar = 1000

Next, create a credit card object using a TC approved test card.

creditcard = ActiveMerchant::Billing::CreditCard.new(
  :number => '4111111111111111',
  :month => 8,
  :year => 2006,
  :first_name => 'Longbob',
  :last_name => 'Longsen'
)

To finish setting up, create the active_merchant object you will be using, with the TrustCommerce gateway. If you have a functional TrustCommerce account, replace login and password with your account info. Otherwise the defaults will work for testing.

gateway = ActiveMerchant::Billing::Base.gateway(:trust_commerce).new(:login => "TestMerchant", :password => "password")

Now we are ready to process our transaction

response = gateway.purchase(tendollar, creditcard)

Sending a transaction to TrustCommerce with active_merchant returns a Response object, which consistently allows you to:

1) Check whether the transaction was successful

response.success?

2) Retrieve any message returned by TrustCommerce, either a “transaction was successful” note or an explanation of why the transaction was rejected.

response.message

3) Retrieve and store the unique transaction ID returned by Trust Commerece, for use in referencing the transaction in the future.

response.params["transid"]

For higher performance and failover with the TrustCommerceGateway you can install the TCLink library from www.trustcommerce.com/tclink.html. Follow the instructions available there to get it working on your system. ActiveMerchant will automatically use tclink if available.

The TCLink library has the following added benefits:

* Good transaction times. Transaction duration under 1.2 seconds are common.
* Fail-over to geographically distributed servers for extreme reliability

Once it is installed, you should be able to make sure that it is visible to your ruby install by opening irb and typing “require ‘tclink’”, which should return “true”.

This should be enough to get you started with Trust Commerce and active_merchant. For further information, review the methods below and the rest of active_merchant’s documentation, as well as Trust Commerce’s user and developer documentation.

Constants

BADDATA_CODES
DECLINE_CODES
ERROR_CODES
SUCCESS_TYPES
TEST_LOGIN
TEST_PASSWORD
VOIDABLE_ACTIONS

Public Class Methods

new(options = {}) click to toggle source

Creates a new TrustCommerceGateway

The gateway requires that a valid login and password be passed in the options hash.

Options

  • :login – The TrustCommerce account login.

  • :password – The TrustCommerce account password.

  • :test => true or false – Perform test transactions

Test Account Credentials

  • :login – TestMerchant

  • :password – password

Calls superclass method ActiveMerchant::Billing::Gateway::new
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 133
def initialize(options = {})
  requires!(options, :login, :password)

  super
end

Public Instance Methods

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

authorize() is the first half of the preauth(authorize)/postauth(capture) model. The TC API docs call this preauth, we preserve active_merchant’s nomenclature of authorize() for consistency with the rest of the library. This method simply checks to make sure funds are available for a transaction, and returns a transid that can be used later to postauthorize (capture) the funds.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 152
def authorize(money, creditcard_or_billing_id, options = {})
  parameters = {
    amount: amount(money)
  }

  add_order_id(parameters, options)
  add_aggregator(parameters, options)
  add_customer_data(parameters, options)
  add_payment_source(parameters, creditcard_or_billing_id)
  add_addresses(parameters, options)
  add_custom_fields(parameters, options)

  commit('preauth', parameters)
end
capture(money, authorization, options = {}) click to toggle source

capture() is the second half of the preauth(authorize)/postauth(capture) model. The TC API docs call this postauth, we preserve active_merchant’s nomenclature of capture() for consistency with the rest of the library. To process a postauthorization with TC, you need an amount in cents or a money object, and a TC transid.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 187
def capture(money, authorization, options = {})
  transaction_id, = split_authorization(authorization)
  parameters = {
    amount: amount(money),
    transid: transaction_id
  }
  add_aggregator(parameters, options)
  add_custom_fields(parameters, options)

  commit('postauth', parameters)
end
credit(money, identification, options = {}) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 215
def credit(money, identification, options = {})
  ActiveMerchant.deprecated CREDIT_DEPRECATION_MESSAGE
  refund(money, identification, options)
end
purchase(money, creditcard_or_billing_id, options = {}) click to toggle source

purchase() is a simple sale. This is one of the most common types of transactions, and is extremely simple. All that you need to process a purchase are an amount in cents or a money object and a creditcard object or billingid string.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 169
def purchase(money, creditcard_or_billing_id, options = {})
  parameters = {
    amount: amount(money)
  }

  add_order_id(parameters, options)
  add_aggregator(parameters, options)
  add_customer_data(parameters, options)
  add_payment_source(parameters, creditcard_or_billing_id)
  add_addresses(parameters, options)
  add_custom_fields(parameters, options)

  commit('sale', parameters)
end
recurring(money, creditcard, options = {}) click to toggle source

recurring() a TrustCommerce account that is activated for Citadel, TrustCommerce’s hosted customer billing info database.

Recurring billing uses the same TC action as a plain-vanilla ‘store’, but we have a separate method for clarity. It can be called like store, with the addition of a required ‘periodicity’ parameter:

The parameter :periodicity should be specified as either :bimonthly, :monthly, :biweekly, :weekly, :yearly or :daily

gateway.recurring(tendollar, creditcard, :periodicity => :weekly)

You can optionally specify how long you want payments to continue using ‘payments’

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 268
def recurring(money, creditcard, options = {})
  ActiveMerchant.deprecated RECURRING_DEPRECATION_MESSAGE

  requires!(options, %i[periodicity bimonthly monthly biweekly weekly yearly daily])

  cycle =
    case options[:periodicity]
    when :monthly
      '1m'
    when :bimonthly
      '2m'
    when :weekly
      '1w'
    when :biweekly
      '2w'
    when :yearly
      '1y'
    when :daily
      '1d'
    end

  parameters = {
    amount: amount(money),
    cycle: cycle,
    verify: options[:verify] || 'y',
    billingid: options[:billingid] || nil,
    payments: options[:payments] || nil
  }

  add_creditcard(parameters, creditcard)

  commit('store', parameters)
end
refund(money, identification, options = {}) click to toggle source

refund() allows you to return money to a card that was previously billed. You need to supply the amount, in cents or a money object, that you want to refund, and a TC transid for the transaction that you are refunding.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 201
def refund(money, identification, options = {})
  transaction_id, = split_authorization(identification)

  parameters = {
    amount: amount(money),
    transid: transaction_id
  }

  add_aggregator(parameters, options)
  add_custom_fields(parameters, options)

  commit('credit', parameters)
end
scrub(transcript) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 335
def scrub(transcript)
  transcript.
    gsub(%r((Authorization: Basic )\w+), '\1[FILTERED]').
    gsub(%r((&?cc=)\d*(&?)), '\1[FILTERED]\2').
    gsub(%r((&?password=)[^&]+(&?)), '\1[FILTERED]\2').
    gsub(%r((&?cvv=)\d*(&?)), '\1[FILTERED]\2').
    gsub(%r((&?account=)\d*(&?)), '\1[FILTERED]\2')
end
store(creditcard, options = {}) click to toggle source

store() requires a TrustCommerce account that is activated for Citadel. You can call it with a credit card and a billing ID you would like to use to reference the stored credit card info for future captures. Use ‘verify’ to specify whether you want to simply store the card in the DB, or you want TC to verify the data first.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 306
def store(creditcard, options = {})
  parameters = {
    verify: options[:verify] || 'y',
    billingid: options[:billingid] || options[:billing_id] || nil
  }

  add_creditcard(parameters, creditcard)
  add_addresses(parameters, options)
  add_custom_fields(parameters, options)

  commit('store', parameters)
end
supports_scrubbing() click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 331
def supports_scrubbing
  true
end
test?() click to toggle source
Calls superclass method ActiveMerchant::Billing::Gateway#test?
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 143
def test?
  ((@options[:login] == TEST_LOGIN && @options[:password] == TEST_PASSWORD) || super)
end
unstore(identification, options = {}) click to toggle source

To unstore a creditcard stored in Citadel using store() or recurring(), all that is required is the billing id. When you run unstore() the information will be removed and a Response object will be returned indicating the success of the action.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 321
def unstore(identification, options = {})
  parameters = {
    billingid: identification
  }

  add_custom_fields(parameters, options)

  commit('unstore', parameters)
end
verify(credit_card, options = {}) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 251
def verify(credit_card, options = {})
  parameters = {}
  add_creditcard(parameters, credit_card)
  commit('verify', parameters)
end
void(authorization, options = {}) click to toggle source

void() clears an existing authorization and releases the reserved fund s back to the cardholder. The TC API refers to this transaction as a reversal. After voiding, you will no longer be able to capture funds from this authorization. TrustCommerce seems to always return a status of “accepted” even if the transid you are trying to deauthorize has already been captured. Note: Your account needs to be configured by TrustCommerce to allow for reversal transactions before you can use this method.

void() is also used to to cancel a capture (postauth), purchase (sale), or refund (credit) or a before it is sent for settlement.

NOTE: AMEX preauth’s cannot be reversed. If you want to clear it more quickly than the automatic expiration (7-10 days), you will have to capture it and then immediately issue a credit for the same amount which should clear the customers credit card with 48 hours according to TC.

# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 237
def void(authorization, options = {})
  transaction_id, original_action = split_authorization(authorization)
  action = (VOIDABLE_ACTIONS - ['preauth']).include?(original_action) ? 'void' : 'reversal'

  parameters = {
    transid: transaction_id
  }

  add_aggregator(parameters, options)
  add_custom_fields(parameters, options)

  commit(action, parameters)
end

Private Instance Methods

add_addresses(params, options) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 398
def add_addresses(params, options)
  address = options[:billing_address] || options[:address]

  if address
    params[:address1]  = address[:address1] unless address[:address1].blank?
    params[:address2]  = address[:address2] unless address[:address2].blank?
    params[:city]      = address[:city]     unless address[:city].blank?
    params[:state]     = address[:state]    unless address[:state].blank?
    params[:zip]       = address[:zip]      unless address[:zip].blank?
    params[:country]   = address[:country]  unless address[:country].blank?
    params[:avs]       = 'n'
  end

  if shipping_address = options[:shipping_address]
    params[:shipto_name]     = shipping_address[:name]     unless shipping_address[:name].blank?
    params[:shipto_address1] = shipping_address[:address1] unless shipping_address[:address1].blank?
    params[:shipto_address2] = shipping_address[:address2] unless shipping_address[:address2].blank?
    params[:shipto_city]     = shipping_address[:city]     unless shipping_address[:city].blank?
    params[:shipto_state]    = shipping_address[:state]    unless shipping_address[:state].blank?
    params[:shipto_zip]      = shipping_address[:zip]      unless shipping_address[:zip].blank?
    params[:shipto_country]  = shipping_address[:country]  unless shipping_address[:country].blank?
  end
end
add_aggregator(params, options) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 352
def add_aggregator(params, options)
  if @options[:aggregator_id] || application_id != Gateway.application_id
    params[:aggregators] = 1
    params[:aggregator1] = @options[:aggregator_id] || application_id
  end
end
add_billing_id(params, billingid) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 389
def add_billing_id(params, billingid)
  params[:billingid] = billingid
end
add_check(params, check) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 369
def add_check(params, check)
  params[:media] = 'ach'
  params[:routing] = check.routing_number
  params[:account] = check.account_number
  params[:savings] = 'y' if check.account_type == 'savings'
  params[:name] = check.name
end
add_creditcard(params, creditcard) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 377
def add_creditcard(params, creditcard)
  params[:media]     = 'cc'
  params[:name]      = creditcard.name
  params[:cc]        = creditcard.number
  params[:exp]       = expdate(creditcard)
  params[:cvv]       = creditcard.verification_value if creditcard.verification_value?
end
add_custom_fields(params, options) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 346
def add_custom_fields(params, options)
  options[:custom_fields]&.each do |key, value|
    params[key.to_sym] = value
  end
end
add_customer_data(params, options) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 393
def add_customer_data(params, options)
  params[:email] = options[:email] unless options[:email].blank?
  params[:ip] = options[:ip] unless options[:ip].blank?
end
add_order_id(params, options) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 385
def add_order_id(params, options)
  params[:ticket] = options[:order_id] unless options[:order_id].blank?
end
add_payment_source(params, source) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 359
def add_payment_source(params, source)
  if source.is_a?(String)
    add_billing_id(params, source)
  elsif card_brand(source) == 'check'
    add_check(params, source)
  else
    add_creditcard(params, source)
  end
end
authorization_from(action, data) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 488
def authorization_from(action, data)
  case action
  when 'store'
    data['billingid']
  when *VOIDABLE_ACTIONS
    "#{data['transid']}|#{action}"
  else
    data['transid']
  end
end
clean_and_stringify_params(parameters) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 422
def clean_and_stringify_params(parameters)
  # TCLink wants us to send a hash with string keys, and activemerchant pushes everything around with
  # symbol keys. Before sending our input to TCLink, we convert all our keys to strings and dump the symbol keys.
  # We also remove any pairs with nil values, as these confuse TCLink.
  parameters.keys.reverse_each do |key|
    parameters[key.to_s] = parameters[key] if parameters[key]
    parameters.delete(key)
  end
end
commit(action, parameters) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 436
def commit(action, parameters)
  parameters[:custid]      = @options[:login]
  parameters[:password]    = @options[:password]
  parameters[:demo]        = test? ? 'y' : 'n'
  parameters[:action]      = action

  clean_and_stringify_params(parameters)

  data = if tclink?
           TCLink.send(parameters)
         else
           parse(ssl_post(self.live_url, post_data(parameters)))
         end

  # to be considered successful, transaction status must be either "approved" or "accepted"
  success = SUCCESS_TYPES.include?(data['status'])
  message = message_from(data)
  Response.new(
    success,
    message,
    data,
    test: test?,
    authorization: authorization_from(action, data),
    cvv_result: data['cvv'],
    avs_result: { code: data['avs'] }
  )
end
message_from(data) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 475
def message_from(data)
  case data['status']
  when 'decline'
    return DECLINE_CODES[data['declinetype']]
  when 'baddata'
    return BADDATA_CODES[data['error']]
  when 'error'
    return ERROR_CODES[data['errortype']]
  else
    return 'The transaction was successful'
  end
end
parse(body) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 464
def parse(body)
  results = {}

  body.split(/\n/).each do |pair|
    key, val = pair.split(/=/)
    results[key] = val
  end

  results
end
post_data(parameters) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 432
def post_data(parameters)
  parameters.collect { |key, value| "#{key}=#{CGI.escape(value.to_s)}" }.join('&')
end
split_authorization(authorization) click to toggle source
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 499
def split_authorization(authorization)
  authorization&.split('|')
end