Visual Basic Guide

Adding a Web Reference

To add a Web reference to a project in Visual Studio:

• In the "Solution Explorer", select the project that will be using the web service.
• Right-click on the project and choose "Add Web Reference".

• The "Add Web Reference" dialog box will open

• Populate the URL field with your Newtek Gateway generated WSDL link. For testing on sandbox you can use https://sandbox.newtekgateway.com/soap/gate/15E7FB61/newtek.wsdl but it is recommend that you generate your own wsdl link in the Developer's Center.

• Click 'Go'

• A security warning will appear, click 'Yes'
• Change the Web reference name to 'newtek' and then click 'Add Reference'

• You have now added a web reference called "newtek" to your project.

Using the Web Reference

To use the Newtek Gateway web reference, you must generate a "token" which authenticates your application to the gateway. This requires generating an MD5 hash value. The following steps walk through the process of creating this token. Once the token is created, running specific methods is fairly easy. For examples of a specific methods, please refer to the examples provide on each methods pages. An index of available methods is available here.

Step 1: Including required Imports

The generation of MD5 hash requires some .NET libraries be imported into your code. Typically these import statements will go at the top of the your code.

    Imports System
    Imports System.Web
    Imports System.IO
    Imports System.Security.Cryptography
    Imports System.Text

Step 2: Instantiating the client

The next step is to instantiate the client object. In the soap examples provided on this site, we use the variable 'client' for this object.

    Dim client As New newtek.newtekService 'newtek is the name of your Web Reference

Step 2b: Setting a Proxy Server (if needed)

If your network requires you to use a proxy server, the next step is to reference the proxy server. If you do not have a proxy server, skip this step.

    Dim proxycreds As New System.Net.NetworkCredential("user", "password", "Domain")
    Dim proxy As New System.Net.WebProxy("127.0.0.1", 80)

    proxy.Credentials = proxycreds
    client.Proxy = proxy

Step 3: Building Security token

The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin. The source key is created by the merchant in the Merchant Console under the Settings - API Keys screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.

    Dim token As New newtek.ueSecurityToken

    token.SourceKey = "ENTER_SOURCE_KEY_HERE"
    token.ClientIP = "127.0.0.1"
    token.PinHash = New newtek.ueHash

    token.PinHash.Seed = "5678" 'Hard coded seed for easy troubleshooting
    token.PinHash.Type = "md5"  'Type of encryption

    Dim prehashvalue As String
    prehashvalue = token.SourceKey & token.PinHash.Seed & "1234" 'Put together the pieces

    token.PinHash.HashValue = Me.GenerateHash(prehashvalue) 'Pass the prehashvalue to a GenerateHash function

The above code expects a "GenerateHash" method to be present in your class. Copy and paste the function below into your class.

    Private Function GenerateHash(ByVal SourceText As String) As String
            'Instantiate an MD5 Provider object
            Dim md5 As New MD5CryptoServiceProvider

            'Compute the hash value from the source
            Dim ByteHash() As Byte = md5.ComputeHash(Encoding.Default.GetBytes(SourceText))

            'Instantiate a StringBuilder object
            Dim sb As New StringBuilder

            'Repack binary hash as hex
            For c As Integer = 0 To ByteHash.Length - 1
                sb.AppendFormat("{0:x2}", ByteHash(c))
            Next c

            'Return the hex hash
            Return sb.ToString
    End Function

Handling Events

The visual studio webservice implementation allows you to subscribe to a "completed" event that will be raised when a soap call completes. The following code demonstrates how to subscribe to the addCustomerCompleted event:

    Private WithEvents client As newtek.newtekService

    Private Sub handleStatusUpdate(ByVal sender, ByVal ev As newtek.addCustomerCompletedEventArgs) Handles client.addCustomerCompleted

       MsgBox("Customer added!")

    End Sub

Additional Help

For questions please email support@newtekgateway.com