class ActiveMerchant::Billing::AuthorizeNetArbGateway

For more information on the Authorize.Net Gateway please visit their Integration Center

The login and password are not the username and password you use to login to the Authorize.Net Merchant Interface. Instead, you will use the API Login ID as the login and Transaction Key as the password.

How to Get Your API Login ID and Transaction Key

  1. Log into the Merchant Interface

  2. Select Settings from the Main Menu

  3. Click on API Login ID and Transaction Key in the Security section

  4. Type in the answer to the secret question configured on setup

  5. Click Submit

Automated Recurring Billing (ARB)

Automated Recurring Billing (ARB) is an optional service for submitting and managing recurring, or subscription-based, transactions.

To use recurring, update_recurring, cancel_recurring and status_recurring ARB must be enabled for your account.

Information about ARB is available on the Authorize.Net website. Information about the ARB API is available at the Authorize.Net Integration Center

Constants

API_VERSION
AUTHORIZE_NET_ARB_NAMESPACE
RECURRING_ACTIONS

Public Class Methods

new(options = {}) click to toggle source

Creates a new AuthorizeNetArbGateway

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

Options

  • :login – The Authorize.Net API Login ID (REQUIRED)

  • :password – The Authorize.Net Transaction Key. (REQUIRED)

  • :testtrue or false. If true, perform transactions against the test server. Otherwise, perform transactions against the production server.

Calls superclass method ActiveMerchant::Billing::Gateway::new
# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 59
def initialize(options = {})
  ActiveMerchant.deprecated "ARB functionality in ActiveMerchant is deprecated and will be removed in a future version. Please contact the ActiveMerchant maintainers if you have an interest in taking ownership of a separate gem that continues support for it."
  requires!(options, :login, :password)
  super
end

Public Instance Methods

cancel_recurring(subscription_id) click to toggle source

Cancel a recurring payment.

This transaction cancels an existing Automated Recurring Billing (ARB) subscription. Your account must have ARB enabled and the subscription must have already been created previously by calling recurring()

Parameters

  • subscription_id – A string containing the subscription_id of the recurring payment already in place for a given credit card. (REQUIRED)

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 128
def cancel_recurring(subscription_id)
  request = build_recurring_request(:cancel, :subscription_id => subscription_id)
  recurring_commit(:cancel, request)
end
recurring(money, creditcard, options={}) click to toggle source

Create a recurring payment.

This transaction creates a new Automated Recurring Billing (ARB) subscription. Your account must have ARB enabled.

Parameters

  • money – The amount to be charged to the customer at each interval as an Integer value in cents.

  • creditcard – The CreditCard details for the transaction.

  • options – A hash of parameters.

Options

  • :interval – A hash containing information about the interval of time between payments. Must contain the keys :length and :unit. :unit can be either :months or :days. If :unit is :months then :length must be an integer between 1 and 12 inclusive. If :unit is :days then :length must be an integer between 7 and 365 inclusive. For example, to charge the customer once every three months the hash would be +:interval => { :unit => :months, :length => 3 }+ (REQUIRED)

  • :duration – A hash containing keys for the :start_date the subscription begins (also the date the initial billing occurs) and the total number of billing :occurrences or payments for the subscription. (REQUIRED)

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 85
def recurring(money, creditcard, options={})
  requires!(options, :interval, :duration, :billing_address)
  requires!(options[:interval], :length, [:unit, :days, :months])
  requires!(options[:duration], :start_date, :occurrences)
  requires!(options[:billing_address], :first_name, :last_name)

  options[:credit_card] = creditcard
  options[:amount] = money

  request = build_recurring_request(:create, options)
  recurring_commit(:create, request)
end
status_recurring(subscription_id) click to toggle source

Get Subscription Status of a recurring payment.

This transaction gets the status of an existing Automated Recurring Billing (ARB) subscription. Your account must have ARB enabled.

Parameters

  • subscription_id – A string containing the subscription_id of the recurring payment already in place for a given credit card. (REQUIRED)

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 141
def status_recurring(subscription_id)
  request = build_recurring_request(:status, :subscription_id => subscription_id)
  recurring_commit(:status, request)
end
update_recurring(options={}) click to toggle source

Update a recurring payment’s details.

This transaction updates an existing Automated Recurring Billing (ARB) subscription. Your account must have ARB enabled and the subscription must have already been created previously by calling +recurring()+. The ability to change certain details about a recurring payment is dependent on transaction history and cannot be determined until after calling +update_recurring()+. See the ARB XML Guide for such conditions.

Parameters

  • options – A hash of parameters.

Options

  • :subscription_id – A string containing the :subscription_id of the recurring payment already in place for a given credit card. (REQUIRED)

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 113
def update_recurring(options={})
  requires!(options, :subscription_id)
  request = build_recurring_request(:update, options)
  recurring_commit(:update, request)
end

Private Instance Methods

add_address(xml, container_name, address) click to toggle source

