Sagepay are a card payment provider. There is a new Sagepay API to manage the actions that are normally accessed through the account management web portal “MySagePay”. At time of writing it is in restricted Beta. As it is not open I feel unable to disclose everything about how it works, but if you are using the beta service with .NET then parts of my wrapper may be useful to you.

To get in on the Beta, go into the Sagepay website Access forum and PM Joe in support who will send you the API documents. If you want my .NET wrapper for Access then I don’t mind sharing but would need to confirm with you that you have been given the Beta documentation first.

LINQ to XML seemed like the best way forward so here goes;

Prepare the XML

I’ve left out the command name, you can replace it if you have the API documentation as you will know what it is. For each call in the API you start with the same XML fragment then append the relevant parameters to it.

Public Shared Function lockUserXMLRequest( _

 ByVal VendorID As String, ByVal UserName As String, ByVal Password As String, _

                      ByVal lockusername As String) As XElement

    If lockusername.Length > 20 Then Throw New ArgumentException("username must be 20 characters maximum", _

         "lockusername", Nothing)

    Dim SagePayRequestXML As XElement = New Credentials("[commandname]", VendorID, UserName, Password)

    SagePayRequestXML.Element("user").AddAfterSelf(<username><%= lockusername %></username>)

    Return HashRequestxml(SagePayRequestXML)

End Function

Public Class Credentials

    Inherits XElement

    Public Sub New(ByVal Command As String, ByVal VendorID As String, _

                   ByVal UserName As String, ByVal Password As String)

        MyBase.New("vspaccess")

        If UserName.Length > 20 Then

            Throw New ArgumentException("UserName maximum of 20 character", "UserName", Nothing)

        End If

        If VendorID.Length > 16 Then

            Throw New ArgumentException("VendorID maximum of 16 character", "VendorID", Nothing)

        End If

        If Password.Length > 32 Then

            Throw New ArgumentException("Password maximum of 32 character", "Password", Nothing)

        End If

        Me.Add(<command><%= Command %></command>)

        Me.Add(<vendor><%= VendorID %></vendor>)

        Me.Add(<user><%= UserName %></user>)

        Me.Add(<password><%= Password %></password>)

    End Sub

End Class

Hash the request

Once you have the XML it is hashed with your vendor password, the password must be removed before the XML is submitted to Sagepay;

Private Shared Function HashRequestxml(ByVal RequestElement As XElement) As XElement

    ''Is there a better way to convert xElement() to string?

    Dim sb As New StringBuilder

    For Each currentElement In RequestElement.Elements

        sb.Append(currentElement.ToString)

    Next

    ' Get the "inner xml" of the element

    Dim oReader = RequestElement.CreateReader()

    oReader.MoveToContent()

    Dim asstring = oReader.ReadInnerXml()

    'Hash the request and password element together and use the result

    ' as the signature

    Dim signature As XElement = _

            <signature><%= getMd5Hash(asstring) %></signature>

    'Now remove the password, not required now hash generated

    RequestElement.Element("password").Remove()

    RequestElement.Add(signature)

    Return RequestElement

End Function

Note: A post in the Sagepay forum indicates that the final Access may be significantly different to the current one in use. See: Our improved Reporting & Admin API is coming...

A note to myself, if you have an xElement and want to get just the inner xml then this is the way to do it:

' Get the "inner xml" of the element

Dim oReader = RequestElement.CreateReader()

oReader.MoveToContent()

Dim asstring = oReader.ReadInnerXml()

If you need to integrate with Microsoft Dynamics GP one of the options you may choose is to use the eConnect product. eConnect is an API that allows you to submit XML documents to Dynamics GP to perform CRUD operations on most of the document types in GP. Using .NET for integrations, if any issues/problems arise from submissions to eConnect,  via eConnect_EntryPoint or eConnect_Requester methods, then these errors are surfaced as eConnect exceptions. The .Message property of this class contains the error text.

The econnectException class returns the message from the eConnect stored procedure that originated the problem. A table of these messages is held in SQL server, DYNAMICS database, table taErrorCode. This table gives an idea of the error conditions you may not have thought possible and lets you be a bit more proactive at handling errors.

To see the contents of this table see this file:

Item does not allow back orders

Lets choose an example problem that you may experience. When submitting a SOP sales order document, normally you want any items that are out of stock to be back ordered. This is easy, set the QtyShrtOpt = 4 in the XML to back order the balance. However if you have a situation where you have a telesales team hammering in orders as well as a website taking orders, even with SQL replication you can occasionally get a scenario where a web order comes in for an item that has been set to disallow web orders and it no longer has enough stock to satisfy the web order. This may be due to latency in updating stock on the website for example. eConnect lets us know with the following exception: “Microsoft.GreatPlains.eConnect.eConnectException: Error Number = 4776”

Gracefully dealing with it

There a few ways I can think of to deal with this, the chosen one is to change the QtyShrtOpt = 6 for the line in question inorder to cancel the qty that can not be allocated from stock. It is wise to then set an order note to let the sales staff who will process the order know about the issue so it can be resolved with the customer, perhaps alternative item offered.

.NET code

A regular expression is used to parse the eConnect exception text. This allows easy detection of what error has occurred and extracts the item number for the order line raising the exception.

Having a list of item numbers with this issue allows us to change the XML of the document being submitted to alter the quantity shortage option flag to cancel the balance (option 6). Promoting LINQ for XML work, load the XML document into a XDocument (LINQ XML Document) class.

Now use a LINQ query to get all the elements that need the backorder option changing and change it to 6.

Now the altered XML document is resubmitted to Dynamics GP via eConnnect. If it fails this time there is an issue that we have not programmed for so it needs administrative intervention.

To load the xDocument back into the XMLDocument class for submission to eConnect,

Note on security

Beware exposing your ERP system to your website – if the website gets compromised, then so is your business. eConnect allows most of your business data to be altered and queried - this is something to be very careful of. With the implementation I created, the XML document is punched through the firewalls to a custom web service on the GP segment of the network. This web service only lets through the specific eConnect documents we want to allow through and only those that meet specific criteria to limit the attack potential.

Summary

By adding to this example, common errors your eConnect integration encounters could be eliminated so IT staff are prevented from spending time supporting disruptive day to day integration issues. Thus these problem cases are handed back to the process owner, be that; buyers, warehouse, or sales staff.