class ActiveMerchant::Billing::UsaEpayAdvancedGateway
USA ePay Advanced SOAP Interface¶ ↑
This class encapuslates 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:¶ ↑
-
Questions: post to active_merchant google group
-
Feedback/fixes: matt (at) nearapogee (dot) com
Links:¶ ↑
Constants
- API_VERSION
Public Class Methods
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 totrue
to add :soap_response to the params hash containing the entire soap xml message
ActiveMerchant::Billing::Gateway::new
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 237 def initialize(options = {}) requires!(options, :login, :password) if options[:software_id] self.live_url = "#{LIVE_URL_BASE}#{options[:software_id].to_s}" self.test_url = "#{TEST_URL_BASE}#{options[:software_id].to_s}" else self.live_url = options[:live_url].to_s self.test_url = options[:test_url].to_s if options[:test_url] end super end
Public Instance Methods
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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 337 def add_customer(options={}) request = build_request(__method__, options) commit(__method__, request) end
Add a payment method to a customer.
Required¶ ↑
-
:customer_number
– number returned byadd_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
– settrue
to make default -
:verify
– settrue
to run auth_only verification; throws fault if cannot verify
Response
¶ ↑
-
#message
– method_id of new customer payment method
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 399 def add_customer_payment_method(options={}) requires! options, :customer_number request = build_request(__method__, options) commit(__method__, request) end
Capture an authorized transaction.
Note: See run_transaction
for additional options.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 274 def capture(money, identification, options={}) capture_transaction(options.merge!(:amount => money, :reference_number => identification)) end
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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 641 def capture_transaction(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 294 def credit(money, identification, options={}) ActiveMerchant.deprecated CREDIT_DEPRECATION_MESSAGE refund(money, identification, options) end
Delete one the payment methods belonging to a customer
Required¶ ↑
-
:customer_number
-
:method_id
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 464 def delete_customer_payment_method(options={}) requires! options, :customer_number, :method_id request = build_request(__method__, options) commit(__method__, request) end
Enable a customer for recurring billing.
Note: Customer does not need to have all recurring parameters to succeed.
Required¶ ↑
-
:customer_number
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 364 def enable_customer(options={}) requires! options, :customer_number request = build_request(__method__, options) commit(__method__, request) end
Check
status of a check transaction.
Required¶ ↑
-
:reference_number
Response
¶ ↑
-
#message
– check trace hash
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 925 def get_check_trace(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
Retrive one of the payment methods belonging to a customer
Required¶ ↑
-
:customer_number
-
:method_id
Response
¶ ↑
-
#message
– hash of payment method
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 430 def get_customer_payment_method(options={}) requires! options, :customer_number, :method_id request = build_request(__method__, options) commit(__method__, request) end
Retrive 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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 414 def get_customer_payment_methods(options={}) requires! options, :customer_number request = build_request(__method__, options) commit(__method__, request) end
Retrieve details of a specified transaction.
Required¶ ↑
-
:reference_number
Response
¶ ↑
-
#message
– transaction hash
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 795 def get_transaction(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 910 def get_transaction_custom(options={}) requires! options, :reference_number, :fields request = build_request(__method__, options) commit(__method__, request) end
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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 812 def get_transaction_status(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
Override transaction flagged for manager approval.
Note: Checks only!
Required¶ ↑
-
:reference_number
Options¶ ↑
-
:reason
Response
¶ ↑
-
#message
– transaction response hash
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 697 def override_transaction(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
Post an authorization code obtained offline.
Required¶ ↑
-
:authorization_code
– obtained offline
Options¶ ↑
-
Same as
run_transaction
Response
¶ ↑
-
#message
– transaction response hash
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 619 def post_auth(options={}) requires! options, :authorization_code request = build_request(__method__, options) commit(__method__, request) end
Make a purchase with a credit card. (Authorize and capture for settlement.)
Note: See run_transaction
for additional options.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 258 def purchase(money, creditcard, options={}) run_sale(options.merge!(:amount => money, :payment_method => creditcard)) end
Refund a previous transaction.
Note: See run_transaction
for additional options.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 290 def refund(money, identification, options={}) refund_transaction(options.merge!(:amount => money, :reference_number => identification)) end
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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 677 def refund_transaction(options={}) requires! options, :reference_number, :amount request = build_request(__method__, options) commit(__method__, request) end
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 tofalse
-
:customer_email
– specify if different than customer record -
:customer_template
– name of template -
:merchant_receipt
–true
, sends receipt to merchant. active_merchant defaults tofalse
-
:merchant_email
– required if :merchant_receipt set totrue
-
:merchant_template
– name of template -
:recurring
– defaults tofalse
*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; defaultsfalse
-
: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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 527 def run_customer_transaction(options={}) requires! options, :customer_number, :command, :amount request = build_request(__method__, options) commit(__method__, request) end
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; defaultsfalse
-
: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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 778 def run_quick_credit(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
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
– settrue
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; defaultsfalse
-
: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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 740 def run_quick_sale(options={}) requires! options, :reference_number, :amount request = build_request(__method__, options) commit(__method__, request) end
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 forrun_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
– settrue
if you want to override the duplicate transaction handling -
:account_holder
– name of account holder -
:customer_id
– merchant assigned id -
:customer_receipt
– settrue
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; defaultsfalse
-
: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
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 591 def run_transaction(options={}) request = build_request(__method__, options) commit(__method__, request) end
Update a customer by replacing all of the customer details.
Required¶ ↑
-
:customer_number
– customer to update
Options¶ ↑
* Same as add_customer
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 350 def update_customer(options={}) requires! options, :customer_number request = build_request(__method__, options) commit(__method__, request) end
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
– settrue
to run auth_only verification; throws fault if cannot verify
Response
¶ ↑
-
#message
– hash of payment method
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 451 def update_customer_payment_method(options={}) requires! options, :method_id request = build_request(__method__, options) commit(__method__, request) end
Void a previous transaction that has not been settled.
Note: See run_transaction
for additional options.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 282 def void(identification, options={}) void_transaction(options.merge!(:reference_number => identification)) end
Void a transaction.
Note: Can only be voided before being settled.
Required¶ ↑
-
:reference_number
Response
¶ ↑
-
#message
– transaction response hash
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 658 def void_transaction(options={}) requires! options, :reference_number request = build_request(__method__, options) commit(__method__, request) end
Private Instance Methods
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1449 def avs_from(avs) avs_params = { :code => avs } avs_params.merge!(:message => AVS_CUSTOM_MESSAGES[avs]) if AVS_CUSTOM_MESSAGES.key?(avs) avs_params end
Customer ======================================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 988 def build_add_customer(soap, options) soap.tag! "ns1:addCustomer" do build_token soap, options build_customer_data soap, options build_tag soap, :double, 'Amount', amount(options[:amount]) build_tag soap, :double, 'Tax', amount(options[:tax]) build_tag soap, :string, 'Next', options[:next].strftime("%Y-%m-%d") if options[:next] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1022 def build_add_customer_payment_method(soap, options) soap.tag! "ns1:addCustomerPaymentMethod" do build_token soap, options build_tag soap, :integer, 'CustNum', options[:customer_number] build_customer_payment_methods soap, options build_tag soap, :boolean, 'MakeDefault', options[:make_default] build_tag soap, :boolean, 'Verify', options[:verify] end end
General Helpers ===============================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1385 def build_billing_address(soap, options) if options[:billing_address] if options[:billing_address][:name] name = options[:billing_address][:name].split(nil,2) # divide name options[:billing_address][:first_name], options[:billing_address][:last_name] = name[0], name[1] end soap.BillingAddress 'xsi:type' => "ns1:Address" do ADDRESS_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[:billing_address][k] end end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1166 def build_capture_transaction(soap, options) soap.tag! "ns1:captureTransaction" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] build_tag soap, :double, 'Amount', amount(options[:amount]) end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1342 def build_card_expiration(options) month = options[:payment_method].month year = options[:payment_method].year unless month.nil? || year.nil? "#{"%02d" % month}#{year.to_s[-2..-1]}" end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1350 def build_check_data(soap, options) soap.CheckData 'xsi:type' => "ns1:CheckData" do build_tag soap, :integer, 'CheckNumber', options[:payment_method].number build_tag soap, :string, 'Account', options[:payment_method].account_number build_tag soap, :string, 'Routing', options[:payment_method].routing_number build_tag soap, :string, 'AccountType', options[:payment_method].account_type.capitalize CHECK_DATA_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[k] end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1326 def build_credit_card_data(soap, options) soap.CreditCardData 'xsi:type' => "ns1:CreditCardData" do build_tag soap, :string, 'CardNumber', options[:payment_method].number build_tag soap, :string, 'CardExpiration', build_card_expiration(options) if options[:billing_address] build_tag soap, :string, 'AvsStreet', options[:billing_address][:address1] build_tag soap, :string, 'AvsZip', options[:billing_address][:zip] end build_tag soap, :string, 'CardCode', options[:payment_method].verification_value build_tag soap, :boolean, 'CardPresent', options[:card_present] || false CREDIT_CARD_DATA_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[k] end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1243 def build_credit_card_or_check(soap, payment_method) case when payment_method[:method].kind_of?(ActiveMerchant::Billing::CreditCard) build_tag soap, :string, 'CardNumber', payment_method[:method].number build_tag soap, :string, 'CardExpiration', "#{"%02d" % payment_method[:method].month}#{payment_method[:method].year.to_s[-2..-1]}" if options[:billing_address] build_tag soap, :string, 'AvsStreet', options[:billing_address][:address1] build_tag soap, :string, 'AvsZip', options[:billing_address][:zip] end build_tag soap, :string, 'CardCode', payment_method[:method].verification_value when payment_method[:method].kind_of?(ActiveMerchant::Billing::Check) build_tag soap, :string, 'Account', payment_method[:method].account_number build_tag soap, :string, 'Routing', payment_method[:method].routing_number unless payment_method[:method].account_type.nil? build_tag soap, :string, 'AccountType', payment_method[:method].account_type.capitalize end build_tag soap, :string, 'DriversLicense', options[:drivers_license] build_tag soap, :string, 'DriversLicenseState', options[:drivers_license_state] build_tag soap, :string, 'RecordType', options[:record_type] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1416 def build_custom_fields(soap, options) # TODO end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 998 def build_customer(soap, options, type, add_customer_data=false) soap.tag! "ns1:#{type}" do build_token soap, options build_tag soap, :integer, 'CustNum', options[:customer_number] build_customer_data soap, options if add_customer_data end end
Customer Helpers ==============================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1207 def build_customer_data(soap, options) soap.CustomerData 'xsi:type' => 'ns1:CustomerObject' do CUSTOMER_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[k] end build_billing_address soap, options build_customer_payments soap, options build_custom_fields soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1266 def build_customer_payment_methods(soap, options) payment_methods, tag_name = extract_methods_and_tag(options) payment_methods.each do |payment_method| soap.tag! tag_name, 'xsi:type' => "ns1:PaymentMethod" do build_tag soap, :integer, 'MethodID', payment_method[:method_id] build_tag soap, :string, 'MethodType', payment_method[:type] build_tag soap, :string, 'MethodName', payment_method[:name] build_tag soap, :integer, 'SecondarySort', payment_method[:sort] build_credit_card_or_check(soap, payment_method) end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1218 def build_customer_payments(soap, options) if options[:payment_methods] length = options[:payment_methods].length soap.PaymentMethods 'SOAP-ENC:arrayType' => "ns1:PaymentMethod[#{length}]", 'xsi:type' =>"ns1:PaymentMethodArray" do build_customer_payment_methods soap, options end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1279 def build_customer_transaction(soap, options) soap.Parameters 'xsi:type' => "ns1:CustomerTransactionRequest" do build_transaction_detail soap, options CUSTOMER_TRANSACTION_REQUEST_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[k] end build_custom_fields soap, options build_line_items soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1018 def build_delete_customer(soap, options) build_customer(soap, options, 'deleteCustomer') end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1052 def build_delete_customer_payment_method(soap, options) soap.tag! "ns1:deleteCustomerPaymentMethod" do build_token soap, options build_tag soap, :integer, 'Custnum', options[:customer_number] build_tag soap, :integer, 'PaymentMethodID', options[:method_id] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1014 def build_disable_customer(soap, options) build_customer(soap, options, 'disableCustomer') end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1010 def build_enable_customer(soap, options) build_customer(soap, options, 'enableCustomer') end
Account =======================================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1199 def build_get_account_details(soap, options) soap.tag! "ns1:getAccountDetails" do build_token soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1159 def build_get_check_trace(soap, options) soap.tag! "ns1:getCheckTrace" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1032 def build_get_customer_payment_method(soap, options) soap.tag! 'ns1:getCustomerPaymentMethod' do build_token soap, options build_tag soap, :integer, 'CustNum', options[:customer_number] build_tag soap, :integer, 'MethodID', options[:method_id] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1040 def build_get_customer_payment_methods(soap, options) build_customer(soap, options, 'getCustomerPaymentMethods') end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1137 def build_get_transaction(soap, options) soap.tag! "ns1:getTransaction" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1151 def build_get_transaction_custom(soap, options) soap.tag! "ns1:getTransactionCustom" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] build_transaction_field_array soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1144 def build_get_transaction_status(soap, options) soap.tag! "ns1:getTransactionStatus" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1413 def build_line_items(soap, options) # TODO end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1189 def build_override_transaction(soap, options) soap.tag! "ns1:overrideTransaction" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] build_tag soap, :string, 'Reason', options[:reason] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1113 def build_post_auth(soap, options) soap.tag! 'ns1:postAuth' do build_token soap, options build_transaction_request_object soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1362 def build_recurring_billing(soap, options) if options[:recurring] soap.RecurringBilling 'xsi:type' => "ns1:RecurringBilling" do build_tag soap, :double, 'Amount', amount(options[:recurring][:amount]) build_tag soap, :string, 'Next', options[:recurring][:next].strftime("%Y-%m-%d") if options[:recurring][:next] build_tag soap, :string, 'Expire', options[:recurring][:expire].strftime("%Y-%m-%d") if options[:recurring][:expire] RECURRING_BILLING_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[:recurring][k] end end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1181 def build_refund_transaction(soap, options) soap.tag! "ns1:refundTransaction" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] build_tag soap, :integer, 'Amount', amount(options[:amount]) end end
Build soap header, etc.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 949 def build_request(action, options = {}) soap = Builder::XmlMarkup.new soap.instruct!(:xml, :version => '1.0', :encoding => 'utf-8') soap.tag! "SOAP-ENV:Envelope", 'xmlns:SOAP-ENV' => 'http://schemas.xmlsoap.org/soap/envelope/', 'xmlns:ns1' => 'urn:usaepay', 'xmlns:xsd' => 'http://www.w3.org/2001/XMLSchema', 'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance', 'xmlns:SOAP-ENC' => 'http://schemas.xmlsoap.org/soap/encoding/', 'SOAP-ENV:encodingStyle' => 'http://schemas.xmlsoap.org/soap/encoding/' do soap.tag! "SOAP-ENV:Body" do send("build_#{action}", soap, options) end end soap.target! end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1433 def build_response(action, soap) response_params, success, message, authorization, avs, cvv = parse(action, soap) response_params.merge!('soap_response' => soap) if @options[:soap_response] Response.new( success, message, response_params, :test => test?, :authorization => authorization, :avs_result => avs_from(avs), :cvv_result => cvv ) end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1085 def build_run_auth_only(soap, options) soap.tag! 'ns1:runAuthOnly' do build_token soap, options build_transaction_request_object soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1106 def build_run_check_credit(soap, options) soap.tag! 'ns1:runCheckCredit' do build_token soap, options build_transaction_request_object soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1099 def build_run_check_sale(soap, options) soap.tag! 'ns1:runCheckSale' do build_token soap, options build_transaction_request_object soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1092 def build_run_credit(soap, options) soap.tag! 'ns1:runCredit' do build_token soap, options build_transaction_request_object soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1060 def build_run_customer_transaction(soap, options) soap.tag! "ns1:runCustomerTransaction" do build_token soap, options build_tag soap, :integer, 'CustNum', options[:customer_number] build_tag soap, :integer, 'PaymentMethodID', options[:method_id] || 0 build_customer_transaction soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1129 def build_run_quick_credit(soap, options) soap.tag! 'ns1:runQuickCredit' do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] build_transaction_detail soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1120 def build_run_quick_sale(soap, options) soap.tag! 'ns1:runQuickSale' do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] build_transaction_detail soap, options build_tag soap, :boolean, 'AuthOnly', options[:authorize_only] || false end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1078 def build_run_sale(soap, options) soap.tag! 'ns1:runSale' do build_token soap, options build_transaction_request_object soap, options end end
Transactions ==================================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1071 def build_run_transaction(soap, options) soap.tag! 'ns1:runTransaction' do build_token soap, options build_transaction_request_object soap, options, 'Parameters' end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1399 def build_shipping_address(soap, options) if options[:shipping_address] if options[:shipping_address][:name] name = options[:shipping_address][:name].split(nil,2) # divide name options[:shipping_address][:first_name], options[:shipping_address][:last_name] = name[0], name[1] end soap.ShippingAddress 'xsi:type' => "ns1:Address" do ADDRESS_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[:shipping_address][k] end end end end
Build generic tag.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 967 def build_tag(soap, type, tag, value) soap.tag!(tag, value, 'xsi:type' => "xsd:#{type}") if value != nil end
Build token.
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 972 def build_token(soap, options) seed = SecureRandom.base64(32) hash = Digest::SHA1.hexdigest("#{@options[:login]}#{seed}#{@options[:password].to_s.strip}") soap.Token 'xsi:type' => 'ns1:ueSecurityToken' do build_tag soap, :string, 'ClientIP', options[:client_ip] soap.PinHash 'xsi:type' => 'ns1:ueHash' do build_tag soap, :string, "HashValue", hash build_tag soap, :string, "Seed", seed build_tag soap, :string, "Type", 'sha1' end build_tag soap, :string, 'SourceKey', @options[:login] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1315 def build_transaction_detail(soap, options) soap.Details 'xsi:type' => "ns1:TransactionDetail" do TRANSACTION_DETAIL_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[k] end TRANSACTION_DETAIL_MONEY_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], amount(options[k]) end end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1375 def build_transaction_field_array(soap, options) soap.Fields 'SOAP-ENC:arryType' => "xsd:string[#{options[:fields].length}]", 'xsi:type' => 'ns1:stringArray' do options[:fields].each do |field| build_tag soap, :string, 'item', field end end end
Transaction Helpers ===========================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1292 def build_transaction_request_object(soap, options, name='Params') soap.tag! name, 'xsi:type' => "ns1:TransactionRequestObject" do TRANSACTION_REQUEST_OBJECT_OPTIONS.each do |k,v| build_tag soap, v[0], v[1], options[k] end case when options[:payment_method] == nil when options[:payment_method].kind_of?(ActiveMerchant::Billing::CreditCard) build_credit_card_data soap, options when options[:payment_method].kind_of?(ActiveMerchant::Billing::Check) build_check_data soap, options else raise ArgumentError, 'options[:payment_method] must be a CreditCard or Check' end build_transaction_detail soap, options build_billing_address soap, options build_shipping_address soap, options build_recurring_billing soap, options build_line_items soap, options build_custom_fields soap, options end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1006 def build_update_customer(soap, options) build_customer(soap, options, 'updateCustomer', true) end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1044 def build_update_customer_payment_method(soap, options) soap.tag! 'ns1:updateCustomerPaymentMethod' do build_token soap, options build_customer_payment_methods soap, options build_tag soap, :boolean, 'Verify', options[:verify] end end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1174 def build_void_transaction(soap, options) soap.tag! "ns1:voidTransaction" do build_token soap, options build_tag soap, :integer, 'RefNum', options[:reference_number] end end
Request =======================================================
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1421 def commit(action, request) url = test? ? test_url : live_url begin soap = ssl_post(url, request, "Content-Type" => "text/xml") rescue ActiveMerchant::ResponseError => error soap = error.response.body end build_response(action, soap) end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1228 def extract_methods_and_tag(options) case when options[:payment_method] && !options[:payment_methods] payment_methods = [options[:payment_method]] tag_name = 'PaymentMethod' when options[:payment_methods] && !options[:payment_method] payment_methods = options[:payment_methods] tag_name = 'item' else payment_methods = [options] tag_name = 'PaymentMethod' end [payment_methods, tag_name] end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1455 def parse(action, soap) xml = REXML::Document.new(soap) root = REXML::XPath.first(xml, "//SOAP-ENV:Body") response = root ? parse_element(root[0]) : { :response => soap } success, message, authorization, avs, cvv = false, FAILURE_MESSAGE, nil, nil, nil fault = (!response) || (response.length < 1) || response.has_key?('faultcode') return [response, success, response['faultstring'], authorization, avs, cvv] if fault if response.respond_to?(:[]) && p = response["#{action}_return"] if p.respond_to?(:key?) && p.key?('result_code') success = p['result_code'] == 'A' ? true : false authorization = p['ref_num'] avs = AVS_RESULTS[p['avs_result_code']] cvv = p['card_code_result_code'] else success = true end message = case action when :get_customer_payment_methods p['item'] when :get_transaction_custom items = p['item'].kind_of?(Array) ? p['item'] : [p['item']] items.inject({}) { |hash, item| hash[item['field']] = item['value']; hash } else p end elsif response.respond_to?(:[]) && p = response[:response] message = p # when response is html end [response, success, message, authorization, avs, cvv] end
# File lib/active_merchant/billing/gateways/usa_epay_advanced.rb, line 1490 def parse_element(node) if node.has_elements? response = {} node.elements.each do |e| key = e.name.underscore value = parse_element(e) if response.has_key?(key) if response[key].is_a?(Array) response[key].push(value) else response[key] = [response[key], value] end else response[key] = parse_element(e) end end else response = node.text end response end