Class: ActiveMerchant::Billing::TrustCommerceGateway
- Defined in:
- lib/active_merchant/billing/gateways/trust_commerce.rb
Overview
To get started using TrustCommerce with active_merchant, download the tclink library from www.trustcommerce.com/tclink.html, following the instructions available there to get it working on your system. 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”.
TO USE: First, make sure you have everything setup correctly and all of your dependencies in place with:
require 'rubygems'
require 'money'
require 'active_merchant'
The second line is a require for the ‘money’ library. Make sure you have it installed with ‘gem install money’
Using the money library, create a money object. Pass the dollar value in cents. In this case, $10 US becomes 1000.
tendollar = Money.us_dollar(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.
3) Retrieve and store the unique transaction ID returned by Trust Commerece, for use in referencing the transaction in the future.
response.params["transid"]
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 =
["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" }
Instance Attribute Summary collapse
-
#options ⇒ Object
readonly
Returns the value of attribute options.
-
#response ⇒ Object
readonly
Returns the value of attribute response.
-
#url ⇒ Object
readonly
URL.
Class Method Summary collapse
Instance Method Summary collapse
-
#authorize(money, creditcard, options = {}) ⇒ Object
authorize() is the first half of the preauth(authorize)/postauth(capture) model.
-
#capture(money, authorization, options = {}) ⇒ Object
capture() is the second half of the preauth(authorize)/postauth(capture) model.
-
#credit(money, identification, options = {}) ⇒ Object
credit() allows you to return money to a card that was previously billed.
-
#initialize(options = {}) ⇒ TrustCommerceGateway
constructor
A new instance of TrustCommerceGateway.
-
#purchase(money, creditcard, options = {}) ⇒ Object
purchase() is a simple sale.
-
#recurring(money, creditcard, options = {}) ⇒ Object
recurring() a TrustCommerce account that is activated for Citatdel, TrustCommerce’s hosted customer billing info database.
-
#store(creditcard, options = {}) ⇒ Object
store() requires a TrustCommerce account that is activated for Citatdel.
-
#unstore(identification, options = {}) ⇒ Object
To unstore a creditcard stored in Citadel using store() or recurring(), all that is required is the billing id.
Methods inherited from Gateway
Methods included from RequiresParameters
Methods included from PostsData
Constructor Details
#initialize(options = {}) ⇒ TrustCommerceGateway
Returns a new instance of TrustCommerceGateway.
107 108 109 110 111 112 113 114 115 116 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 107 def initialize( = {}) requires!(, :login, :password) # these are the defaults for trustcommerce @options = { :login => "TestMerchant", :password => "password" }.update() super end |
Instance Attribute Details
#options ⇒ Object (readonly)
Returns the value of attribute options.
103 104 105 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 103 def @options end |
#response ⇒ Object (readonly)
Returns the value of attribute response.
102 103 104 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 102 def response @response end |
#url ⇒ Object (readonly)
URL
101 102 103 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 101 def url @url end |
Class Method Details
.supported_cardtypes ⇒ Object
239 240 241 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 239 def self.supported_cardtypes [:visa, :master, :discover, :american_express, :diners_club, :jcb] end |
Instance Method Details
#authorize(money, creditcard, 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.
123 124 125 126 127 128 129 130 131 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 123 def (money, creditcard, = {}) parameters = { :amount => amount(money), } add_creditcard(parameters, creditcard) add_address(parameters, ) 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.
150 151 152 153 154 155 156 157 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 150 def capture(money, , = {}) parameters = { :amount => amount(money), :transid => , } commit('postauth', parameters) end |
#credit(money, identification, options = {}) ⇒ Object
credit() 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.
162 163 164 165 166 167 168 169 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 162 def credit(money, identification, = {}) parameters = { :amount => amount(money), :transid => identification, } commit('credit', parameters) end |
#purchase(money, creditcard, 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.
136 137 138 139 140 141 142 143 144 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 136 def purchase(money, creditcard, = {}) parameters = { :amount => amount(money), } add_creditcard(parameters, creditcard) add_address(parameters, ) commit('sale', parameters) end |
#recurring(money, creditcard, options = {}) ⇒ Object
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’
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 183 def recurring(money, creditcard, = {}) requires!(, [:periodicity, :bimonthly, :monthly, :biweekly, :weekly, :yearly, :daily] ) cycle = case [: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 => [:verify] || 'y', :billingid => [:billingid] || nil, :payments => [:payments] || nil, } add_creditcard(parameters, creditcard) commit('store', parameters) end |
#store(creditcard, options = {}) ⇒ Object
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.
218 219 220 221 222 223 224 225 226 227 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 218 def store(creditcard, = {}) parameters = { :verify => [:verify] || 'y', :billingid => [:billingid] || nil, } add_creditcard(parameters, creditcard) add_address(parameters, ) commit('store', parameters) 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.
231 232 233 234 235 236 237 |
# File 'lib/active_merchant/billing/gateways/trust_commerce.rb', line 231 def unstore(identification, = {}) parameters = { :billingid => identification, } commit('unstore', parameters) end |