Class Index [+]

Quicksearch

ActiveMerchant::Billing::DataCashGateway

Constants

TEST_URL

Datacash server URLs

LIVE_URL
AUTH_TYPE

Different Card Transaction Types

CANCEL_TYPE
FULFILL_TYPE
PRE_TYPE
REFUND_TYPE
TRANSACTION_REFUND_TYPE
POLICY_ACCEPT

Constant strings for use in the ExtendedPolicy complex element for CV2 checks

POLICY_REJECT
DATACASH_SUCCESS

Datacash success code

Public Class Methods

new(options = {}) click to toggle source

Creates a new DataCashGateway

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

Options

  • :login — The Datacash account login.

  • :password — The Datacash account password.

  • :test => true or false — Use the test or live Datacash url.

      
    # File lib/active_merchant/billing/gateways/data_cash.rb, line 50
50:       def initialize(options = {})
51:         requires!(options, :login, :password)
52:         @options = options
53:         super
54:       end

Public Instance Methods

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

Performs an authorization, which reserves the funds on the customer’s credit card, but does not charge the card.

Parameters

  • money The amount to be authorized as an Integer value in cents.

  • authorization_or_credit_card

    The continuous authority reference or CreditCard details for the transaction.

  • options A hash of optional parameters.

    • :order_id A unique reference for this order (corresponds to merchantreference in datacash documentation)

    • :set_up_continuous_authority
       Set to true to set up a recurring historic transaction account be set up.
       Only supported for :visa, :master and :american_express card types 
       See http://www.datacash.com/services/recurring/historic.php for more details of historic transactions. 
      
    • :address

      billing address for card

The continuous authority reference will be available in response#[‘ca_referece’] if you have requested one

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 98
 98:       def authorize(money, authorization_or_credit_card, options = {})
 99:         requires!(options, :order_id)
100: 
101:         if authorization_or_credit_card.is_a?(String)
102:           request = build_purchase_or_authorization_request_with_continuous_authority_reference_request(AUTH_TYPE, money, authorization_or_credit_card, options)
103:         else
104:           request = build_purchase_or_authorization_request_with_credit_card_request(PRE_TYPE, money, authorization_or_credit_card, options)
105:         end
106: 
107:         commit(request)
108:       end
capture(money, authorization, options = {}) click to toggle source

Captures the funds from an authorized transaction.

Parameters

  • money — The amount to be captured as anInteger value in cents.

  • authorization — The authorization returned from the previous authorize request.

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 116
116:       def capture(money, authorization, options = {})
117:         commit(build_void_or_capture_request(FULFILL_TYPE, money, authorization, options))
118:       end
credit(money, reference_or_credit_card, options = {}) click to toggle source

Refund to a card

Parameters

  • money The amount to be refunded as an Integer value in cents. Set to nil for a full refund on existing transaction.

  • reference_or_credit_card The credit card you want to refund OR the datacash_reference for the existing transaction you are refunding

  • options Are ignored when refunding via reference to an existing transaction, otherwise

    • :order_id A unique reference for this order (corresponds to merchantreference in datacash documentation)

    • :address

      billing address for card

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 140
140:       def credit(money, reference_or_credit_card, options = {})
141:         if reference_or_credit_card.is_a?(String)
142:           deprecated CREDIT_DEPRECATION_MESSAGE
143:           refund(money, reference_or_credit_card)
144:         else
145:           request = build_refund_request(money, reference_or_credit_card, options)
146:           commit(request)
147:         end
148:       end
purchase(money, authorization_or_credit_card, options = {}) click to toggle source

Perform a purchase, which is essentially an authorization and capture in a single operation.

Parameters

  • money The amount to be authorized as an Integer value in cents.

  • authorization_or_credit_card

    The continuous authority reference or CreditCard details for the transaction.

  • options A hash of optional parameters.

    • :order_id A unique reference for this order (corresponds to merchantreference in datacash documentation)

    • :set_up_continuous_authority

       Set to true to set up a recurring historic transaction account be set up.
       Only supported for :visa, :master and :american_express card types 
       See http://www.datacash.com/services/recurring/historic.php for more details of historic transactions. 
      
    • :address

      billing address for card

