Ruby Library v1.0.2

Downloads

File	Version	Release Date	Description
usaepay_ruby_1.0.2.zip	1.0.2	04/17/15	Ruby Library 1.0.2

Library Overview

The USAePay Ruby Library provides an easy to use Ruby interface for running server to server processing. If you are developing your site using Ruby it is highly recommended that you use this script rather than the client side method. Not only will it provide a more consistent interface for your customers, but it will also prevent manipulation of order data.

When using this script, the basic flow will go something like: Customer enters creditcard data on merchant's server Script on merchant's server takes customer data and populates USAePay transaction (transaciton=UmTransaction.new) Merchant's server tells USAePay transaction to process (transaction.process) USAePay library sends transaction via SSL encrypted HTTP connection to USAePay for authorization USAePay library reads response from USAePay Library returns response to merchant's script Merchant's script interprets the result and displays the corresponding response to the customer

Trouble Shooting

Specified Source Key Not Found

I reviewed the usaepay documentation and downloaded the test files to make sure everything will run on our web server. I cannot successfully run the file "example_Transaction.rb". It returns the following:

Please Wait One Moment While We process your card. Card Declined (Error) Reason: Specified source key not found.

The source key in the example is a dummy key. Please generate your key at usaepay.com when you log into your USAePay Merchant Console. You can also generate keys from the test server however remember to change the gatewayurl property.

'require' No such file to load -- usaepay

If you are getting the following:

