Soap API v1.2

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

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

  • You have now added a web reference called “usaepay” to your project.

Using the Web Reference

To use the USAePay 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 usaepay.usaepayService 'usaepay 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("", 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 - Sources 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 usaepay.ueSecurityToken
        token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81"
        token.ClientIP = ""
        token.PinHash = New usaepay.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 usaepay.usaepayService
Private Sub handleStatusUpdate(ByVal sender, ByVal ev As usaepay.addCustomerCompletedEventArgs) Handles client.addCustomerCompleted
   MsgBox("Customer added!")
End Sub

Additional Help

For questions please email

developer/soap-1.2/howto/vb.txt · Last modified: 2010/02/12 12:06 by epouchak

Page Tools