.NET Library v 4.0
| Platform | File | Size | Link |
|---|---|---|---|
| .NET v4.0 | Newtek GatewayAPI.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...
- Click on the "Browse" tab and select the Newtek GatewayAPI.dll file and click "Ok"
- Make sure you are on Framework ".NET Framework 4.6" or above
- To initialize the Newtek Gateway client in your code, instantiate Newtek GatewayAPI.Newtek Gateway:
:::vb Dim newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
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.
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 newtekgateway.com in order to close each batch.
Visual Basic
:::vb
Dim newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 5.0
newtek.Description = "Test Sale Transaction"
newtek.CardHolder = "Joe Schmoe"
newtek.CardNumber = "4000100011112224"
newtek.CardExp = "0919"
newtek.CustEmail = "test@test.com"
newtek.CustReceipt = True
' Uncomment the following line to use a non default receipt
' newtek.CustReceiptName = "My Receipt"
' Custom Data
newtek.Custom(1) = "Apples"
newtek.Custom(2) = "Oranges"
newtek.Custom(3) = "Pears"
newtek.Custom(4) = "Bananas"
newtek.Custom(5) = "Watermelon"
Try
newtek.Sale()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.ErrorCode & vbLf
End If
MsgBox(message)
Catch ex As Exception
MsgBox("Caught Exception: " & ex.Message)
End Try
C
<code c#>
private void RunSale()
{
Newtek GatewayAPI.Newtek Gateway newtek = new Newtek GatewayAPI.Newtek Gateway();
newtek.SourceKey = "_6S00RQ88NCS877A67lBNSycSJz8C4jO";
newtek.Pin = "1234";
newtek.Amount = 2.23;
newtek.Description = "A test transaction";
newtek.CardHolder = "Joe Schmoe";
newtek.CardNumber = "4000100011112224";
newtek.CardExp = "0919";
//For Sandbox accounts set to true
newtek.UseSandbox = true;
try
{
newtek.Sale();
if(newtek.ResultCode == "A")
{
lblStatus.Text = "Transaction approved\n" +
"Auth Code: " + newtek.AuthCode + "\n" +
"Ref Num: " + newtek.ResultRefNum + "\n" +
"AVS: " + newtek.AvsResult + "\n" +
"CVV: " + newtek.Cvv2Result;
}
else if(newtek.ResultCode == "D")
{
lblStatus.Text = "Transaction Declined\n" +
"Ref Num: " + newtek.ResultRefNum;
} else {
lblStatus.Text="Transaction Error\n" +
"Ref Num: " + newtek.ResultRefNum + "\n" +
"Error: " + newtek.ErrorMesg + "\n" +
"Error Code: " + newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 5.0
newtek.Description = "Test Sale Transaction"
newtek.CardHolder = "Joe Schmoe"
newtek.CardNumber = "4000100011112224"
newtek.CardExp = "0919"
newtek.CustEmail = "test@test.com"
newtek.CustReceipt = True
' Uncomment the following line to use a non default receipt
' newtek.CustReceiptName = "My Receipt"
' Custom Data
newtek.Custom(1) = "Apples"
newtek.Custom(2) = "Oranges"
newtek.Custom(3) = "Pears"
newtek.Custom(4) = "Bananas"
newtek.Custom(5) = "Watermelon"
Try
newtek.Credit()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = "5.00"
Try
newtek.Refund("56764522")
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
Try
newtek.Void("56765028")
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
Try
newtek.CreditVoid("56764950")
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.RefNum = "56753272"
newtek.Command = "void:release"
Try
newtek.Process()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 secure.newtekgateway.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 5.0
newtek.Description = "Test Sale Transaction"
newtek.CardHolder = "Joe Schmoe"
newtek.CardNumber = "4000100011112224"
newtek.CardExp = "0919"
newtek.CustEmail = "test@test.com"
newtek.CustReceipt = True
newtek.Command = "authonly"
' Uncomment the following line to use a non default receipt
' newtek.CustReceiptName = "My Receipt"
' Custom Data
newtek.Custom(1) = "Apples"
newtek.Custom(2) = "Oranges"
newtek.Custom(3) = "Pears"
newtek.Custom(4) = "Bananas"
newtek.Custom(5) = "Watermelon"
Try
newtek.Process()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 Newtek Gateway 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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 5.0
newtek.RefNum = "56756210"
newtek.Command = "capture"
Try
newtek.Process()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 5.0
newtek.Description = "Test Sale Transaction"
newtek.CardHolder = "Joe Schmoe"
newtek.CardNumber = "4000100011112224"
newtek.CardExp = "0919"
newtek.CustEmail = "test@test.com"
newtek.CustReceipt = True
newtek.Command = "postauth"
newtek.OrigAuthCode = "123456"
Try
newtek.Process()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = "5.00"
Try
newtek.QuickSale("56753272")
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 1.12
newtek.Description = "Test Sale Transaction"
newtek.CardHolder = "Joe Schmoe"
newtek.CheckAccount = "123456"
newtek.CheckRouting = "021000021"
newtek.CustEmail = "test@test.com"
newtek.CustReceipt = True
newtek.Command = "check"
' Uncomment the following line to use a non default receipt
' newtek.CustReceiptName = "My Receipt"
' Custom Data
newtek.Custom(1) = "Apples"
newtek.Custom(2) = "Oranges"
newtek.Custom(3) = "Pears"
newtek.Custom(4) = "Bananas"
newtek.Custom(5) = "Watermelon"
Try
newtek.Process()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim message As String
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
newtek.Amount = 12.99
newtek.Description = "Test Check Transaction"
newtek.CardHolder = "Joe Schmoe"
newtek.CheckAccount = "123456"
newtek.CheckRouting = "021000021"
newtek.CustEmail = "test@test.com"
newtek.CustReceipt = True
newtek.Command = "checkcredit"
Try
newtek.Process()
If newtek.ResultCode = "A" Then
message = "Transaction approved" & vbLf _
& "Auth Code: " & newtek.AuthCode & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "AVS: " & newtek.AvsResult & vbLf _
& "CVV: " & newtek.Cvv2Result
ElseIf newtek.ResultCode = "D" Then
message = "Transaction Declined" & vbLf _
& "Ref Num: " & newtek.ResultRefNum
Else
message = "Transaction Error" & vbLf _
& "Ref Num: " & newtek.ResultRefNum & vbLf _
& "Error: " & newtek.ErrorMesg & vbLf _
& "Error Code: " & newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
Dim batch As Newtek GatewayAPI.BatchStatus
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
newtek.Pin = "ABA123"
newtek.UseSandbox = True
Try
batch = newtek.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 newtek As Newtek GatewayAPI.Newtek Gateway = New Newtek GatewayAPI.Newtek Gateway
newtek.SourceKey = "_RXxdGjOYIfOUl0E22295o21J55Z4K84"
' Batch Closure requires a PIN
newtek.Pin = "ABA123"
' For Sandbox accounts set to true
newtek.UseSandbox = True
Dim batch As Newtek GatewayAPI.BatchStatus
' A batch number of "0" retreives info on currently open batch
Try
batch = newtek.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()
{
Newtek GatewayAPI.Newtek Gateway newtek = new Newtek GatewayAPI.Newtek Gateway();
Newtek GatewayAPI.BatchStatus batch = new Newtek GatewayAPI.BatchStatus();
//Init object with our source key and pin from newtekgateway.com
newtek.SourceKey = "_6S00RQ88NCS877A67lBNSycSJz8C4jO";
newtek.Pin = "1234";
//For Sandbox accounts set to true
newtek.UseSandbox = "true";
try
{
batch = newtek.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>
Newtek Gateway Class
Read/Write Properties
| Property | Type | Required | Description |
|---|---|---|---|
| Processing Settings | |||
| SourceKey | String | All | Source Key generated by the Merchant Console at secure.newtekgateway.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://secure.newtekgateway.com/gate. To use the secondary server pools set the url to https://secure.newtekgateway.com/gate or or https://secure-02.newtekgateway.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 Newtek Gateway 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 Newtek Gateway 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 | ||
| 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. newtek.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. newtek.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