The continuous authority reference will be available in response#[‘ca_referece’] if you have requested one

    # File lib/active_merchant/billing/gateways/data_cash.rb, line 70
70:       def purchase(money, authorization_or_credit_card, options = {})
71:         requires!(options, :order_id)
72: 
73:         if authorization_or_credit_card.is_a?(String)
74:           request = build_purchase_or_authorization_request_with_continuous_authority_reference_request(AUTH_TYPE, money, authorization_or_credit_card, options)
75:         else
76:           request = build_purchase_or_authorization_request_with_credit_card_request(AUTH_TYPE, money, authorization_or_credit_card, options)
77:         end
78: 
79:         commit(request)
80:       end
refund(money, reference, options = {}) click to toggle source
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 150
150:       def refund(money, reference, options = {})
151:         commit(build_transaction_refund_request(money, reference))
152:       end
test?() click to toggle source

Is the gateway running in test mode?

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 155
155:       def test?
156:         @options[:test] || super
157:       end
void(authorization, options = {}) click to toggle source

Void a previous transaction

Parameters

  • authorization - The authorization returned from the previous authorize request.

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 125
125:       def void(authorization, options = {})
126:         request = build_void_or_capture_request(CANCEL_TYPE, nil, authorization, options)
127: 
128:         commit(request)
129:       end

Private Instance Methods

add_authentication(xml) click to toggle source

Adds the authentication element to the passed builder xml doc

Parameters:

  -xml: Builder document that is being built up
  

Returns:

  -none: The results is stored in the passed xml document
  
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 450
450:       def add_authentication(xml)
451:         xml.tag! :Authentication do
452:           xml.tag! :client, @options[:login]
453:           xml.tag! :password, @options[:password]
454:         end
455:       end
add_credit_card(xml, credit_card, address) click to toggle source

Add credit_card detals to the passed XML Builder doc

Parameters:

  -xml: Builder document that is being built up
  -credit_card: ActiveMerchant::Billing::CreditCard object
  -billing_address: Hash containing all of the billing address details
  

Returns:

  -none: The results is stored in the passed xml document
  
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 467
467:       def add_credit_card(xml, credit_card, address)
468:         
469:         xml.tag! :Card do
470: 
471:           # DataCash calls the CC number 'pan'
472:           xml.tag! :pan, credit_card.number
473:           xml.tag! :expirydate, format_date(credit_card.month, credit_card.year)
474: 
475:           # optional values - for Solo etc
476:           if [ 'switch', 'solo' ].include?(card_brand(credit_card).to_s)
477:             
478:             xml.tag! :issuenumber, credit_card.issue_number unless credit_card.issue_number.blank?
479: 
480:             if !credit_card.start_month.blank? && !credit_card.start_year.blank?
481:               xml.tag! :startdate, format_date(credit_card.start_month, credit_card.start_year)
482:             end
483:           end
484: 
485:           xml.tag! :Cv2Avs do
486:             xml.tag! :cv2, credit_card.verification_value if credit_card.verification_value?
487:             if address
488:               xml.tag! :street_address1, address[:address1] unless address[:address1].blank?
489:               xml.tag! :street_address2, address[:address2] unless address[:address2].blank?
490:               xml.tag! :street_address3, address[:address3] unless address[:address3].blank?
491:               xml.tag! :street_address4, address[:address4] unless address[:address4].blank?
492:               xml.tag! :postcode, address[:zip] unless address[:zip].blank?
493:             end
494: 
495:             # The ExtendedPolicy defines what to do when the passed data 
496:             # matches, or not...
497:             # 
498:             # All of the following elements MUST be present for the
499:             # xml to be valid (or can drop the ExtendedPolicy and use
500:             # a predefined one
501:             xml.tag! :ExtendedPolicy do
502:               xml.tag! :cv2_policy, 
503:               :notprovided =>   POLICY_REJECT,
504:               :notchecked =>    POLICY_REJECT,
505:               :matched =>       POLICY_ACCEPT,
506:               :notmatched =>    POLICY_REJECT,
507:               :partialmatch =>  POLICY_REJECT
508:               xml.tag! :postcode_policy,
509:               :notprovided =>   POLICY_ACCEPT,
510:               :notchecked =>    POLICY_ACCEPT,
511:               :matched =>       POLICY_ACCEPT,
512:               :notmatched =>    POLICY_REJECT,
513:               :partialmatch =>  POLICY_ACCEPT
514:               xml.tag! :address_policy, 
515:               :notprovided =>   POLICY_ACCEPT,
516:               :notchecked =>    POLICY_ACCEPT,
517:               :matched =>       POLICY_ACCEPT,
518:               :notmatched =>    POLICY_REJECT,
519:               :partialmatch =>  POLICY_ACCEPT
520:             end
521:           end
522:         end
523:       end
build_purchase_or_authorization_request_with_continuous_authority_reference_request(type, money, authorization, options) click to toggle source

