.NET Library v 4.0

Platform File Size Link
.NET v4.0 USAePayAPI.dll 295k 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...

alt text

  • Click on the "Browse" tab and select the USAePayAPI.dll file and click "Ok"

alt text

  • Make sure you are on Framework ".NET Framework 4.6" or above

alt text

  • To initialize the USAePay client in your code, instantiate USAePayAPI.USAePay: :::vb Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay

Updating for TLS 1.2 from Previous Versions

If you are using the DotNet DLL, you will not need to recompile your software, just update the .NET Framework to 4.5+.

.Net Framework 4.5 supports TLS 1.2 but does not use it by default, the following needs to be added before connecting:

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12

Found here https://blogs.perficient.com/microsoft/2016/04/tsl-1-2-and-net-support/

4.6+ Should support TLS 1.2 by default.

Next, drop in the replacement DLL file listed below according to the current version you are using.

If you are using version... Update to version:
Versions 1.** or 2.** DotNet DLL 2.0
Version 3.0 and above DotNet DLL 4.0

DotNet DLL Scanner Tool

The scanner tool listed below should locate your current DLL version, update it to be TLS 1.2 compatible and update your .NET Framework as well. Simply download and run the tool.

DotNet DLL Update Tool

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.

Example: 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

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 5.0
        usaepay.Description = "Test Sale Transaction"
        usaepay.CardHolder = "Joe Schmoe"
        usaepay.CardNumber = "4000100011112224"
        usaepay.CardExp = "0919"
        usaepay.CustEmail = "test@test.com"
        usaepay.CustReceipt = True
        ' Uncomment the following line to use a non default receipt
        ' usaepay.CustReceiptName = "My Receipt"

        ' Custom Data
        usaepay.Custom(1) = "Apples"
        usaepay.Custom(2) = "Oranges"
        usaepay.Custom(3) = "Pears"
        usaepay.Custom(4) = "Bananas"
        usaepay.Custom(5) = "Watermelon"

        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

<code c#> private void RunSale() { USAePayAPI.USAePay usaepay = new USAePayAPI.USAePay(); usaepay.SourceKey = "_6S00RQ88NCS877A67lBNSycSJz8C4jO"; usaepay.Pin = "1234"; usaepay.Amount = 2.23; usaepay.Description = "A test transaction"; usaepay.CardHolder = "Joe Schmoe"; usaepay.CardNumber = "4000100011112224"; usaepay.CardExp = "0919";

    //For Sandbox accounts set to true
    usaepay.UseSandbox = true;


    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;
    }
}

</code>

Example: Credit

The credit command is used to refund money to a credit card. It requires the credit card number and expiration date as well as the amount being refunded. This transaction is also referred to as an “Open Credit”. It does not associate the credit with an existing sale in the system. Some credit card processors do not support open credits. Merchants should verify with their provider before using this command. A safer alternative to the credit command is the “Refund” command. (see below). The credit is placed in the currently open batch. When the batch is closed the credit will be sent to the bank.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 5.0
        usaepay.Description = "Test Sale Transaction"
        usaepay.CardHolder = "Joe Schmoe"
        usaepay.CardNumber = "4000100011112224"
        usaepay.CardExp = "0919"
        usaepay.CustEmail = "test@test.com"
        usaepay.CustReceipt = True
        ' Uncomment the following line to use a non default receipt
        ' usaepay.CustReceiptName = "My Receipt"

        ' Custom Data
        usaepay.Custom(1) = "Apples"
        usaepay.Custom(2) = "Oranges"
        usaepay.Custom(3) = "Pears"
        usaepay.Custom(4) = "Bananas"
        usaepay.Custom(5) = "Watermelon"

        Try
            usaepay.Credit()
            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

Example: Refund

The 'refund' command allows the merchant to refund some or all of a previous sale transaction. It can be used with both credit card and check sales. It requires that the Transaction ID (RefNum) of the original sale be submitted. If the amount is not submitted, then the entire amount of the original sale will be refunded. The refund command will work for both credit card and check transactions. Not all check processors support refunds on checks so Merchants should verify with their provider that they can use this command.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True


        usaepay.Amount = "5.00"


        Try
            usaepay.Refund("56764522")
            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

Example: Void

The void command cancels a pending transaction. For credit card transactions, this command removes the transaction from the current batch. For ACH check transactions, the transaction is removed from the file that is sent to the bank. In both cases, there is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. For checks, a transaction can no longer be voided once the file has been sent to bank. This typically happens at the end of each business day. The void requires that the original transaction reference number be passed in the RefNum field.