Adds address information

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 360
def add_address(xml, container_name, address)
  return if address.blank?
  xml.tag!(container_name) do
    xml.tag!('firstName', address[:first_name])
    xml.tag!('lastName', address[:last_name])
    xml.tag!('company', address[:company])
    xml.tag!('address', address[:address1])
    xml.tag!('city', address[:city])
    xml.tag!('state', address[:state])
    xml.tag!('zip', address[:zip])
    xml.tag!('country', address[:country])
  end
end
add_bank_account(xml, options) click to toggle source

Adds customer’s bank account information Note: This element should only be included when the payment method is bank account.

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 297
def add_bank_account(xml, options)
  bank_account = options[:bank_account]
  return unless bank_account
  xml.tag!('bankAccount') do
    # The type of bank account used for payment of the subscription
    xml.tag!('accountType', bank_account[:account_type])
    # The routing number of the customer’s bank
    xml.tag!('routingNumber', bank_account[:routing_number])
    # The bank account number used for payment of the subscription
    xml.tag!('accountNumber', bank_account[:account_number])
    # The full name of the individual associated
    # with the bank account number
    xml.tag!('nameOfAccount', bank_account[:name_of_account])
    # The full name of the individual associated
    # with the bank account number (optional)
    xml.tag!('bankName', bank_account[:bank_name]) if bank_account[:bank_name]
    # The type of electronic check transaction used for the subscription
    xml.tag!('echeckType', bank_account[:echeck_type])
  end
end
add_credit_card(xml, options) click to toggle source

Adds customer’s credit card information Note: This element should only be included when the payment method is credit card.

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 283
def add_credit_card(xml, options)
  credit_card = options[:credit_card]
  return unless credit_card
  xml.tag!('creditCard') do
    # The credit card number used for payment of the subscription
    xml.tag!('cardNumber', credit_card.number)
    # The expiration date of the credit card used for the subscription
    xml.tag!('expirationDate', expdate(credit_card))
  end
end
add_customer(xml, options) click to toggle source

Adds information about the customer

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 331
def add_customer(xml, options)
  customer = options[:customer]
  return unless customer
  xml.tag!('customer') do
    xml.tag!('type', customer[:type]) if customer[:type]
    xml.tag!('id', customer[:id]) if customer[:id]
    xml.tag!('email', customer[:email]) if customer[:email]
    xml.tag!('phoneNumber', customer[:phone_number]) if customer[:phone_number]
    xml.tag!('faxNumber', customer[:fax_number]) if customer[:fax_number]
    add_drivers_license(xml, options)
    xml.tag!('taxId', customer[:tax_id]) if customer[:tax_id]
  end
end
add_drivers_license(xml, options) click to toggle source

Adds the customer’s driver’s license information (conditional)

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 346
def add_drivers_license(xml, options)
  return unless customer = options[:customer]
  return unless drivers_license = customer[:drivers_license]
  xml.tag!('driversLicense') do
    # The customer's driver's license number
    xml.tag!('number', drivers_license[:number])
    # The customer's driver's license state
    xml.tag!('state', drivers_license[:state])
    # The customer's driver's license date of birth
    xml.tag!('dateOfBirth', drivers_license[:date_of_birth])
  end
end
add_duration(xml, options) click to toggle source

Adds information about the subscription duration

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 246
def add_duration(xml, options)
  duration = options[:duration]
  return unless duration
  # The date the subscription begins
  # (also the date the initial billing occurs)
  xml.tag!('startDate', duration[:start_date]) if duration[:start_date]
  # Number of billing occurrences or payments for the subscription
  xml.tag!('totalOccurrences', duration[:occurrences]) if duration[:occurrences]
end
add_interval(xml, options) click to toggle source

Adds information about the interval of time between payments

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 232
def add_interval(xml, options)
  interval = options[:interval]
  return unless interval
  xml.tag!('interval') do
    # The measurement of time, in association with the Interval Unit,
    # that is used to define the frequency of the billing occurrences
    xml.tag!('length', interval[:length])
    # The unit of time, in association with the Interval Length,
    # between each billing occurrence
    xml.tag!('unit', interval[:unit].to_s)
  end
end
add_merchant_authentication(xml) click to toggle source

Contains the merchant’s payment gateway account authentication information

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 165
def add_merchant_authentication(xml)
  xml.tag!('merchantAuthentication') do
    xml.tag!('name', @options[:login])
    xml.tag!('transactionKey', @options[:password])
  end
end
add_order(xml, options) click to toggle source

Adds order information (optional)

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 319
def add_order(xml, options)
  order = options[:order]
  return unless order
  xml.tag!('order') do
    # Merchant-assigned invoice number for the subscription (optional)
    xml.tag!('invoiceNumber', order[:invoice_number])
    # Description of the subscription (optional)
    xml.tag!('description', order[:description])
  end
end
add_payment(xml, options) click to toggle source

Adds customer’s credit card or bank account payment information

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 270
def add_payment(xml, options)
  return unless options[:credit_card] || options[:bank_account]
  xml.tag!('payment') do
    # Contains the customer’s credit card information
    add_credit_card(xml, options)
    # Contains the customer’s bank account information
    add_bank_account(xml, options)
  end