Create the xml document for an ‘auth’ or ‘pre’ transaction with continuous authorization

Final XML should look like:

  <Transaction> 
    <ContAuthTxn type="historic" /> 
    <TxnDetails> 
      <merchantreference>3851231</merchantreference> 
      <capturemethod>cont_auth</capturemethod> 
      <amount currency="GBP">18.50</amount> 
    </TxnDetails> 
    <HistoricTxn> 
      <reference>4500200040925092</reference> 
      <method>auth</method> 
    </HistoricTxn> 
  </Transaction> 
  <Authentication> 
    <client>99000001</client> 
    <password>mypasswd</password> 
  </Authentication> 

Parameters:

  -type must be 'auth' or 'pre'
  -money - A money object with the price and currency
  -authorization - The authorization containing a continuous authority reference previously set up on a credit card
  -options:
    :order_id is the merchant reference number
  

Returns:

  -xml: Builder document containing the markup
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 334
334:       def build_purchase_or_authorization_request_with_continuous_authority_reference_request(type, money, authorization, options)
335:         reference, auth_code, ca_reference = authorization.to_s.split(';')
336:         raise ArgumentError, "The continuous authority reference is required for continuous authority transactions" if ca_reference.blank?
337: 
338:         xml = Builder::XmlMarkup.new :indent => 2
339:         xml.instruct!
340:         xml.tag! :Request do
341:           add_authentication(xml)
342:           xml.tag! :Transaction do
343:             xml.tag! :ContAuthTxn, :type => 'historic'
344:             xml.tag! :HistoricTxn do
345:               xml.tag! :reference, ca_reference
346:               xml.tag! :method, type
347:             end
348:             xml.tag! :TxnDetails do
349:               xml.tag! :merchantreference, format_reference_number(options[:order_id])
350:               xml.tag! :amount, amount(money), :currency => options[:currency] || currency(money)
351:               xml.tag! :capturemethod, 'cont_auth'
352:             end
353:           end
354:         end
355:         xml.target!
356:       end
build_purchase_or_authorization_request_with_credit_card_request(type, money, credit_card, options) click to toggle source

Create the xml document for an ‘auth’ or ‘pre’ transaction with a credit card

Final XML should look like:

 <Authentication>
   <client>99000000</client>
   <password>*******</password>
 </Authentication>
 <Transaction>
   <TxnDetails>
     <merchantreference>123456</merchantreference>
     <amount currency="EUR">10.00</amount>
   </TxnDetails>
   <CardTxn>
     <Card>
       <pan>4444********1111</pan>
       <expirydate>03/04</expirydate>
       <Cv2Avs>
         <street_address1>Flat 7</street_address1>
         <street_address2>89 Jumble
              Street</street_address2>
         <street_address3>Mytown</street_address3>
         <postcode>AV12FR</postcode>
         <cv2>123</cv2>
          <ExtendedPolicy>
            <cv2_policy notprovided="reject"
                         notchecked="accept"
                         matched="accept"
                         notmatched="reject"
                         partialmatch="reject"/>
            <postcode_policy notprovided="reject"
                         notchecked="accept"
                         matched="accept"
                         notmatched="reject"
                         partialmatch="accept"/>
            <address_policy notprovided="reject"
                         notchecked="accept"
                         matched="accept"
                         notmatched="reject"
                         partialmatch="accept"/>
          </ExtendedPolicy>
       </Cv2Avs>
     </Card>
     <method>auth</method>
   </CardTxn>
 </Transaction>

