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