C# Soap 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".

alt text

  • 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/1412E031/newtek.wsdl but it is recommend that you generate your own wsdl link in the Developer's Center.

  • Click 'Go'

alt text

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

alt text

  • 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 headers

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

    using System;
    using System.Web;
    using System.Security.Cryptography;
    using 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.

    newtek.newtekService client = new 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.

    System.Net.NetworkCredential proxycreds = new System.Net.NetworkCredential("user", "password");
    System.Net.WebProxy proxy = new System.Net.WebProxy("127.0.0.1", 80); //address of proxy server
    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.

    newtek.ueSecurityToken token = new newtek.ueSecurityToken();

    token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81";
    token.ClientIP = "11.22.33.44";  // IP address of end user (if applicable)
    string pin = "1234";   // pin assigned to source

    newtek.ueHash hash = new newtek.ueHash();
    hash.Type = "md5";  // Type of encryption 
    hash.Seed = Guid.NewGuid().ToString();  // unique encryption seed

    string prehashvalue = string.Concat(token.SourceKey, hash.Seed, pin);  // combine data into single string
    hash.HashValue = GenerateHash(prehashvalue); // generate hash

    token.PinHash = hash;   // add hash value to token

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

    private static string GenerateHash(string input)
    {
        // Create a new instance of the MD5CryptoServiceProvider object.
        MD5 md5Hasher = MD5.Create();

        // Convert the input string to a byte array and compute the hash.
        byte[] data = md5Hasher.ComputeHash(Encoding.Default.GetBytes(input));

        // Create a new Stringbuilder to collect the bytes
        // and create a string.
        StringBuilder sBuilder = new StringBuilder();

        // Loop through each byte of the hashed data 
        // and format each one as a hexadecimal string.
        for (int i = 0; i < data.Length; i++)
        {
            sBuilder.Append(data[i].ToString("x2"));
        }

        // Return the hexadecimal string.
        return sBuilder.ToString();
    }

Step 4: Calling Soap Method

Now that you have a security token created you can make calls to the soap methods listed in the api. For example, to close the currently open credit credit card batch:

    try
    {
        // close current open batch
        result = client.closeBatch(token, "0");

        if (result) MessageBox.Show("Batch closed successfully");
        else MessageBox.Show("Batch failed to close");
    }
    catch (Exception err)
    {
        MessageBox.Show(err.Message);
    }

Sample Code

SoapExamplesCSharp-090827.zip

The above link is a zip file containing a Visual Studio project that provides some basic soap examples. To use the example project you must generate a source key on sandbox. If you do not have a sandbox account please log into the Developer's Center and request a test account.

Examples can be found on many of the method and object documentation pages. If you are working on a method that does not have an example posted in the documentation, please email developer support.