Class: ActiveMerchant::Billing::UsaEpayAdvancedGateway

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

Overview

USA ePay Advanced SOAP Interface

This class encapsulates USA ePay’s Advanced SOAP Interface. The Advanced Soap Interface allows standard transactions, storing customer information, and recurring billing. Storing sensitive information on USA ePay’s servers can help with PCI DSS compliance, since customer and card data do not need to be stored locally.

Make sure you have enabled this functionality for your account with USA ePay.

Information about the Advanced SOAP interface is available on the USA ePay wiki.

Login, Password, and Software ID

Please follow all of USA ePay’s directions for acquiring all accounts and settings.

The value used for :login is the Key value found in the Merchant Console under Settings > Source Key. You will have to add this key in the USA ePay Merchant Console.

The value used for :password is the pin value also found and assigned in the Merchant Console under Settings > Source Key. The pin is required to use all but basic transactions in the SOAP interface. You will have to add the pin to your source key, as it defaults to none.

The value used for the :software_id is found in the Developer’s Login under the Developers Center in your WSDL. It is the 8 character value in <soap:address> tag. A masked example: <soap:address location=“www.usaepay.com/soap/gate/XXXXXXXX”/> It is also found in the link to your WSDL. This is required as every account has a different path SOAP requests are submitted to. Optionally, you can provide the entire urls via :live_url and :test_url, if your prefer.

Responses

  • #success? – true if transmitted and returned correctly

  • #message – response or fault message

  • #authorization – reference_number or nil

  • #params – hash of entire soap response contents

Address Options

  • :billing_address/:shipping_address – contains some extra options

    • :name – virtual attribute; will split to first and last name

    • :first_name

    • :last_name

    • :address1

    • :address2

    • :city

    • :state

    • :zip

    • :country

    • :phone

    • :email

    • :fax

    • :company

Support:

Constant Summary collapse

API_VERSION = 
'1.4'
TEST_URL_BASE =

:nodoc:

'https://sandbox.usaepay.com/soap/gate/'
LIVE_URL_BASE =

:nodoc:

'https://www.usaepay.com/soap/gate/'
FAILURE_MESSAGE =

:nodoc:

'Default Failure'
CUSTOMER_PROFILE_OPTIONS = 
{
  id: [:string, 'CustomerID'], # merchant assigned number
  notes: [:string, 'Notes'],
  data: [:string, 'CustomData'],
  url: [:string, 'URL']
}
CUSTOMER_RECURRING_BILLING_OPTIONS =

:nodoc:

{
  enabled: [:boolean, 'Enabled'],
  schedule: [:string, 'Schedule'],
  number_left: [:integer, 'NumLeft'],
  currency: [:string, 'Currency'],
  description: [:string, 'Description'],
  order_id: [:string, 'OrderID'],
  user: [:string, 'User'],
  source: [:string, 'Source'],
  send_receipt: [:boolean, 'SendReceipt'],
  receipt_note: [:string, 'ReceiptNote']
}
CUSTOMER_POINT_OF_SALE_OPTIONS =

:nodoc:

{
  price_tier: [:string, 'PriceTier'],
  tax_class: [:string, 'TaxClass'],
  lookup_code: [:string, 'LookupCode']
}
CUSTOMER_OPTIONS =

:nodoc:

[
  CUSTOMER_PROFILE_OPTIONS,
  CUSTOMER_RECURRING_BILLING_OPTIONS,
  CUSTOMER_POINT_OF_SALE_OPTIONS
].inject(:merge)
COMMON_ADDRESS_OPTIONS = 
{
  first_name: [:string, 'FirstName'],
  last_name: [:string, 'LastName'],
  city: [:string, 'City'],
  state: [:string, 'State'],
  zip: [:string, 'Zip'],
  country: [:string, 'Country'],
  phone: [:string, 'Phone'],
  email: [:string, 'Email'],
  fax: [:string, 'Fax'],
  company: [:string, 'Company']
}
ADDRESS_OPTIONS =

:nodoc:

