To add a service reference to a project in Visual Studio

• In the “Solution Explorer,” select the project that will be using the USAePay service.
• Right-click on the project and choose “Add Service Reference.”

• The “Add Service Reference” dialog box will open.

• Populate the URL field with your USAePay generated WSDL link. For testing on sandbox you can use https://sandbox.usaepay.com/soap/gate/3213EA2A/usaepay.wsdl, but it is recommend that you generate your own wsdl link in the Developer Portal.
• Click “Go.”

• Change the namespace to “usaepay” and then click “OK.”

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

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 specific methods, please refer to the examples provided on each method's page. An index of current methods is available here.

The generation of an MD5 hash value requires that you import some .NET libraries 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

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.ueSoapServerPortTypeClient 'usaepay' is the name of your Web Reference

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

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 tab. 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 = "127.0.0.1"
        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

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

For questions please email devsupport@usaepay.com.