Parameters:

  -type must be 'auth' or 'pre'
  -money - A money object with the price and currency
  -credit_card - The credit_card details to use
  -options:
    :order_id is the merchant reference number
    :billing_address is the billing address for the cc
    :address is the delivery address
  

Returns:

  -xml: Builder document containing the markup
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 277
277:       def build_purchase_or_authorization_request_with_credit_card_request(type, money, credit_card, options)
278:         xml = Builder::XmlMarkup.new :indent => 2
279:         xml.instruct!
280:         xml.tag! :Request do
281:           add_authentication(xml)
282:           
283:           xml.tag! :Transaction do
284:             if options[:set_up_continuous_authority]
285:               xml.tag! :ContAuthTxn, :type => 'setup'
286:             end
287:             xml.tag! :CardTxn do
288:               xml.tag! :method, type
289:               add_credit_card(xml, credit_card, options[:billing_address])
290:             end
291:             xml.tag! :TxnDetails do
292:               xml.tag! :merchantreference, format_reference_number(options[:order_id])
293:               xml.tag! :amount, amount(money), :currency => options[:currency] || currency(money)
294:             end
295:           end
296:         end
297:         xml.target!
298:       end
build_refund_request(money, credit_card, options) click to toggle source

Create the xml document for a full or partial refund with

Final XML should look like:

  <Authentication> 
    <client>99000001</client> 
    <password>*****</password> 
  </Authentication> 
  <Transaction> 
    <CardTxn> 
      <Card> 
        <pan>633300*********1</pan> 
        <expirydate>04/06</expirydate> 
        <startdate>01/04</startdate> 
      </Card> 
      <method>refund</method> 
    </CardTxn> 
    <TxnDetails> 
      <merchantreference>1000001</merchantreference> 
      <amount currency="GBP">95.99</amount> 
    </TxnDetails> 
  </Transaction>

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 422
422:       def build_refund_request(money, credit_card, options)
423:         xml = Builder::XmlMarkup.new :indent => 2
424:         xml.instruct!
425:         xml.tag! :Request do
426:           add_authentication(xml)
427:           xml.tag! :Transaction do
428:             xml.tag! :CardTxn do
429:               xml.tag! :method, REFUND_TYPE
430:               add_credit_card(xml, credit_card, options[:billing_address])
431:             end
432:             xml.tag! :TxnDetails do
433:               xml.tag! :merchantreference, format_reference_number(options[:order_id])
434:               xml.tag! :amount, amount(money)
435:             end
436:           end
437:         end
438:         xml.target!
439:       end
build_transaction_refund_request(money, reference) click to toggle source

Create the xml document for a full or partial refund transaction with

Final XML should look like:

  <Authentication> 
    <client>99000001</client> 
    <password>*******</password> 
  </Authentication> 
  <Transaction> 
    <HistoricTxn> 
      <method>txn_refund</method> 
      <reference>12345678</reference> 
    </HistoricTxn> 
    <TxnDetails> 
      <amount>10.00</amount> 
    </TxnDetails> 
  </Transaction>

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 378
378:       def build_transaction_refund_request(money, reference)
379:         xml = Builder::XmlMarkup.new :indent => 2
380:         xml.instruct!
381:         xml.tag! :Request do
382:           add_authentication(xml)
383:           xml.tag! :Transaction do
384:             xml.tag! :HistoricTxn do
385:               xml.tag! :reference, reference
386:               xml.tag! :method, TRANSACTION_REFUND_TYPE
387:             end
388:             unless money.nil?
389:               xml.tag! :TxnDetails do
390:                 xml.tag! :amount, amount(money)
391:               end
392:             end
393:           end
394:         end
395:         xml.target!
396:       end
build_void_or_capture_request(type, money, authorization, options) click to toggle source