example_Transaction.rb:1:in `require': no such file to load -- usaepay (LoadError) // from example_Transaction.rb:1//

Make sure that you set up a correct path to the library. If you use Rails, place the file to the lib folder, or to the same directory where you have example.rb if you use Ruby

Examples

Example: Sale

The most common transaction is a Sale. The customer's creditcard will be authorized for the amount specified and placed in the batch for settlement. Once the batch is settled, the funds will be transferred to the merchant's account. Please note: unless merchants have configured their batch to auto close, they will need to log into usaepay.com to close their batch.

:::ruby
require 'usaepay'

tran=UmTransaction.new

# Merchants Source key must be generated within the console
tran.key="Your_source_key_here"

# Send request to sandbox server not production.  Make sure to comment or remove this line before
#  putting your code into production
tran.usesandbox=true

tran.card="4111111111111111"
tran.exp="0919"             
tran.amount="1.00"      
tran.invoice="1234"         
tran.cardholder="Test T Jones"  
tran.street="1234 Main Street"
tran.zip="90036"            
tran.description="Online Order"
tran.cvv2="435"         
tran.custom3="testest"
tran.pin="1234"

p "Please Wait One Moment While We process your card."

$stdout.flush

tran.process
if tran.resultcode.to_s=="A"
then
    p "Card approved"
    p "Authcode:  #{tran.authcode} "
    p "AVS Result: #{tran.avs_result} "
    p "Cvv2 Result: #{tran.cvv2_result} "
else
    p "Card Declined #{tran.result} "
    p "Reason: #{tran.error}"
end

Example: Auth Only (Queued Transaction)

The Auth Only transaction is extremely useful for companies that do not ship products right away. The gateway will authorize the charge but instead of putting the charge into the merchant's batch, the charge is placed on the Queued Transactions screen. This allows a merchant to verify that the customer's card is good and that they have the funds available. The merchant then has up to 30 days (depending on their bank) to "capture" the transaction once they are ready to ship the merchandise. There are two ways in which the transaction can be moved from the queued transactions screen to the current batch: 1) the merchant can log into www.usaepay.com and go to the queued transactions screen and select capture; 2) the transaction can be captured via the Ruby API. If you are planning on capturing transactions via the Ruby API, make sure to record the value of the refnum field. (See Capture Example)

:::ruby
require 'usaepay'

tran=UmTransaction.new

# Merchants Source key must be generated within the console
tran.key="Your_source_key_here"

# Send request to sandbox server not production.  Make sure to comment or remove this line before
#  putting your code into production
tran.usesandbox=true

tran.command="authonly"
tran.card="4111111111111111"
tran.exp="0919"             
tran.amount="1.00"      
tran.invoice="1234"         
tran.cardholder="Test T Jones"  
tran.street="1234 Main Street"
tran.zip="90036"            
tran.description="Online Order"
tran.cvv2="435"         
tran.custom3="testest"
tran.pin="1234"

p "Please Wait One Moment While We process your card."

$stdout.flush

tran.process
if tran.resultcode.to_s=="A"
then
    p "Card approved"
    p "Authcode:  #{tran.authcode} "
    p "AVS Result: #{tran.avs_result} "
    p "Cvv2 Result: #{tran.cvv2_result} "
else
    p "Card Declined #{tran.result} "
    p "Reason: #{tran.error}"
end

Example: Capture (Queued Transaction)

This command allows you to capture a previously authorized charge. An example of this would be a shopping cart that uses an order management system. When a customer places an order, the transaction is authorized and then queued. The merchant then logs into the shopping cart and marks the order as "Shipped." The shopping cart then tells USAePay to capture that transaction. To capture the transaction via the API, you must have the refnum returned during the original authorization. This value should be stored on the merchant's server.

:::ruby
require 'usaepay'

tran=UmTransaction.new

# Merchants Source key must be generated within the console
tran.key="Your_source_key_here"

# Send request to sandbox server not production.  Make sure to comment or remove this line before
#  putting your code into production
tran.usesandbox=true

tran.command="capture"
tran.pin="1234"
tran.refnum="123456789"

p "Please Wait One Moment While We Capture."

$stdout.flush

tran.process
if tran.resultcode.to_s=="A"
then
    p "Transaction Captured"
    p "Authcode:  #{tran.authcode} "
    p "AVS Result: #{tran.avs_result} "
    p "Cvv2 Result: #{tran.cvv2_result} "
else
    p "Unable to capture transaction #{tran.result} "
    p "Reason: #{tran.error}"
end

Example: Card Present transaction

:::ruby
require 'usaepay'

tran=UmTransaction.new

# Merchants Source key must be generated within the console
tran.key="Your_source_key_here"

# Send request to sandbox server not production.  Make sure to comment or remove this line before
#  putting your code into production
tran.usesandbox=true

tran.command="sale"
tran.pin="1234"
tran.cardpresent=true
tran.magstripe="%B4000100011112224^TESTCARD/VISA^220910100000000000672000000?;4000100011112224=22091010000067200000?"
tran.amount="1.00"
tran.invoice="12345"


p "Please Wait One Moment While We Process."

$stdout.flush

tran.process
if tran.resultcode.to_s=="A"
then
    p "Transaction Approved"
    p "Authcode:  #{tran.authcode} "
    p "AVS Result: #{tran.avs_result} "
    p "Cvv2 Result: #{tran.cvv2_result} "
else
    p "Unable to process transaction #{tran.result} "
    p "Reason: #{tran.error}"
end

Example: Add customer with recurring billing

:::ruby
require 'usaepay'

tran=UmTransaction.new

# Merchants Source key must be generated within the console
tran.key="Your_source_key_here"

# Send request to sandbox server not production.  Make sure to comment or remove this line before
#  putting your code into production
tran.usesandbox=true

tran.command="sale"
tran.pin="1234"
tran.amount="1.00"
tran.invoice="12345"

tran.card="4111111111111111"
tran.exp="0919"                     
tran.cardholder="Test T Jones"  
tran.street="1234 Main Street"
tran.zip="90036"            
tran.description="Online Order"
tran.cvv2="435"         
tran.custom3="testest"
tran.addcustomer="yes"
tran.schedule="weekly"
tran.billamount="10.00"


p "Please Wait One Moment While We Process."

$stdout.flush

tran.process
if tran.resultcode.to_s=="A"
then
    p "Transaction Approved"
    p "Authcode:  #{tran.authcode} "
    p "AVS Result: #{tran.avs_result} "
    p "Cvv2 Result: #{tran.cvv2_result} "
    p "Customer number: #{tran.custnum} "
else
    p "Unable to process transaction #{tran.result} "
    p "Reason: #{tran.error}"
end

Example: QuickCredit

:::ruby
require 'usaepay'

tran=UmTransaction.new

# Merchants Source key must be generated within the console
tran.key="Your_source_key_here"

# Send request to sandbox server not production.  Make sure to comment or remove this line before
#  putting your code into production
tran.usesandbox=true    
tran.pin="1234"
tran.amount="1.00"
tran.refnum="1234567"
tran.invoice="12345"

p "Please Wait One Moment While We Process."

$stdout.flush

tran.processQuickCredit

if tran.resultcode.to_s=="A"
then
    p "Transaction Approved"
    p "Authcode:  #{tran.authcode} "
else
    p "Unable to process transaction #{tran.result} "
    p "Reason: #{tran.error}"
end

Reference Tables

Read/Write Properties

Property	Description
proxyurl	If your server must send outgoing traffic through a proxy, set this property to the url of your proxy server. Make sure to include port if not on port 80. Example: http://proxy.mycompany.com:3128
gatewayurl	Optional. Allows you to override the default gateway url of https://www.usaepay.com/gate. To use the secondary server pools set the url to https://www-03.usaepay.com/gate or or https://www-02.usaepay.com/gate
General Properties
key	Source Key generated by the Merchant Console at www.usaepay.com.
pin	Pin for Source Key. This field is required only if the merchant has set a Pin in the merchant console.
command	Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, cc:save, refund and creditvoid Default is cc:sale.
allowpartialauth	Yes/No. Indicates whether to allow a partial authorization if the full UMamount is not available (for debit, prepaid and gift cards). If left blank or set to No, the transaction will be automatically canceled and reversed if full UMamount is not available
ifauthexpired	controls what happens when capturing an authorization that has expired. Options are 'ignore','error','reauth'.
authexpiredays	Set the number of days an authorization is valid for. Defaults to merchant account settings.
inventorylocation	Set the warehouse to pull inventory from. defaults to source key setting.
card	Credit Card Number with no spaces or dashes.
savecard	If set to true and the transaction has been approved, the system will issue a token for future use.
exp	Expiration Date in the form of MMYY with no spaces or punctuation.
amount	Charge amount without $. The amount field should include the total amount to be charged, including sales tax.
currency	Currency of "amount." Required if using a MCP based account. Must be one of the 3 digit numeric codes found here.
tax	The portion of amount that is sales tax.
nontaxable	Set to yes if transaction is not taxable. (optional, platform dependent)
tip	The portion of amount that is tip.
shipping	Shipping charges.
discount	Discount amount (ie gift certificate or coupon).
subtotal	Order subtotal. If set, then subtotal + tip + shipping - discount + tax must equal amount or the transaction will be declined. If subtotal is left blank, it will be ignored.
invoice	Unique ticket, invoice or order number. 10 digits.
orderid	Unique order identifier. Used to reference the order to which the transaction corresponds. This field can contain up to 64 characters and should be used instead of invoice when orderids longer that 10 digits are needed.
ponum	Customer purchase order number. Only required for commercial cards.
origauthcode	Originating Auth Code, required when running the postauth command. Typically used when a voice authorization is obtained.
custid	Alpha-numeric code that uniquely identifies the customer.
cardholder	Name as it appears on the creditcard.
street	Street Address for use in AVS check
zip	Zipcode for AVS check
description	Charge description (optional).
cvv2	CVC/CVV2 code (optional).
custemail	Customer Email address (optional).
custreceipt	Send a customer receipt. Note, this will override the source setting. (defaults to no)
custreceiptname	Use a custom email receipt template
ignoreduplicate	Suppresses the duplicate folding feature.
ip	IP Address of client browser, used for fraud checks. (optional)
timeout	Sets how long to wait, in seconds, for a reply from the gateway before returning an error. (optional, defaults to 45 seconds)
software	Allows developers to send the name and version of their application in to the gateway.
testmode	Use testmode. If set to yes then the transaction will be simulated but not actually processed. (optional, defaults to no)
usesandbox	If set to true will use the sandbox server. Overrides the gatewayurl parameter
transport	Override the connection library used. Either 'curl' or 'stream'. By default the library will be selected automatically.
clerk	Indicates the clerk/person processing transaction, for reporting purposes. (optional)
terminal	Indictes the terminal used to process transaction, for reporting purposes. (optional)
restaurant_table	Indicates the restaurant table, for reporting purposes. (optional)
Card Present Transactions
cardpresent	Marks transaction as a card present transaction. true or false
magstripe	Track 1, Track 2 or both Tracks read from credit card.
dukpt	DUK/PT key for Pin-Debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the Pin Pad serial number and transaction counter.
termtype	The type of terminal being used: Optons are POS (cash register), StandAlone (self service terminal), Unattended (ie gas pump), Unkown. (defaults to Unknown)
magsupport	Support for mag stripe reader: yes, no, contactless or unknown (default is unknown unless magstripe has been sent)
contactless	Magstripe was read via contactless swiper: yes or no (default is no)
signature	Raw cardholder signature captured by pos device. (does not need to be encoded)
Electronic Check Transactions
routing	Bank routing number. Required for check transactions.
account	Bank account number. Required for check transactions.
checkformat	Override default check record format.
dlnum	Driver's License Number. Required for check transactions if not using SSN.
dlstate	Driver's License Issuing State. Required for check transactions if not using SSN.
checknum	The checknumber. (optional)
checkimage_front	JPG image of front side of check. (optional). Use raw image data, do not encode using base64
checkimage_back	JPG image of back side of check. (optional)
auxonus	Aux On US for check 21
epccode	EPC Code for check 21
Customer Database and Recurring Billing
addcustomer	If set to yes and the transaction has been approved, the system will create a new customer record and store the payment information for future use. (Yes/No)
schedule	How often to run the transaction. Possible values are: daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, annually. Default is monthly. If you do not want to enable recurring billing for this customer, set schedule="disabled"
numleft	The number of times to left in billing cycle. Either a number or * for unlimited. (default is *)
start	When to start the schedule. Must be in YYYYMMDD format. To begin one billing period from today, set to "next." (For example, if today is 5/1/2007 and schedule is "monthly" the recurring billing will start on 6/1/2007.) If left blank, default is "tomorrow."
end	When to stop running transactions. Default is to run forever. If both end and numleft are specified, transaction will stop when the earliest condition is met.
billamount	Optional recurring billing amount. If not specified, the amount field will be used for future recurring billing charges.
billtax	Optional recurring billing tax. If not specified, the tax field will be used for future recurring billing charges.
billsourcekey	If set to true, for future recurring billing charges will be run using the same source key as the original transaction. By default recurring charges run using a source key labeled "Recurring".
Cardholder Authorization (Verified By Visa and Mastercard SecureCode)
cardauth	Enables Cardholder Authentication. The merchant must have a Cardinal Commerce account enabled in the gateway. If they don't have an account, this field will be ignored and the transaction will be processed normally (without authentication). Set cardauth=1 to enable cardholder authentication, set cardauth=0 to disable authentication. (defaults to disabled)
pares	The authentication response received from an independent authentication site.
Billing Address Fields
billfname
billlname
billcompany
billstreet
billstreet2
billcity
billstate
billzip
billcountry
billphone
email
fax
website
Shipping Address Fields (optional)
shipfname
shiplname
shipcompany
shipstreet
shipstreet2
shipcity
shipstate
shipzip
shipcountry
shipphone
Custom Data Fields (optional)
custom1
custom2
custom3
custom4
custom5
custom6
custom7
custom8
custom9
custom10
custom11
custom12
custom13
custom14
custom15
custom16
custom17
custom18
custom19
custom20

Functions

Function	Description
Process	Runs the transaction. Return true on Approved and false on Declined or Error.
addLine	Add lineitem data to transaction
getLineTotal	Method for calculating the total amount of the lines.
clearLines	Remove all lineitem data
clearData	Clear all transaction properties but retain the key, pin, software and gatewayurl
CheckData	Check data for errors. (runs automatically during the Process function)
ProcessQuickSale	Run a sale by referencing a previous sale (refnum must be set). No credit card or check data is required.
ProcessQuickCredit	Run a refund by referencing a previous sale (refnum must be set). No credit card or check data is required.
Test	Test Ruby. If errors are detected, suggested solutions will be displayed.

Read Properties

Property	Description
result	Full result: Approved, Declined, Error or Verification
resultcode	Single character result code: A,D,E or V
authcode	Authorization Code
refnum	Reference Number
cardref	Card reference token. 16-19 digit alphanumeric string. It is returned with dashes but it is not required that these be stored.
cardtype	The type of card that was submitted, ie “Visa”
maskednum	The masked out card number including the last 4 digits
batch	Batch Number
avs_result	The result of the AVS check.
cvv2_result	The result of the CVV2 check.
cardlevelresult	[developer:cardlevelcodes
vpas_result_code	The result of the cardholder authentication (CAVV)
isduplicate	When the duplicate folding feature is enabled, this will indicate when a transaction has been marked as a duplicate. All transaction data returned (authcode, refnum, etc), is from the original transaction.
error	Error if transaction is not approved.
errorcode	Numerical error code.
transporterror	This will contain any underlying connection errors received (useful for debugging curl/ssl installation).
acsurl	If the result was Verification, this field will contain the url that the customer must be sent to for authentication.
pareq	Contains the encrypted authentication request. This must be posted to the above url as the field "PaReq".
convertedamount	Amount converted to merchant's currency, when using a multi-currency processor.
convertedamountcurrency	Merchant's currency, when using a multi-currency processor.
conversionrate	Conversion rate used to convert currency, when using a multi-currency processor.
custnum	Customer reference number assigned by gateway for recurring transactions only.
procrefnum	Transaction Reference number provided by backend processor (platform), blank if not available
balance	The balance remaining on some prepaid and stored value cards
authamount	Amount authorized. May be less than amount requested if allowpartialauth was set true

Line Items

Line Items	Description
refnum	(optional) Gateway assigned product RefNum, used for inventory control.
sku	Product id, code or SKU
name	item name or short description
description	Long description
cost	Cost of item per unit of measure(before tax and discount)
qty	Quantity
taxable	1 = Taxable, 0 = Non-taxable
taxrate	Tax rate for line Required for level 3 processing
taxamount	Amount of tax charge for line Required for level 3 processing
um	Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used Required for level 3 processing
commoditycode	Commodity code Required for level 3 processing
discountrate	Discount percentage for line Required for level 3 processing
discountamount	Discount amount for line Required for level 3 processing
taxclass	Required for level 3 processing

Changelog

ver. 1.0.1 -> 1.0.2:
added getLineTotal and Test methods
added cc:save command
added Line Item fields: refnum, sku, name, description, cost, qty, taxable, taxrate, taxamount, um, commoditycode, discountrate, discountamount, taxclass
added response fields: cardref, cardtype, maskednum, transporterror
added additional fields: authexpiredays, inventorylocation, savecard, timeout, transport, clerk, terminal, restaurant_table, proxyurl, ifauthexpired
fixed the response logic
04/17/2015

ver. 1.0.0 -> 1.0.1:
added ProcessQuickCredit and ProcessQuickSale methods
03/01/2011