Soap API v1.3

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”.

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

usaepay.usaepayService client = new 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.

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

usaepay.ueSecurityToken token = new usaepay.ueSecurityToken();
token.SourceKey = "P11PON_ENTER_SOURCE_KEY_HERE_KSQr1VT81";
token.ClientIP = "";  // IP address of end user (if applicable)
string pin = "1234";   // pin assigned to source
usaepay.ueHash hash = new usaepay.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++)
            // 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:

                // 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)

Sample Code

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 portal and request a test account.

Additional 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.

developer/soap-1.3/howto/csharp.txt · Last modified: 2010/06/21 14:50 by tem

Page Tools