end
add_payment_schedule(xml, options) click to toggle source
# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 256
def add_payment_schedule(xml, options)
  return unless options[:interval] || options[:duration]
  xml.tag!('paymentSchedule') do
    # Contains information about the interval of time between payments
    add_interval(xml, options)
    add_duration(xml, options)
    if trial = options[:trial]
      # Number of billing occurrences or payments in the trial period (optional)
      xml.tag!('trialOccurrences', trial[:occurrences]) if trial[:occurrences]
    end
  end
end
add_subscription(xml, options) click to toggle source

Adds subscription information

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 204
def add_subscription(xml, options)
  xml.tag!('subscription') do
    # Merchant-assigned name for the subscription (optional)
    xml.tag!('name', options[:subscription_name]) if options[:subscription_name]
    # Contains information about the payment schedule
    add_payment_schedule(xml, options)
    # The amount to be billed to the customer
    # for each payment in the subscription
    xml.tag!('amount', amount(options[:amount])) if options[:amount]
    if trial = options[:trial]
      # The amount to be charged for each payment during a trial period (conditional)
      xml.tag!('trialAmount', amount(trial[:amount])) if trial[:amount]
    end
    # Contains either the customer’s credit card
    # or bank account payment information
    add_payment(xml, options)
    # Contains order information (optional)
    add_order(xml, options)
    # Contains information about the customer
    add_customer(xml, options)
    # Contains the customer's billing address information
    add_address(xml, 'billTo', options[:billing_address])
    # Contains the customer's shipping address information (optional)
    add_address(xml, 'shipTo', options[:shipping_address])
  end
end
build_cancel_subscription_request(xml, options) click to toggle source

Builds body for ARBCancelSubscriptionRequest

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 190
def build_cancel_subscription_request(xml, options)
  xml.tag!('subscriptionId', options[:subscription_id])

  xml.target!
end
build_create_subscription_request(xml, options) click to toggle source

Builds body for ARBCreateSubscriptionRequest

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 173
def build_create_subscription_request(xml, options)
  # Subscription
  add_subscription(xml, options)

  xml.target!
end
build_recurring_request(action, options = {}) click to toggle source

Builds recurring billing request

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 149
def build_recurring_request(action, options = {})
  unless RECURRING_ACTIONS.include?(action)
    raise StandardError, "Invalid Automated Recurring Billing Action: #{action}"
  end

  xml = Builder::XmlMarkup.new(:indent => 2)
  xml.instruct!(:xml, :version => '1.0', :encoding => 'utf-8')
  xml.tag!("#{RECURRING_ACTIONS[action]}Request", :xmlns => AUTHORIZE_NET_ARB_NAMESPACE) do
    add_merchant_authentication(xml)
    # Merchant-assigned reference ID for the request
    xml.tag!('refId', options[:ref_id]) if options[:ref_id]
    send("build_#{action}_subscription_request", xml, options)
  end
end
build_status_subscription_request(xml, options) click to toggle source

Builds body for ARBGetSubscriptionStatusRequest

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 197
def build_status_subscription_request(xml, options)
  xml.tag!('subscriptionId', options[:subscription_id])

  xml.target!
end
build_update_subscription_request(xml, options) click to toggle source

Builds body for ARBUpdateSubscriptionRequest

# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 181
def build_update_subscription_request(xml, options)
  xml.tag!('subscriptionId', options[:subscription_id])
  # Adds Subscription
  add_subscription(xml, options)

  xml.target!
end
expdate(credit_card) click to toggle source
# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 374
def expdate(credit_card)
  sprintf('%04d-%02d', credit_card.year, credit_card.month)
end
recurring_commit(action, request) click to toggle source
# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 378
def recurring_commit(action, request)
  url = test? ? test_url : live_url
  xml = ssl_post(url, request, "Content-Type" => "text/xml")

  response = recurring_parse(action, xml)

  message = response[:message] || response[:text]
  test_mode = test? || message =~ /Test Mode/
  success = response[:result_code] == 'Ok'

  Response.new(success, message, response,
    :test => test_mode,
    :authorization => response[:subscription_id]
  )
end
recurring_parse(action, xml) click to toggle source
# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 394
def recurring_parse(action, xml)
  response = {}
  xml = REXML::Document.new(xml)
  root = REXML::XPath.first(xml, "//#{RECURRING_ACTIONS[action]}Response") ||
         REXML::XPath.first(xml, "//ErrorResponse")
  if root
    root.elements.to_a.each do |node|
      recurring_parse_element(response, node)
    end
  end

  response
end
recurring_parse_element(response, node) click to toggle source
# File lib/active_merchant/billing/gateways/authorize_net_arb.rb, line 408
def recurring_parse_element(response, node)
  if node.has_elements?
    node.elements.each{|e| recurring_parse_element(response, e) }
  else
    response[node.name.underscore.to_sym] = node.text
  end
end