Visual Basic

:::vb

        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True


        Try
            usaepay.Void("56765028")
            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

Example: CreditVoid

The CreditVoid command allows you to “credit back” or “void out” a transaction based on the original transaction reference number. The command automatically checks the status of the transaction, if the transaction has been settled then a credit (for all or part of the initial transaction) is entered into the current batch. If the transaction has not been settled then it will be voided (removed from the current settlement batch). The only required property for this command is the refnum property. The amount specified must be equal to or less than the original transaction. If no amount is specified, the full amount will be refunded. Note: for security reasons, this command requires that a pin be configured on the source key.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True



        Try
            usaepay.CreditVoid("56764950")
            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

Example: VoidRelease

The voidrelease command cancels a pending transaction. For credit card transactions, this command removes the transaction from the current batch. For ACH check transactions, the transaction is removed from the file that is sent to the bank. In both cases, there is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. For checks, a transaction can no longer be voided once the file has been sent to bank. This typically happens at the end of each business day. The void requires that the original transaction reference number be passed in the RefNum field. Difference between Void and VoidRelease is that VoidRelease speeds up the process of releasing customer's funds.

Visual Basic

:::vb

        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True


        usaepay.RefNum = "56753272"
        usaepay.Command = "void:release"


        Try
            usaepay.Process()
            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

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 .NET API. If you are planning on capturing transactions via the .NET API, make sure to record the value of the refnum field. (See Capture Example)

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 5.0
        usaepay.Description = "Test Sale Transaction"
        usaepay.CardHolder = "Joe Schmoe"
        usaepay.CardNumber = "4000100011112224"
        usaepay.CardExp = "0919"
        usaepay.CustEmail = "test@test.com"
        usaepay.CustReceipt = True
        usaepay.Command = "authonly"
        ' Uncomment the following line to use a non default receipt
        ' usaepay.CustReceiptName = "My Receipt"

        ' Custom Data
        usaepay.Custom(1) = "Apples"
        usaepay.Custom(2) = "Oranges"
        usaepay.Custom(3) = "Pears"
        usaepay.Custom(4) = "Bananas"
        usaepay.Custom(5) = "Watermelon"

        Try
            usaepay.Process()
            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

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.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 5.0
        usaepay.RefNum = "56756210"
        usaepay.Command = "capture"


        Try
            usaepay.Process()
            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

Example: PostAuth

The PostAuth command adds a transaction that was authorized outside of the gateway to the current batch. Typically this is used when a merchant obtains a Voice Authorization via the phone. To send a postauth transaction, the merchant must pass in the authorization code that was provided by bank in the OrigAuthCode field. The transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 5.0
        usaepay.Description = "Test Sale Transaction"
        usaepay.CardHolder = "Joe Schmoe"
        usaepay.CardNumber = "4000100011112224"
        usaepay.CardExp = "0919"
        usaepay.CustEmail = "test@test.com"
        usaepay.CustReceipt = True
        usaepay.Command = "postauth"
        usaepay.OrigAuthCode = "123456"


        Try
            usaepay.Process()
            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

Example: QuickSale

This method allows you to run a new transaction using the payment data from a previous transaction. Simply pass the reference number (RefNum) of the previous transaction and the gateway will automatically transfer the credit card or electronic check (ACH) information for use in the new transaction. Some credit card information, such as the card code and magnetic strip cannot be stored. This may cause the new transaction to come in at a higher rate than the original.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True


        usaepay.Amount = "5.00"


        Try
            usaepay.QuickSale("56753272")
            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

Example: Check Sale

The Check Sale command is used to debit money from a customers checking/savings account via ACH/EFT. To use this feature the merchant must have an account with a support check processor. To process a Check Sale, the customer's account number and ABA Routing number must be sent in the CheckAccount and CheckRouting fields.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 1.12
        usaepay.Description = "Test Sale Transaction"
        usaepay.CardHolder = "Joe Schmoe"
        usaepay.CheckAccount = "123456"
        usaepay.CheckRouting = "021000021"
        usaepay.CustEmail = "test@test.com"
        usaepay.CustReceipt = True
        usaepay.Command = "check"
        ' Uncomment the following line to use a non default receipt
        ' usaepay.CustReceiptName = "My Receipt"

        ' Custom Data
        usaepay.Custom(1) = "Apples"
        usaepay.Custom(2) = "Oranges"
        usaepay.Custom(3) = "Pears"
        usaepay.Custom(4) = "Bananas"
        usaepay.Custom(5) = "Watermelon"

        Try
            usaepay.Process()
            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

