developer:soap-1.6:howto:csharp

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

developer:soap-1.6:howto:csharp [2012/08/04 11:49] (current)
tem created
Line 1: Line 1:
 +<embed ..:​contents/>​
 +
 +====== 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"​.
 +
 +{{:​developer:​soap:​howto:​addwebreference-csharp.png|}}
 +
 +  * The "Add Web 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/​1412E031/​usaepay.wsdl ​ but it is recommend that you generate your own wsdl link in the [[https://​www.usaepay.com/​developer/​|Developer Portal]]
 +  * Click '​Go'​
 +{{:​developer:​soap:​howto:​addwebreferencego.png|}}
 +
 +  * A security warning will appear, ​ click '​Yes' ​
 +  * Change the Web reference name to '​usaepay'​ and then click 'Add Reference'​
 +{{:​developer:​soap:​howto:​addreference.png|}} ​
 +  * 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 [[developer:​soap|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.
 +
 +<code c>
 +using System;
 +using System.Web;
 +using System.Security.Cryptography;​
 +using System.Text;​
 +</​code>​
 +
 +==== 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.
 +
 +<code c>
 +usaepay.usaepayService client = new usaepayService(); ​ //usaepay is the name of your Web Reference
 +</​code>​
 +
 +
 +
 +==== 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.
 +
 +<code c>
 +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;
 +</​code>​
 +
 +==== 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:​support|Merchant Console]] under the [[merchant:​console:​sources|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.
 +
 +<code c>
 +usaepay.ueSecurityToken token = new usaepay.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
 +
 +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
 +
 +</​code>​
 +
 +The above code expects a "​GenerateHash"​ method to be present in your class. ​ Copy and paste the function below into your class.  ​
 +
 +<code c>
 +       ​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();​
 +        }
 +</​code>​
 +
 +
 +==== 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:
 +
 +<code c>
 +            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);​
 +            }
 +</​code>​
 +
 +===== Sample Code =====
 +
 +[[http://​www.usaepay.com/​topics/​SoapExamplesCSharp-090827.zip|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 [[https://​www.usaepay.com/​developer/​login|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.6/howto/csharp.txt ยท Last modified: 2012/08/04 11:49 by tem

Page Tools