[
  COMMON_ADDRESS_OPTIONS,
  {
    address1: [:string, 'Street'],
    address2: [:string, 'Street2']
  }
].inject(:merge)
CUSTOMER_UPDATE_DATA_FIELDS = 
[
  CUSTOMER_PROFILE_OPTIONS,
  CUSTOMER_RECURRING_BILLING_OPTIONS,
  COMMON_ADDRESS_OPTIONS,
  {
    address1: [:string, 'Address'],
    address2: [:string, 'Address2']
  },
  {
    card_number: [:string, 'CardNumber'],
    card_exp: [:string, 'CardExp'],
    account: [:string, 'Account'],
    routing: [:string, 'Routing'],
    check_format: [:string, 'CheckFormat'],
    record_type: [:string, 'RecordType']
  }
].inject(:merge)
CUSTOMER_TRANSACTION_REQUEST_OPTIONS = 
{
  command: [:string, 'Command'],
  ignore_duplicate: [:boolean, 'IgnoreDuplicate'],
  client_ip: [:string, 'ClientIP'],
  customer_receipt: [:boolean, 'CustReceipt'],
  customer_email: [:boolean, 'CustReceiptEmail'],
  customer_template: [:boolean, 'CustReceiptName'],
  merchant_receipt: [:boolean, 'MerchReceipt'],
  merchant_email: [:boolean, 'MerchReceiptEmail'],
  merchant_template: [:boolean, 'MerchReceiptName'],
  recurring: [:boolean, 'isRecurring'],
  verification_value: [:string, 'CardCode'],
  software: [:string, 'Software']
}
TRANSACTION_REQUEST_OBJECT_OPTIONS =

:nodoc:

{
  command: [:string, 'Command'],
  ignore_duplicate: [:boolean, 'IgnoreDuplicate'],
  authorization_code: [:string, 'AuthCode'],
  reference_number: [:string, 'RefNum'],
  account_holder: [:string, 'AccountHolder'],
  client_ip: [:string, 'ClientIP'],
  customer_id: [:string, 'CustomerID'],
  customer_receipt: [:boolean, 'CustReceipt'],
  customer_template: [:boolean, 'CustReceiptName'],
  software: [:string, 'Software']
}
TRANSACTION_DETAIL_OPTIONS =

:nodoc:

{
  invoice: [:string, 'Invoice'],
  po_number: [:string, 'PONum'],
  order_id: [:string, 'OrderID'],
  clerk: [:string, 'Clerk'],
  terminal: [:string, 'Terminal'],
  table: [:string, 'Table'],
  description: [:string, 'Description'],
  comments: [:string, 'Comments'],
  allow_partial_auth: [:boolean, 'AllowPartialAuth'],
  currency: [:string, 'Currency'],
  non_tax: [:boolean, 'NonTax']
}
TRANSACTION_DETAIL_MONEY_OPTIONS =

:nodoc:

{
  amount: [:double, 'Amount'],
  tax: [:double, 'Tax'],
  tip: [:double, 'Tip'],
  non_tax: [:boolean, 'NonTax'],
  shipping: [:double, 'Shipping'],
  discount: [:double, 'Discount'],
  subtotal: [:double, 'Subtotal']
}
CREDIT_CARD_DATA_OPTIONS =

:nodoc:

{
  magnetic_stripe: [:string, 'MagStripe'],
  dukpt: [:string, 'DUKPT'],
  signature: [:string, 'Signature'],
  terminal_type: [:string, 'TermType'],
  magnetic_support: [:string, 'MagSupport'],
  xid: [:string, 'XID'],
  cavv: [:string, 'CAVV'],
  eci: [:integer, 'ECI'],
  internal_card_authorization: [:boolean, 'InternalCardAuth'],
  pares: [:string, 'Pares']
}
CHECK_DATA_OPTIONS =

:nodoc:

{
  drivers_license: [:string, 'DriversLicense'],
  drivers_license_state: [:string, 'DriversLicenseState'],
  record_type: [:string, 'RecordType'],
  aux_on_us: [:string, 'AuxOnUS'],
  epc_code: [:string, 'EpcCode'],
  front_image: [:string, 'FrontImage'],
  back_image: [:string, 'BackImage']
}
RECURRING_BILLING_OPTIONS =

:nodoc:

{
  schedule: [:string, 'Schedule'],
  number_left: [:integer, 'NumLeft'],
  enabled: [:boolean, 'Enabled']
}
AVS_RESULTS =

:nodoc:

{
  'Y' => %w(YYY Y YYA YYD),
  'Z' => %w(NYZ Z),
  'A' => %w(YNA A YNY),
  'N' => %w(NNN N NN),
  'X' => %w(YYX X),
  'W' => %w(NYW W),
  'XXW' => %w(XXW),
  'XXU' => %w(XXU),
  'R' => %w(XXR R U E),
  'S' => %w(XXS S),
  'XXE' => %w(XXE),
  'G' => %w(XXG G C I),
  'B' => %w(YYG B M),
  'D' => %w(GGG D),
  'P' => %w(YGG P)
}.inject({}) do |map, (type, codes)|
  codes.each { |code| map[code] = type }
  map
end
AVS_CUSTOM_MESSAGES =

:nodoc:

{
  'XXW' => 'Card number not on file.',
  'XXU' => 'Address information not verified for domestic transaction.',
  'XXE' => 'Address verification not allowed for card type.'
}
TRANSACTION_METHODS = 
%i[
  run_sale run_auth_only run_credit
  run_check_sale run_check_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

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, #scrub, supported_countries, #supported_countries, supported_countries=, supports?, #supports_network_tokenization?, #supports_scrubbing?, #test?

Methods included from CreditCardFormatting

#expdate, #format

Methods included from PostsData

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

Constructor Details

#initialize(options = {}) ⇒ UsaEpayAdvancedGateway

Create a new gateway.

Required

  • At least the live_url OR the software_id must be present.

    • :software_id – 8 character software id

    OR

    • :test_url – full url for testing

    • :live_url – full url for live/production

Optional

  • :soap_response – set to true to add :soap_response to the params hash containing the entire soap xml message



271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 271

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

  if options[:software_id]
    self.live_url = "#{LIVE_URL_BASE}#{options[:software_id]}"
    self.test_url = "#{TEST_URL_BASE}#{options[:software_id]}"
  else
    self.live_url = options[:live_url].to_s
    self.test_url = options[:test_url].to_s if options[:test_url]
  end

  super
end

Instance Method Details

#add_customer(options = {}) ⇒ Object

Add a customer.

Options

  • :id – merchant assigned id

  • :notes – notes about customer

  • :data – base64 data about customer

  • :url – customer website

  • :billing_address – usual options

  • :payment_methods – array of payment method hashes.

    • :method – credit_card or check

    • :name – optional name/label for the method

    • :sort – optional integer value specifying the backup sort order, 0 is default

Recurring Options

  • :enabled – true enables recurring

  • :schedule – daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually, first of month, last day of month

  • :number_left – number of payments left; -1 for unlimited

  • :next – date of next payment (Date/Time)

  • :amount – amount of recurring payment

  • :tax – tax portion of amount

  • :currency – numeric currency code

  • :description – description of transaction

  • :order_id – transaction order id

  • :user – merchant username assigned to transaction

  • :source – name of source key assigned to billing

  • :send_receipt – true to send client a receipt

  • :receipt_note – leave a note on the receipt

Point of Sale Options

  • :price_tier – name of customer price tier

  • :tax_class – tax class

  • :lookup_code – lookup code from customer/member id card; barcode or magnetic stripe; can be assigned by merchant; defaults to system assigned if blank

Response

  • #message – customer number assigned by gateway



371
372
373
374
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 371

def add_customer(options = {})
  request = build_request(__method__, options)
  commit(__method__, request)
end

#add_customer_payment_method(options = {}) ⇒ Object

Add a payment method to a customer.

Required

  • :customer_number – number returned by add_customer response.message

  • :payment_method

    • :method – credit_card or check

    • :name – optional name/label for the method

    • :sort – an integer value specifying the backup sort order, 0 is default

Optional

  • :make_default – set true to make default

  • :verify – set true to run auth_only verification; throws fault if cannot verify

Response

  • #message – method_id of new customer payment method



482
483
484
485
486
487
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 482

def add_customer_payment_method(options = {})
  requires! options, :customer_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

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

Authorize an amount on a credit card or account.

Note: See run_transaction for additional options.



300
301
302
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 300

def authorize(money, creditcard, options = {})
  run_auth_only(options.merge!(amount: money, payment_method: creditcard))
end

#capture(money, identification, options = {}) ⇒ Object

Capture an authorized transaction.

Note: See run_transaction for additional options.



308
309
310
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 308

def capture(money, identification, options = {})
  capture_transaction(options.merge!(amount: money, reference_number: identification))
end

#capture_transaction(options = {}) ⇒ Object

Capture an authorized transaction and move it into the current batch for settlement.

Note: Check with merchant bank for details/restrictions on differing amounts than the original authorization.

Required

  • :reference_number

Options

  • :amount – may be different than original amount; 0 will void authorization

Response

  • #message – transaction response hash



724
725
726
727
728
729
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 724

def capture_transaction(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#credit(money, identification, options = {}) ⇒ Object 



328
329
330
331
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 328

def credit(money, identification, options = {})
  ActiveMerchant.deprecated CREDIT_DEPRECATION_MESSAGE
  refund(money, identification, options)
end

#delete_customer(options = {}) ⇒ Object

Delete a customer.

Required

  • :customer_number



559
560
561
562
563
564
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 559

def delete_customer(options = {})
  requires! options, :customer_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#delete_customer_payment_method(options = {}) ⇒ Object

Delete one the payment methods belonging to a customer

Required

  • :customer_number

  • :method_id



547
548
549
550
551
552
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 547

def delete_customer_payment_method(options = {})
  requires! options, :customer_number, :method_id

  request = build_request(__method__, options)
  commit(__method__, request)
end

#disable_customer(options = {}) ⇒ Object

Disable a customer for recurring billing.

Required

  • :customer_number



459
460
461
462
463
464
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 459

def disable_customer(options = {})
  requires! options, :customer_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#enable_customer(options = {}) ⇒ Object

Enable a customer for recurring billing.

Note: Customer does not need to have all recurring parameters to succeed.

Required

  • :customer_number



447
448
449
450
451
452
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 447

def enable_customer(options = {})
  requires! options, :customer_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#get_account_details ⇒ Object

Retrieve merchant account details

Response

  • #message – account hash



1022
1023
1024
1025
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 1022

def 
  request = build_request(__method__)
  commit(__method__, request)
end

#get_check_trace(options = {}) ⇒ Object

Check status of a check transaction.

Required

  • :reference_number

Response

  • #message – check trace hash



1008
1009
1010
1011
1012
1013
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 1008

def get_check_trace(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#get_customer_payment_method(options = {}) ⇒ Object

Retrieve one of the payment methods belonging to a customer

Required

  • :customer_number

  • :method_id

Response

  • #message – hash of payment method



513
514
515
516
517
518
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 513

def get_customer_payment_method(options = {})
  requires! options, :customer_number, :method_id

  request = build_request(__method__, options)
  commit(__method__, request)
end

#get_customer_payment_methods(options = {}) ⇒ Object

Retrieve all of the payment methods belonging to a customer

Required

  • :customer_number

Response

  • #message – either a single hash or an array of hashes of payment methods



497
498
499
500
501
502
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 497

def get_customer_payment_methods(options = {})
  requires! options, :customer_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#get_transaction(options = {}) ⇒ Object

Retrieve details of a specified transaction.

Required

  • :reference_number

Response

  • #message – transaction hash



878
879
880
881
882
883
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 878

def get_transaction(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#get_transaction_custom(options = {}) ⇒ Object

Check status of a transaction (custom).

Required

  • :reference_number

  • :fields – string array of fields to retrieve

    • Response.AuthCode

    • Response.AvsResult

    • Response.AvsResultCode

    • Response.BatchNum

    • Response.CardCodeResult

    • Response.CardCodeResultCode

    • Response.ConversionRate

    • Response.ConvertedAmount

    • Response.ConvertedAmountCurrency

    • Response.Error

    • Response.ErrorCode

    • Response.RefNum

    • Response.Result

    • Response.ResultCode

    • Response.Status

    • Response.StatusCode

    • CheckTrace.TrackingNum

    • CheckTrace.Effective

    • CheckTrace.Processed

    • CheckTrace.Settled

    • CheckTrace.Returned

    • CheckTrace.BankNote

    • DateTime

    • AccountHolder

    • Details.Invoice

    • Details.PoNum

    • Details.OrderID

    • Details.Clerk

    • Details.Terminal

    • Details.Table

    • Details.Description

    • Details.Amount

    • Details.Currency

    • Details.Tax

    • Details.Tip

    • Details.NonTax

    • Details.Shipping

    • Details.Discount

    • Details.Subtotal

    • CreditCardData.CardType

    • CreditCardData.CardNumber

    • CreditCardData.CardExpiration

    • CreditCardData.CardCode

    • CreditCardData.AvsStreet

    • CreditCardData.AvsZip

    • CreditCardData.CardPresent

    • CheckData.CheckNumber

    • CheckData.Routing

    • CheckData.Account

    • CheckData.SSN

    • CheckData.DriversLicense

    • CheckData.DriversLicenseState

    • CheckData.RecordType

    • User

    • Source

    • ServerIP

    • ClientIP

    • CustomerID

    • BillingAddress.FirstName

    • BillingAddress.LastName

    • BillingAddress.Company

    • BillingAddress.Street

    • BillingAddress.Street2

    • BillingAddress.City

    • BillingAddress.State

    • BillingAddress.Zip

    • BillingAddress.Country

    • BillingAddress.Phone

    • BillingAddress.Fax

    • BillingAddress.Email

    • ShippingAddress.FirstName

    • ShippingAddress.LastName

    • ShippingAddress.Company

    • ShippingAddress.Street

    • ShippingAddress.Street2

    • ShippingAddress.City

    • ShippingAddress.State

    • ShippingAddress.Zip

    • ShippingAddress.Country

    • ShippingAddress.Phone

    • ShippingAddress.Fax

    • ShippingAddress.Email

Response

  • #message – hash; keys are the field values



993
994
995
996
997
998
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 993

def get_transaction_custom(options = {})
  requires! options, :reference_number, :fields

  request = build_request(__method__, options)
  commit(__method__, request)
end

#get_transaction_status(options = {}) ⇒ Object

Check status of a transaction.

Required

  • :reference_number

Response

  • response.success – success of the referenced transaction

  • response.message – message of the referenced transaction

  • response.authorization – same as :reference_number in options



895
896
897
898
899
900
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 895

def get_transaction_status(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#override_transaction(options = {}) ⇒ Object

Override transaction flagged for manager approval.

Note: Checks only!

Required

  • :reference_number

Options

  • :reason

Response

  • #message – transaction response hash



780
781
782
783
784
785
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 780

def override_transaction(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#post_auth(options = {}) ⇒ Object

Post an authorization code obtained offline.

Required

  • :authorization_code – obtained offline

Options

  • Same as run_transaction

Response

  • #message – transaction response hash



702
703
704
705
706
707
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 702

def post_auth(options = {})
  requires! options, :authorization_code

  request = build_request(__method__, options)
  commit(__method__, request)
end

#purchase(money, creditcard, options = {}) ⇒ Object

Make a purchase with a credit card. (Authorize and capture for settlement.)

Note: See run_transaction for additional options.



292
293
294
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 292

def purchase(money, creditcard, options = {})
  run_sale(options.merge!(amount: money, payment_method: creditcard))
end

#quick_update_customer(options = {}) ⇒ Object

Update a customer by replacing only the provided fields.

Required

  • :customer_number – customer to update

  • :update_data – FieldValue array of fields to retrieve

    • :first_name

    • :last_name

    • :id

    • :company

    • :address

    • :address2

    • :city

    • :state

    • :zip

    • :country

    • :phone

    • :fax

    • :email

    • :url

    • :receipt_note

    • :send_receipt

    • :notes

    • :description

    • :order_id

    • :enabled

    • :schedule

    • :next

    • :num_left

    • :amount

    • :custom_data

    • :source

    • :user

    • :card_number

    • :card_exp

    • :account

    • :routing

    • :check_format or :record_type

Response

  • #message – boolean; Returns true if successful. Exception thrown all failures.



432
433
434
435
436
437
438
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 432

def quick_update_customer(options = {})
  requires! options, :customer_number
  requires! options, :update_data

  request = build_request(__method__, options)
  commit(__method__, request)
end

#refund(money, identification, options = {}) ⇒ Object

Refund a previous transaction.

Note: See run_transaction for additional options.



324
325
326
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 324

def refund(money, identification, options = {})
  refund_transaction(options.merge!(amount: money, reference_number: identification))
end

#refund_transaction(options = {}) ⇒ Object

Refund transaction.

Note: Required after a transaction has been settled. Refunds both credit card and check transactions.

Required

  • :reference_number

  • :amount – amount to refund; 0 will refund original amount

Response

  • #message – transaction response hash



760
761
762
763
764
765
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 760

def refund_transaction(options = {})
  requires! options, :reference_number, :amount

  request = build_request(__method__, options)
  commit(__method__, request)
end

#run_customer_transaction(options = {}) ⇒ Object

Run a transaction for an existing customer in the database.

Required Options

  • :customer_number – gateway assigned identifier

  • :command – Sale, AuthOnly, Credit, Check, CheckCredit

  • :amount – total amount

Options

  • :method_id – which payment method to use, 0/nil/omitted for default method

  • :ignore_duplicate – true overrides duplicate transaction

  • :client_ip – client ip address

  • :customer_receipt – true, sends receipt to customer. active_merchant defaults to false

  • :customer_email – specify if different than customer record

  • :customer_template – name of template

  • :merchant_receipt – true, sends receipt to merchant. active_merchant defaults to false

  • :merchant_email – required if :merchant_receipt set to true

  • :merchant_template – name of template

  • :recurring – defaults to false *see documentation*

  • :verification_value – pci forbids storage of this value, only required for CVV2 validation

  • :software – active_merchant sets to required gateway option value

  • :line_items – XXX not implemented yet

  • :custom_fields – XXX not implemented yet

Transaction Options

  • :invoice – transaction invoice number; truncated to 10 characters; defaults to reference_number

  • :po_number – commercial purchase order number; upto 25 characters

  • :order_id – should be used to assign a unique id; upto 64 characters

  • :clerk – sales clerk

  • :terminal – terminal name

  • :table – table name/number

  • :description – description

  • :comments – comments

  • :allow_partial_auth – allow partial authorization if full amount is not available; defaults false

  • :currency – numeric currency code

  • :tax – tax portion of amount

  • :tip – tip portion of amount

  • :non_tax – true if transaction is non-taxable

  • :shipping – shipping portion of amount

  • :discount – amount of discount

  • :subtotal – amount of transaction before tax, tip, shipping, and discount are applied

Response

  • #message – transaction response hash



610
611
612
613
614
615
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 610

def run_customer_transaction(options = {})
  requires! options, :customer_number, :command, :amount

  request = build_request(__method__, options)
  commit(__method__, request)
end

#run_quick_credit(options = {}) ⇒ Object

Run a credit based off of a past transaction.

Transfers referenced transaction’s payment method to this transaction. As of 6/2011, USA ePay blocks credit card numbers at 3 years.

Required

  • :reference_number – transaction to reference payment from

Transaction Options

  • :amount – total amount

  • :invoice – transaction invoice number; truncated to 10 characters; defaults to reference_number

  • :po_number – commercial purchase order number; upto 25 characters

  • :order_id – should be used to assign a unique id; upto 64 characters

  • :clerk – sales clerk

  • :terminal – terminal name

  • :table – table name/number

  • :description – description

  • :comments – comments

  • :allow_partial_auth – allow partial authorization if full amount is not available; defaults false

  • :currency – numeric currency code

  • :tax – tax portion of amount

  • :tip – tip portion of amount

  • :non_tax – true if transaction is non-taxable

  • :shipping – shipping portion of amount

  • :discount – amount of discount

  • :subtotal – amount of transaction before tax, tip, shipping, and discount are applied

Response

  • #message – transaction response hash



861
862
863
864
865
866
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 861

def run_quick_credit(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#run_quick_sale(options = {}) ⇒ Object

Run a sale transaction based off of a past transaction.

Transfers referenced transaction’s payment method to this transaction. As of 6/2011, USA ePay blocks credit card numbers at 3 years.

Required

  • :reference_number – transaction to reference payment from

  • :amount – total amount

Options

  • :authorize_only – set true if you just want to authorize

Transaction Options

  • :invoice – transaction invoice number; truncated to 10 characters; defaults to reference_number

  • :po_number – commercial purchase order number; upto 25 characters

  • :order_id – should be used to assign a unique id; upto 64 characters

  • :clerk – sales clerk

  • :terminal – terminal name

  • :table – table name/number

  • :description – description

  • :comments – comments

  • :allow_partial_auth – allow partial authorization if full amount is not available; defaults false

  • :currency – numeric currency code

  • :tax – tax portion of amount

  • :tip – tip portion of amount

  • :non_tax – true if transaction is non-taxable

  • :shipping – shipping portion of amount

  • :discount – amount of discount

  • :subtotal – amount of transaction before tax, tip, shipping, and discount are applied

Response

  • #message – transaction response hash



823
824
825
826
827
828
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 823

def run_quick_sale(options = {})
  requires! options, :reference_number, :amount

  request = build_request(__method__, options)
  commit(__method__, request)
end

#run_transaction(options = {}) ⇒ Object

Run a transaction.

Note: run_sale, run_auth_only, run_credit, run_check_sale, run_check_credit methods are also available. Each takes the same options as run_transaction, but the :command option is not required.

Recurring Note: If recurring options are included USA ePay will create a new customer record with the supplied information. The customer number will be returned in the response.

Options

  • :payment_method – credit_card or check

  • :command – sale, credit, void, creditvoid, authonly, capture, postauth, check, checkcredit; defaults to sale; only required for run_transaction when other than sale

  • :reference_number – for the original transaction; obtained by sale or authonly

  • :authorization_code – required for postauth; obtained offline

  • :ignore_duplicate – set true if you want to override the duplicate transaction handling

  • :account_holder – name of account holder

  • :customer_id – merchant assigned id

  • :customer_receipt – set true to email receipt to billing email address

  • :customer_template – name of template

  • :software – stamp merchant software version for tracking

  • :billing_address – see UsaEpayCimGateway documentation for all address fields

  • :shipping_address – see UsaEpayCimGateway documentation for all address fields

  • :recurring – used for recurring billing transactions

    • :schedule – disabled, daily, weekly, bi-weekly (every two weeks), monthly, bi-monthly (every two months), quarterly, bi-annually (every six months), annually

    • :next – date customer billed next (Date/Time)

    • :expire – date the recurring transactions end (Date/Time)

    • :number_left – transactions remaining in billing cycle

    • :amount – amount to be billed each recurring transaction

    • :enabled – states if currently active

  • :line_items – XXX not implemented yet

  • :custom_fields – XXX not implemented yet

Transaction Options

  • :amount – total amount

  • :invoice – transaction invoice number; truncated to 10 characters; defaults to reference_number

  • :po_number – commercial purchase order number; upto 25 characters

  • :order_id – should be used to assign a unique id; upto 64 characters

  • :clerk – sales clerk

  • :terminal – terminal name

  • :table – table name/number

  • :description – description

  • :comments – comments

  • :allow_partial_auth – allow partial authorization if full amount is not available; defaults false

  • :currency – numeric currency code

  • :tax – tax portion of amount

  • :tip – tip portion of amount

  • :non_tax – true if transaction is non-taxable

  • :shipping – shipping portion of amount

  • :discount – amount of discount

  • :subtotal – amount of transaction before tax, tip, shipping, and discount are applied

Response

  • #message – transaction response hash



674
675
676
677
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 674

def run_transaction(options = {})
  request = build_request(__method__, options)
  commit(__method__, request)
end

#update_customer(options = {}) ⇒ Object

Update a customer by replacing all of the customer details.

Required

  • :customer_number – customer to update

Options

* Same as add_customer



384
385
386
387
388
389
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 384

def update_customer(options = {})
  requires! options, :customer_number

  request = build_request(__method__, options)
  commit(__method__, request)
end

#update_customer_payment_method(options = {}) ⇒ Object

Update a customer payment method.

Required

  • :method_id – method_id to update

Options

  • :method – credit_card or check

  • :name – optional name/label for the method

  • :sort – an integer value specifying the backup sort order, 0 is default

  • :verify – set true to run auth_only verification; throws fault if cannot verify

Response

  • #message – hash of payment method



534
535
536
537
538
539
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 534

def update_customer_payment_method(options = {})
  requires! options, :method_id

  request = build_request(__method__, options)
  commit(__method__, request)
end

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

Void a previous transaction that has not been settled.

Note: See run_transaction for additional options.



316
317
318
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 316

def void(identification, options = {})
  void_transaction(options.merge!(reference_number: identification))
end

#void_transaction(options = {}) ⇒ Object

Void a transaction.

Note: Can only be voided before being settled.

Required

  • :reference_number

Response

  • #message – transaction response hash



741
742
743
744
745
746
 
# File 'lib/active_merchant/billing/gateways/usa_epay_advanced.rb', line 741

def void_transaction(options = {})
  requires! options, :reference_number

  request = build_request(__method__, options)
  commit(__method__, request)
end