Class: ActiveMerchant::Billing::TrustCommerceGateway

Inherits:
Gateway
  • Object
show all
Defined in:
lib/active_merchant/billing/gateways/trust_commerce.rb

Overview

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.

Constant Summary collapse

SUCCESS_TYPES = 
%w[approved accepted]
DECLINE_CODES = 
{
  'decline'       => 'The credit card was declined',
  'avs'           => 'AVS failed; the address entered does not match the billing address on file at the bank',
  'cvv'           => 'CVV failed; the number provided is not the correct verification number for the card',
  'call'          => 'The card must be authorized manually over the phone',
  'expiredcard'   => 'Issuer was not certified for card verification',
  'carderror'     => 'Card number is invalid',
  'authexpired'   => 'Attempt to postauth an expired (more than 14 days old) preauth',
  'fraud'         => 'CrediGuard fraud score was below requested threshold',
  'blacklist'     => 'CrediGuard blacklist value was triggered',
  'velocity'      => 'CrediGuard velocity control value was triggered',
  'dailylimit'    => 'Daily limit in transaction count or amount as been reached',
  'weeklylimit'   => 'Weekly limit in transaction count or amount as been reached',
  'monthlylimit'  => 'Monthly limit in transaction count or amount as been reached'
}
BADDATA_CODES = 
{
  'missingfields'       => 'One or more parameters required for this transaction type were not sent',
  'extrafields'         => 'Parameters not allowed for this transaction type were sent',
  'badformat'           => 'A field was improperly formatted, such as non-digit characters in a number field',
  'badlength'           => 'A field was longer or shorter than the server allows',
  'merchantcantaccept'  => "The merchant can't accept data passed in this field",
  'mismatch'            => 'Data in one of the offending fields did not cross-check with the other offending field'
}
ERROR_CODES = 
{
  'cantconnect'   => "Couldn't connect to the TrustCommerce gateway",
  'dnsfailure'    => 'The TCLink software was unable to resolve DNS hostnames',
  'linkfailure'   => 'The connection was established, but was severed before the transaction could complete',
  'failtoprocess' => 'The bank servers are offline and unable to authorize transactions'
}
TEST_LOGIN = 
'TestMerchant'
TEST_PASSWORD = 
'password'
VOIDABLE_ACTIONS = 
%w(preauth sale postauth credit)

Constants inherited from Gateway

Gateway::CREDIT_DEPRECATION_MESSAGE, Gateway::RECURRING_DEPRECATION_MESSAGE, Gateway::STANDARD_ERROR_CODE

Instance Attribute Summary

Attributes inherited from Gateway

#options

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Gateway

#add_field_to_post_if_present, #add_fields_to_post_if_present, #card_brand, card_brand, #generate_unique_id, inherited, #supported_countries, supported_countries, supported_countries=, supports?, #supports_network_tokenization?, #supports_scrubbing?

Methods included from CreditCardFormatting

#expdate, #format

Methods included from PostsData

included, #raw_ssl_request, #ssl_get, #ssl_post, #ssl_request

Constructor Details

#initialize(options = {}) ⇒ TrustCommerceGateway

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



133
134
135
136
137
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 133

def initialize(options = {})
  requires!(options, :login, :password)

  super
end

Class Method Details

.tclink? ⇒ Boolean

Returns:

  • (Boolean) 


115
116
117
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 115

def self.tclink?
  defined?(TCLink)
end

Instance Method Details

#authorize(money, creditcard_or_billing_id, options = {}) ⇒ Object

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.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# 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 = {}) ⇒ Object

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.



187
188
189
190
191
192
193
194
195
196
197
 
# 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 = {}) ⇒ Object 



215
216
217
218
 
# 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 = {}) ⇒ Object

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.



169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# 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 = {}) ⇒ Object

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’



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 262

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 = {}) ⇒ Object

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.



201
202
203
204
205
206
207
208
209
210
211
212
213
 
# 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) ⇒ Object 



329
330
331
332
333
334
335
336
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 329

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 = {}) ⇒ Object

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.



300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 300

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 ⇒ Object 



325
326
327
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 325

def supports_scrubbing
  true
end

#tclink? ⇒ Boolean

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 139

def tclink?
  self.class.tclink?
end

#test? ⇒ Boolean

Returns:

  • (Boolean) 


143
144
145
 
# 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 = {}) ⇒ Object

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.



315
316
317
318
319
320
321
322
323
 
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 315

def unstore(identification, options = {})
  parameters = {
    billingid: identification
  }

  add_custom_fields(parameters, options)

  commit('unstore', parameters)
end

#void(authorization, options = {}) ⇒ Object

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.



237
238
239
240
241
242
243
244
245
246
247
248
249
 
# 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