====== .NET Library v 1.7 ======
^ Platform ^ Build ^ File ^Size ^Link ^
| .NET v2.0 | 3377 | USAePayAPI-3377.zip | 58k |[[http://www.usaepay.com/topics/USAePayAPI-3377.zip|Download]]|
| .NET v1.0 | 2673 | USAePayAPI-2692-dotnet1.zip| 17k |[[http://www.usaepay.com/topics/USAePayAPI-2692-dotnet1.zip|Download]]|
===== Installation =====
To use this class in your Visual Studio project, follow these steps:
* Download and extract the zip file above
* Open your project in Visual Studio
* In the Solution Explorer, right click on your application and choose "Add Reference...
{{:developer:dotnet-solexp.png|}}
* Click on the "Browse" tab and select the USAePayAPI.dll file and click "Ok"
{{:developer:dotnet-selectdll.png|}}
* To initialize the USAePay client in your code, instantiate USAePayAPI.USAePay:
Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
===== Examples =====
The sample source key and pin used in each example has been provided for use in your testing. They have been configured to run on our test platform that allows for full testing of the transaction process. By using the samples provided, you can test run all commands, including closing/settling the batch. Any valid card number should return an approval, but you can also use the special test card numbers to receive specific responses.
==== Basic Sale ====
The most common transaction is a Sale. During a Sale, the customer's card will be authorized for the specified amount and placed in the batch for settlement. Once the batch has been settled, the funds will be transfered to the merchant's account. Please note: Unless the merchant's account has been configured to auto close, he or she will need to log into usaepay.com in order to close each batch.
=== Visual Basic ===
Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
Dim message As String
usaepay.SourceKey = "dgb8otyulg26vm2hYiF8b2q6P7091681"
usaepay.Pin = "ABA123"
usaepay.Amount = 2.23
usaepay.Description = "A test transaction"
usaepay.CardHolder = "Joe Schmoe"
usaepay.CardNumber = "4444555566667779"
usaepay.CardExp = "0909"
usaepay.IgnoreDupe = True
'For Sandbox accounts set to true
usaepay.UseSandbox = "false"
Try
usaepay.Sale()
If usaepay.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & usaepay.AuthCode & vbLf _
& "Ref Num: " & usaepay.ResultRefNum & vbLf _
& "AVS: " & usaepay.AvsResult & vbLf _
& "CVV: " & usaepay.Cvv2Result
ElseIf usaepay.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & usaepay.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & usaepay.ResultRefNum & vbLf _
& "Error: " & usaepay.ErrorMesg & vbLf _
& "Error Code: " & usaepay.ErrorCode & vbLf
End If
MsgBox(message)
Catch ex As Exception
MsgBox("Caught Exception: " & ex.Message)
End Try
=== C# ===
private void RunSale()
{
USAePayAPI.USAePay usaepay = new USAePayAPI.USAePay();
usaepay.SourceKey = "dgb8otyulg26vm2hYiF8b2q6P7091681";
usaepay.Pin = "ABA123";
usaepay.Amount = 2.23;
usaepay.Description = "A test transaction";
usaepay.CardHolder = "Joe Schmoe";
usaepay.CardNumber = "4444555566667779";
usaepay.CardExp = "0909";
//For Sandbox accounts set to true
usaepay.UseSandbox = "false"
try
{
usaepay.Sale();
if(usaepay.ResultCode == "A")
{
lblStatus.Text = "Transaction approved\n" +
"Auth Code: " + usaepay.AuthCode + "\n" +
"Ref Num: " + usaepay.ResultRefNum + "\n" +
"AVS: " + usaepay.AvsResult + "\n" +
"CVV: " + usaepay.Cvv2Result;
}
else if(usaepay.ResultCode == "D")
{
lblStatus.Text = "Transaction Declined\n" +
"Ref Num: " + usaepay.ResultRefNum;
} else {
lblStatus.Text="Transaction Error\n" +
"Ref Num: " + usaepay.ResultRefNum + "\n" +
"Error: " + usaepay.ErrorMesg + "\n" +
"Error Code: " + usaepay.ErrorCode;
}
}
catch(Exception x)
{
lblStatus.Text="ERROR: " + x.Message;
}
}
==== Batch Summary Request ====
This example shows you how to query the status of a specific batch to determine the total number of transactions and total monetary amount of the batch.
=== Visual Basic ===
Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
usaepay.SourceKey = "dgb8otyulg26vm2hYiF8b2q6P7091681"
' Batch Closure requires a PIN
usaepay.Pin = "ABA123"
' For Sandbox accounts set to true
usaepay.UseSandbox = "false"
Dim batch As USAePayAPI.BatchStatus
' A batch number of "0" retreives info on currently open batch
Try
batch = usaepay.BatchStatus("0")
MsgBox("Batch Status: " & vbLf _
& " Batch ID: " & batch.BatchID & vbLf _
& " Status: " & batch.Status & vbLf _
& " Transactions: " & batch.TransactionCount & vbLf _
& " Total: " & batch.Total & vbLf)
Catch ex As Exception
MsgBox("Unable to retreive batch status: " & ex.Message)
End Try
=== C# ===
private void GetBatchData()
{
USAePayAPI.USAePay usaepay = new USAePayAPI.USAePay();
USAePayAPI.BatchStatus batch = new USAePayAPI.BatchStatus();
//Init object with our source key and pin from usaepay.com
usaepay.SourceKey = "dgb8otyulg26vm2hYiF8b2q6P7091681";
usaepay.Pin = "ABA123";
//For Sandbox accounts set to true
usaepay.UseSandbox = "false";
try
{
batch = usaepay.BatchSummary("0");
lblStatus.Text = "Batch Status: \n" +
" Batch ID: " + batch.BatchID + "\n" +
" Status: " + batch.Status + "\n" +
" Transactions: " + batch.TransactionCount + "\n" +
" Total: " + batch.Total;
}
catch(Exception x)
{
lblStatus.Text="Unable to retreive batch status: " + x.Message;
}
}
===== USAePay Class =====
==== Read/Write Properties ====
^Property ^Type ^Required ^Description^
^Processing Settings^^^^
|SourceKey |String |All |Source Key generated by the Merchant Console at www.usaepay.com.|
|Pin |String |All* |Pin for Source Key. This field is required only if the merchant has set a Pin in the merchant console. * A pin must be set and used if using the CloseBatch() and BatchSummary() methods.|
|IgnoreDupe |Boolean| |Set this flag to allow a duplicate transaction to go through.|
|Command |String |* |Command to run; Possible values are: sale, credit, void, authonly, capture, postauth, creditvoid, refund, check and checkcredit. *This property only needs to be set if you are using the Process method. All other methods override the Command property. Default is sale.|
|Software |String| |Allows developers to send the name and version of their application in to the gateway.|
|ClientIP |String| |IP Address of client browser, used for fraud checks. (optional)|
|GatewayURL |String| |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-11.usaepay.com/gate or https://www-03.usaepay.com/gate or or https://www-02.usaepay.com/gate|
|UseSandbox |String| |Switches the API to use the sandbox environment. You must have a separate source key for the sandbox. A sandbox account can be requested in Developer Center. (optional)|
^Transaction Details^^^^
|Amount |Decimal |All |Charge amount without $. The amount field should include the total amount to be charged, including sales tax.|
|Currency |String |* |Three character currency code. * Should only be sent if using a multicurrency processor on a non USD transaction. Indicates the currency of Amount|
|Tax |Decimal| |The portion of amount that is sales tax.|
|NonTaxable |Boolean| |If true, indicates the transaction is for a non taxable item.|
|Tip |Decimal| |The portion of amount designated for a service tip.|
|Shipping |Decimal| |Shipping charge|
|Discount |Decimal| |Discount amount (i.e. gift certificate or coupon amount)|
|Subtotal |Decimal| |Order subtotal. If set, then subtotal + tip + shipping - discount + tax must equal amount or the transaction will be declined. If subtotal is left blank then it will be ignored.|
|Invoice |String| |Unique ticket, invoice or order number. 10 digits.|
|OrderID |String| |Unique order identifier. Used to reference the order that each transaction corresponds to. This field can contain up to 64 characters and should be used instead of invoice when an orderid is longer that 10 digits.|
|PoNum |String| |Customer purchase order number. Only required for commercial cards.|
|OrigAuthCode |String| |Originating Auth Code, required when running the postauth command. Typically this is given when a voice authorization is obtained.|
|CustID |String| |Alpha-numeric code that uniquely identifies the customer.|
|CardHolder |String| |Name as it appears on the card.|
|Description |String| |Charge description (optional).|
|Comments |String| |Merchant comment for transaction. Not displayed to customer (on receipt). Visible only on the transaction details screen in the console. |
|CustEmail |String| |Customer Email address (optional).|
|CustReceipt |Boolean| |Send a customer receipt. Note, this will override the source setting (defaults to no).|
|CustReceiptName |String| |Name of the custom receipt template to use. If omitted or if receipt not found, default customer receipt template will be used.|
|Custom[1-20] |String| |Optional custom data fields that are stored in the Transaction and/or Customer record. (Custom1, Custom2, etc.)|
^Credit Card Details^^^^
|CardNumber |String |CC |Credit Card Number with no spaces or dashes|
|CardExp |String |CC |Expiration Date in the form of MMYY with no spaces or punctuation|
|AvsStreet |String| |Street address for use in AVS check.|
|AvsZip |String| |Zipcode for AVS check.|
|Cvv2 |String| |CVC/CVV2 3-4 digit security code from back of credit card (optional).|
^Card Present Transactions^^^^
|CardPresent |Boolean| |Marks transaction as a card present transaction. true or false|
|MagStripe |String| |Data read from magnetic stripe on back of card. Track 1, Track 2 or both Tracks read from credit card.|
|Dukpt |String| |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.|
|Contactless |Boolean| |Card read via contactless swiper, yes/no. (defaults to no)|
|TermType |String| |The type of terminal being used: Options are POS - cash register, StandAlone - self service terminal, Unattended - ie gas pump, Unkown (defaults to Unknown).|
|Signature |String| |Base64 encode customer signature image block |
|MagSupport |String| |Support for mag stripe reader: yes, no or unknown (default is unknown unless magstripe has been sent)|
^Electronic Check Transactions^^^^
|CheckRouting |String |Check |Bank routing number. Required for check transactions.|
|CheckAccount |String |Check |Bank account number. Required for check transactions.|
|CheckNum |String| |Check Number. (optional)|
|AccountType |String| |"Checking" or "Savings". Defaults to "Checking" |
|CheckFormat |String| |[[merchant:checkformat|Format]] of ACH transaction. Should be omitted unless instructed by check processor |
|DLnum |String| |Drivers License Number. Required for check transactions if not using SSN.|
|DLstate |String| |Drivers License Issuing State. Required for check transactions if not using SSN.|
^Recurring Billing^^^^
|Recurring |Boolean| |Save the transaction as a recurring transaction. (Yes/No)|
|Schedule |String| |How often to run the transaction. Possible values are: daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, annually. Default is monthly.|
|NumLeft |String| |The number of times to run. Either a number or * for unlimited. Default is unlimited.|
|StartDate |String| |When to start the schedule. Must be in YYYYMMDD format. If left blank, default is "tomorrow."|
|EndDate |String| |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 |Decimal| |Optional recurring billing amount. If not specified, the amount field will be used for future recurring billing payments.|
^Cardholder Authorization (Verified By Visa and Mastercard SecureCode)^^^^
|CardAuth |String| |Enables USAePay Cardholder Authentication. The merchant must have a Cardinal Commerce account enabled in the gateway. If they don't have an account, then the this field will be ignored and the transaction will be processed normally (without attempting authentication). Set cardauth=1 to enable cardholder authentication, set cardauth=0 to disable authentication. (defaults to disabled) If using a thirdparty service (such as the Cardinal Commerce Thin Client) to perform authentication set this value to 0 and populate the CAVV and ECI fields)|
|Pares |String| |The authentication response received from independent authentication site.|
|CAVV |String| |The cavv provided by an external third party verification platform. Omit if using USAePay to perform verification. |
|ECI |String| |ECI value provided by external third party. Omit if you are not using third party verification. |
^Billing Address Information^^^^
|BillingFirstName |String|||
|BillingLastName |String |||
|BillingCompany |String |||
|BillingStreet |String |||
|BillingStreet2 |String |||
|BillingCity |String |||
|BillingState |String |||
|BillingZip |String |||
|BillingCountry |String |||
|BillingPhone |String |||
|Email |String |||
|Fax |String |||
|Website |String |||
^Shipping Address^^^^
|ShippingFirstName |String|||
|ShippingLastName |String|||
|ShippingCompany |String |||
|ShippingStreet |String |||
|ShippingStreet2 |String |||
|ShippingCity |String |||
|ShippingState |String |||
|ShippingZip |String |||
|ShippingCountry |String |||
|ShippingPhone |String |||
==== Read-Only Result 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|||
|Batch |Batch Number|||
|AvsResult |The Result of the AVS check.|||
|Cvv2Result |The result of the CVV2 check.|||
|VpasResultCode |The result of Verified by Visa/MC Sercure code cardholder authentication.|||
|CardLevelResult |For Visa cards, indicates the type of card |||
|ConvertedAmount |If transaction is multi-currency, this result value will contain the transaction amount converted to the merchant's currency.|||
|ConvertedAmountCurrency |The currency code of ConvertedAmount.|||
|ConversionRate |The conversion rate used to obtain ConvertedAmount|||
|ErrorCode |Numerical error code.|||
|ErrorMesg |Error message.|||
|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".|||
|IsDuplicate |Indicates that the transaction was matched as a duplicate and the original transaction details are being returned.|||
|CustNum |Customer reference number assigned by gateway for recurring transactions only.|||
|ProcRefNum |Transaction Reference number from processing backend (is provided) |||
==== Methods ====
^Function ^Returns ^Description^^
|Sale (Void) |Boolean |Runs a credit card sale using the parameters above. Any client side or network transport failures will throw an exception. If the server successfully received and processed the transaction, the Result Properties will be populated.||
|AuthOnly (Void) |Boolean |Run AuthOnly using the parameters set in properties of the web service object. Transaction will not be settled.||
|Capture (Void) (1/2) |Boolean |Mark transaction for settlement that was originally processed using AuthOnly.||
|Capture (String RefNum) (2/2) |Boolean |Mark transaction for settlement that was originally processed using AuthOnly.||
|PostAuth (Void) |Boolean |Runs post-auth routine using the parameters set in properties of the web service object.||
|Void (String RefNum) (1/2) |Boolean |Voids transaction specified by supplied reference number.|
|Void (Void) (2/2) |Boolean |Voids transaction specified by RefNum property of the web service object or via CardNumber, Amount and OrigAuthCode properties.||
|Credit (String RefNum) (1/2) |Boolean |Applies credit for full or partial amount of transaction specified by supplied reference number. If amount property is not set, full credit is applied.||
|Credit (Void) (2/2) |Boolean |Applies an open credit based on CardNumber, CardExp and Amount properties.||
|BatchSummary (String BatchID) |BatchStatus |Returns a BatchStatus object containing the information for the provided batch ID. Pass in "0" for the most recently opened batch.||
|CloseBatch (String BatchID) |BatchStatus |Closes the currently open batch. You can specify the batchID if you want to attempt to close a specific batch. An exception will be thrown if the batch is already closed. Pass "0" if you would like to close the currently open batch. A BatchStatus object will be returned on success.||
|eCheckSale (Void) |Boolean |Runs an eCheck sale using the parameters above. Any client side or network transport failures will throw an exception. If the server successfully received and processed the transaction, the Result Properties will be populated.||
|eCheckCredit (Void) |Boolean |Runs an eCheck credit using the parameters above. Any client side or network transport failures will throw an exception. If the server successfully received and processed the transaction, the Result Properties will be populated.||
|Process (Void) |Boolean |Runs command set in the command parameter. Any client side or network transport failures will throw an exception. If the server successfully received and processed the transaction, the Result Properties will be populated.||
==== Events ====
^Event ^Description^^^
|StatusChange(Done Boolean, StatusMessage String) |Event is sent to track progress of the transaction.|||
===== BatchStatus =====
The BatchStatus object is returned by batch related functions such as BatchSummary() and CloseBatch(). Below are the properties available in the BatchStatus Object.
==== Read/Write Properties ====
^Property ^Description^
|BatchID |ID of batch being reported on.|
|TransactionCount |Total number of transactions in batch (includes returns and voids).|
|Total |Total monetary amount of all transactions.|
|Status |Batch status (open/closed).|
===== Troubleshooting =====
==== Timeouts ====
The default timeout property (Public Timeout As Integer = 30) is set to 30 seconds. If you are experiencing transactions taking longer than 30 seconds to process changing this property to a higher value like 60 (seconds) will resolve the issue.