Example: Check Credit

The Check Credit command is used to send money to a customers checking/savings account via ACH/EFT. Funds will be transferred from the merchant's account and deposited into the customer's account. To use this feature the merchant must verify with their check processor that they can support this type of transaction. Check Credit transactions are not designed to be refunds on previous sales but rather to pay a 3rd party. Example uses include paying commissions to resellers or paying vendors/contractors. To refund an existing Check Credit transaction, the “Refund” command (see below) should be used. Due to the risk associated with processing Check Credit transactions, this command requires the use of a pin on the source key.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim message As String
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True

        usaepay.Amount = 12.99
        usaepay.Description = "Test Check Transaction"
        usaepay.CardHolder = "Joe Schmoe"
        usaepay.CheckAccount = "123456"
        usaepay.CheckRouting = "021000021"
        usaepay.CustEmail = "test@test.com"
        usaepay.CustReceipt = True
        usaepay.Command = "checkcredit"


        Try
            usaepay.Process()
            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

Example: Close Batch

"Close Batch" will close or settle an open batch. Upon settlement the funds will be transferred to the merchant's bank account. 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.

Visual Basic

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay
        Dim batch As USAePayAPI.BatchStatus
        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
        usaepay.Pin = "ABA123"
        usaepay.UseSandbox = True



        Try
            batch = usaepay.CloseBatch("0")
            MsgBox("Batch Closed successfully: " & 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 close batch: " & ex.Message)
        End Try

Example: 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

:::vb
        Dim usaepay As USAePayAPI.USAePay = New USAePayAPI.USAePay

        usaepay.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"

        ' Batch Closure requires a PIN
        usaepay.Pin = "ABA123"

        ' For Sandbox accounts set to true
        usaepay.UseSandbox = True

        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

<code 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 = "_6S00RQ88NCS877A67lBNSycSJz8C4jO";
    usaepay.Pin = "1234";

            //For Sandbox accounts set to true
            usaepay.UseSandbox = "true";

    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;
    }
}