Create the xml document for a ‘cancel’ or ‘fulfill’ transaction.

Final XML should look like:

 <Authentication>
   <client>99000001</client>
   <password>******</password>
 </Authentication>
 <Transaction>
   <TxnDetails>
     <amount>25.00</amount>
   </TxnDetails>
   <HistoricTxn>
     <reference>4900200000000001</reference>
     <authcode>A6</authcode>
     <method>fulfill</method>
   </HistoricTxn>
 </Transaction>

Parameters:

  • type must be FULFILL_TYPE or CANCEL_TYPE

  • money - optional - Integer value in cents

  • authorization - the Datacash authorization from a previous succesful authorize transaction

  • options

    • order_id - A unique reference for the transaction

Returns:

  -Builder xml document
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 190
190:       def build_void_or_capture_request(type, money, authorization, options)
191:         reference, auth_code, ca_reference = authorization.to_s.split(';')
192: 
193:         xml = Builder::XmlMarkup.new :indent => 2
194:         xml.instruct!
195:         xml.tag! :Request do
196:           add_authentication(xml)
197:           
198:           xml.tag! :Transaction do
199:             xml.tag! :HistoricTxn do
200:               xml.tag! :reference, reference
201:               xml.tag! :authcode, auth_code
202:               xml.tag! :method, type
203:             end
204:             
205:             if money
206:               xml.tag! :TxnDetails do
207:                 xml.tag! :merchantreference, format_reference_number(options[:order_id])
208:                 xml.tag! :amount, amount(money), :currency => options[:currency] || currency(money)
209:               end
210:             end
211:           end
212:         end
213:         xml.target!
214:       end
commit(request) click to toggle source

Send the passed data to DataCash for processing

Parameters:

  -request: The XML data that is to be sent to Datacash
  

Returns:

  * ActiveMerchant::Billing::Response object
  
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 533
533:       def commit(request)
534:         response = parse(ssl_post(test? ? TEST_URL : LIVE_URL, request))      
535: 
536:         Response.new(response[:status] == DATACASH_SUCCESS, response[:reason], response,
537:           :test => test?,
538:           :authorization => "#{response[:datacash_reference]};#{response[:authcode]};#{response[:ca_reference]}"
539:         )
540:       end
format_date(month, year) click to toggle source

Returns a date string in the format Datacash expects

Parameters:

  -month: integer, the month
  -year: integer, the year

Returns:

  -String: date in MM/YY format
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 551
551:       def format_date(month, year)
552:         "#{format(month,:two_digits)}/#{format(year, :two_digits)}"
553:       end
format_reference_number(number) click to toggle source
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 592
592:       def format_reference_number(number)
593:         number.to_s.gsub(/[^A-Za-z0-9]/, '').rjust(6, "0").first(30)
594:       end
parse(body) click to toggle source

Parse the datacash response and create a Response object

Parameters:

  -body: The XML returned from Datacash

Returns:

  -a hash with all of the values returned in the Datacash XML response
     # File lib/active_merchant/billing/gateways/data_cash.rb, line 563
563:       def parse(body)
564: 
565:         response = {}
566:         xml = REXML::Document.new(body)
567:         root = REXML::XPath.first(xml, "//Response")
568: 
569:         root.elements.to_a.each do |node|
570:           parse_element(response, node)
571:         end
572: 
573:         response
574:       end
parse_element(response, node) click to toggle source

Parse an xml element

Parameters:

  -response: The hash that the values are being returned in
  -node: The node that is currently being read

Returns:

  • none (results are stored in the passed hash)

     # File lib/active_merchant/billing/gateways/data_cash.rb, line 584
584:       def parse_element(response, node)
585:         if node.has_elements?
586:           node.elements.each{|e| parse_element(response, e) }
587:         else
588:           response[node.name.underscore.to_sym] = node.text
589:         end
590:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.