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.
Creates a new TrustCommerceGateway
The gateway requires that a valid login and password be passed in the options hash.
:login — The TrustCommerce account login.
:password — The TrustCommerce account password.
:test => true or false — Perform test transactions
:login — TestMerchant
:password — password
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 131 131: def initialize(options = {}) 132: requires!(options, :login, :password) 133: 134: @options = options 135: super 136: end
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 181 181: def capture(money, authorization, options = {}) 182: parameters = { 183: :amount => amount(money), 184: :transid => authorization, 185: } 186: 187: commit('postauth', parameters) 188: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 201 201: def credit(money, identification, options = {}) 202: deprecated CREDIT_DEPRECATION_MESSAGE 203: refund(money, identification, options) 204: end
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 166 166: def purchase(money, creditcard_or_billing_id, options = {}) 167: parameters = { 168: :amount => amount(money), 169: } 170: 171: add_order_id(parameters, options) 172: add_customer_data(parameters, options) 173: add_payment_source(parameters, creditcard_or_billing_id) 174: add_addresses(parameters, options) 175: commit('sale', parameters) 176: end
recurring() a TrustCommerce account that is activated for Citatdel, 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 239 239: def recurring(money, creditcard, options = {}) 240: requires!(options, [:periodicity, :bimonthly, :monthly, :biweekly, :weekly, :yearly, :daily] ) 241: 242: cycle = case options[:periodicity] 243: when :monthly 244: '1m' 245: when :bimonthly 246: '2m' 247: when :weekly 248: '1w' 249: when :biweekly 250: '2w' 251: when :yearly 252: '1y' 253: when :daily 254: '1d' 255: end 256: 257: parameters = { 258: :amount => amount(money), 259: :cycle => cycle, 260: :verify => options[:verify] || 'y', 261: :billingid => options[:billingid] || nil, 262: :payments => options[:payments] || nil, 263: } 264: 265: add_creditcard(parameters, creditcard) 266: 267: commit('store', parameters) 268: end
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 192 192: def refund(money, identification, options = {}) 193: parameters = { 194: :amount => amount(money), 195: :transid => identification 196: } 197: 198: commit('credit', parameters) 199: end
store() requires a TrustCommerce account that is activated for Citatdel. 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 274 274: def store(creditcard, options = {}) 275: parameters = { 276: :verify => options[:verify] || 'y', 277: :billingid => options[:billingid] || options[:billing_id] || nil, 278: } 279: 280: add_creditcard(parameters, creditcard) 281: add_addresses(parameters, options) 282: commit('store', parameters) 283: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 138 138: def tclink? 139: self.class.tclink? 140: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 142 142: def test? 143: @options[:login] == TEST_LOGIN && 144: @options[:password] == TEST_PASSWORD || @options[:test] || super 145: end
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 287 287: def unstore(identification, options = {}) 288: parameters = { 289: :billingid => identification, 290: } 291: 292: commit('unstore', parameters) 293: end
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.
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 220 220: def void(authorization, options = {}) 221: parameters = { 222: :transid => authorization, 223: } 224: 225: commit('reversal', parameters) 226: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 332 332: def add_addresses(params, options) 333: address = options[:billing_address] || options[:address] 334: 335: if address 336: params[:address1] = address[:address1] unless address[:address1].blank? 337: params[:address2] = address[:address2] unless address[:address2].blank? 338: params[:city] = address[:city] unless address[:city].blank? 339: params[:state] = address[:state] unless address[:state].blank? 340: params[:zip] = address[:zip] unless address[:zip].blank? 341: params[:country] = address[:country] unless address[:country].blank? 342: params[:avs] = 'n' 343: end 344: 345: if shipping_address = options[:shipping_address] 346: params[:shipto_name] = shipping_address[:name] unless shipping_address[:name].blank? 347: params[:shipto_address1] = shipping_address[:address1] unless shipping_address[:address1].blank? 348: params[:shipto_address2] = shipping_address[:address2] unless shipping_address[:address2].blank? 349: params[:shipto_city] = shipping_address[:city] unless shipping_address[:city].blank? 350: params[:shipto_state] = shipping_address[:state] unless shipping_address[:state].blank? 351: params[:shipto_zip] = shipping_address[:zip] unless shipping_address[:zip].blank? 352: params[:shipto_country] = shipping_address[:country] unless shipping_address[:country].blank? 353: end 354: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 323 323: def add_billing_id(params, billingid) 324: params[:billingid] = billingid 325: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 311 311: def add_creditcard(params, creditcard) 312: params[:media] = "cc" 313: params[:name] = creditcard.name 314: params[:cc] = creditcard.number 315: params[:exp] = expdate(creditcard) 316: params[:cvv] = creditcard.verification_value if creditcard.verification_value? 317: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 327 327: def add_customer_data(params, options) 328: params[:email] = options[:email] unless options[:email].blank? 329: params[:ip] = options[:ip] unless options[:ip].blank? 330: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 319 319: def add_order_id(params, options) 320: params[:ticket] = options[:order_id] unless options[:order_id].blank? 321: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 296 296: def add_payment_source(params, source) 297: if source.is_a?(String) 298: add_billing_id(params, source) 299: else 300: add_creditcard(params, source) 301: end 302: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 356 356: def clean_and_stringify_params(parameters) 357: # TCLink wants us to send a hash with string keys, and activemerchant pushes everything around with 358: # symbol keys. Before sending our input to TCLink, we convert all our keys to strings and dump the symbol keys. 359: # We also remove any pairs with nil values, as these confuse TCLink. 360: parameters.keys.reverse.each do |key| 361: if parameters[key] 362: parameters[key.to_s] = parameters[key] 363: end 364: parameters.delete(key) 365: end 366: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 372 372: def commit(action, parameters) 373: parameters[:custid] = @options[:login] 374: parameters[:password] = @options[:password] 375: parameters[:demo] = test? ? 'y' : 'n' 376: parameters[:action] = action 377: 378: clean_and_stringify_params(parameters) 379: 380: data = if tclink? 381: TCLink.send(parameters) 382: else 383: parse( ssl_post(URL, post_data(parameters)) ) 384: end 385: 386: # to be considered successful, transaction status must be either "approved" or "accepted" 387: success = SUCCESS_TYPES.include?(data["status"]) 388: message = message_from(data) 389: Response.new(success, message, data, 390: :test => test?, 391: :authorization => data["transid"], 392: :cvv_result => data["cvv"], 393: :avs_result => { :code => data["avs"] } 394: ) 395: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 304 304: def expdate(creditcard) 305: year = sprintf("%.4i", creditcard.year) 306: month = sprintf("%.2i", creditcard.month) 307: 308: "#{month}#{year[-2..-1]}" 309: end
# File lib/active_merchant/billing/gateways/trust_commerce.rb, line 408 408: def message_from(data) 409: status = case data["status"] 410: when "decline" 411: return DECLINE_CODES[data["declinetype"]] 412: when "baddata" 413: return BADDATA_CODES[data["error"]] 414: when "error" 415: return ERROR_CODES[data["errortype"]] 416: else 417: return "The transaction was successful" 418: end 419: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.