</code>

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, void:release, authonly, capture, postauth, creditvoid, refund, check, checkcredit, cc:adjust, cc:save, giftcard:sale, giftcard:refund, giftcard:activate, giftcard:addvalue, giftcard:balance, giftcard:generate, giftcard:void and giftcard:transfer. *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)
GatewayTimeout Integer Sets how long to wait, in seconds, for a reply from the gateway before returning an error. (optional, defaults to 45 seconds)
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-03.usaepay.com/gate or or https://www-02.usaepay.com/gate
UseSandbox Boolean 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)
TestMode Boolean Use testmode. If set to True then the transaction will be simulated but not actually processed. (optional, defaults to False)
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.
Duty String Duty charge (Required only for level 3)
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), .. , Custom(20) String Optional custom data fields that are stored in the Transaction and/or Customer record. (Custom(1), Custom(2), etc.)
AllowPartialAuth Boolean True/False.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 False, the transaction will be automatically canceled and reversed if full Amount is not available
IfAuthExpired String controls what happens when capturing an authorization that has expired. Options are 'ignore','error','reauth'.
AuthExpireDays String Set the number of days an authorization is valid for. Defaults to merchant account settings.
InventoryLocation String Set the warehouse to pull inventory from. defaults to source key setting.
Clerk String Indicates the clerk/person processing transaction, for reporting purposes. (optional)
Terminal String Indictes the terminal used to process transaction, for reporting purposes. (optional)
Table String Indicates the restaurant table, for reporting purposes. (optional)
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).
SaveCard Boolean If set to true and the transaction has been approved, the system will issue a token for future use.
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 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.
SSN String Social Security Number for check transactions.
CheckImageFront String JPG image of front side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding
CheckImageBack String JPG image of back side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding
CheckImageEncoding String Encoding method used for check images. (Either base64 or raw). Be careful to avoid double encoding the data! Many check scanners output the image files already in base64 format. No additional encoding is required.
AuxOnUS String Aux On US for check 21
EpcCode String EPC Code for check 21
Recurring Billing
AddCustomer Boolean Save the transaction as a recurring transaction.Field name "Recurring" no longer supported starting V4.0
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.
BillTax Decimal Optional recurring billing tax. If not specified, the tax field will be used for future recurring billing charges.
BillSourceKey String 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”.
RecurringReceipt String Yes/No. Sends the Customer a Recurring Billing Receipt.
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
Line Items
LineRefNum(1), .. , LineRefNum(100) String (optional) Gateway assigned product RefNum, used for inventory control.
LineSku(1), .. , LineSku(100) String Product id, code or SKU
LineName(1), .. , LineName(100) String Item name or short description
LineDescription(1), .. , LineDescription(100) String Long description
LineCost(1), .. , LineCost(100) Decimal Cost of item, each
LineQty(1), .. , LineQty(100) Integer Quantity of item, each
LineTaxable(1), .. , LineTaxable(100) String Y = Taxable, N = Non-taxable
LineTaxRate(1), .. , LineTaxRate(100) Decimal Tax rate for line (only required for level 3 processing)
LineTaxAmount(1), .. , LineTaxAmount(100) Decimal Amount of tax charge for line (if left blank will be calculated from taxrate)
LineUm(1), .. , LineUm(100) String Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used. See list of valid unit of measure codes
LineCommodityCode(1),.., LineCommodityCode(100) String Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.
LineDiscountRate(1),.., LineDiscountRate(100) Decimal Discount percentage for line (only required for level 3 processing)
LineDiscountAmount(1),.., LineDiscountAmount(100) Decimal Discount amount for line (if left blank will be calculated from discountrate)
LineTaxClass(1), .. , LineTaxClass(100) String (only required for level 3 processing)
Lodging Industry
Folio String Folio Number
RoomRate String Nightly Room Rate
Nights String Number of nights
CheckInDate String Guest Check In Date
CheckOutDate String Guest Check Out Date
ExtraChargeReasons String Extra charge reasons
RoomNumber String Room number
CustomerCode String Customer code
LengthOfStay String Length of stay
RoomTaxRate String Room tax rate
NonRoomCharges String Non room charges
RoomTaxAmount String Room tax amount
PreferredCustomer String Preferred customer
ChargeType String Charge type
DepartureTime String Departure time
ArrivalTime String Arrival time

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
AuthAmount Amount authorized. May be less than amount requested if AllowPartialAuth=True
RemainingBalance Returns the balance remaining on some prepaid and stored value cards
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”
MaskedCardNum The masked out card number including the last 4 digits
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)
ResponseHash Response verification hash. (See Source Pin Code section for further details)

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.
Refund (String refNum) Boolean Refund a specific transaction.
Refund (String refNum, String Amount) Boolean Refund a specific transaction.
Refund (String refNum, Decimal Amount) Boolean Refund a specific transaction.
QuickSale (String refNum) Boolean Run a sale by referencing a previous sale (refNum must be set). No credit card or check data is required. usaepay.Amount should be set.
QuickCredit (String refNum) Boolean Run a credit by referencing a previous sale (refNum must be set). No credit card or check data is required. usaepay.Amount should be set.
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.

Changelog

ver. 4.0 -> 4.1:
Updated link to secondary URL

ver. 1.0, ver 2.0, and ver 3.0 No longer supported.  TLS 1.2 is only works with later versions of .Net
02/16/2017

ver. 3.0 -> 4.0:
Changed Amount to Decimal.
Changed Recurring to AddCustomer.
Added additional fields such as:GatewayTimeout, TestMode, CheckImageBack, CheckImageFront,CheckImageEncoding, AuxOnUS, EpcCode,InventoryLocation,AuthExpireDays, Duty,BillSourceKey,RecurringReceipt,BillTax,SaveCard etc.
Added Line Items Additional fields.
Added Lodging Industy fields.
Added CardType and MaskedCardNum property for cc:save.
Additional commands are now supported:giftcard:sale, giftcard:refund, giftcard:activate, giftcard:addvalue, giftcard:balance, giftcard:generate, giftcard:void and giftcard:transfer.
Added result properties: RemainingBalance, CardType, MaskedCardNum, AuthAmount.
11/09/2015

ver. 2.0 -> 3.0:
Added AllowPartialAuth property, SplitKey, SplitAmount, OnError for Split Payments support
Added Custom(1), .. , Custom(20) properties
Added Line Items support
Added CardRef property for cc:save
Fixed QuickSale, QuickCredit
10/10/2011