Referencing The API

Declaring and Initializing the PayTrace API

Once the PayTrace API is declared in your code, request strings may be sent to the PayTrace Payment Gateway, and response may be retrieved and parsed in your code.

The following code example illustrates how the PayTrace API may be referenced in you software’s code. All examples are provided in Visual Basic (VB) Script 5.0

Dim strRequest, strResponse ‘declare variables that are used in various code samples in this document

Function SendPayTraceAPIRequest(ByVal p_Request As String) As String
Dim objPost,  l_Response

‘Create the HTTPS object
set objPost =createobject("MSXML2.XMLHTTP") 
‘newer versions of MSXML are available and supported

‘open the HTTPS object and point it to the PayTrace secure servers
objPost.Open "POST", "",  false

‘set the Request Header of the HTTPS object to a URL encoded form
objPost.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"

‘URLEncode is defined in section 3.2a
l_Request = “PARMLIST=” & URLEncode(p_Request)

‘send the request and save the response
objPost.Send l_Request
l_Response = objPost.ResponseText
Set objPost = Nothing

        SendPayTraceAPIRequest = l_Response
End Function

Formatting a PayTrace API Request String

The PayTrace API accepts requests strings that formatted in name / value pairs that are separated with tildes (~) and delimited with pipes (|). For example, the string “name1~value1|name2~value2|” is correctly formatted to be sent through the PayTrace API. However, the PayTrace API only accepts specific names and each value must meet the expected criteria found in section 3.3 PayTrace API Name / Value Pairs Data Definitions.

Please note that the portion of the request following the “parmList=” designation should be URL encoded. Many programming languages have built in URLEncode functions such as Server.URLEncode() in ASP and URLEncode() in PHP.

The code samples provided in this document are written in VB Script which does not include a URL encoding function by default. Here is an example of a URL encoding function that’s referenced in the code samples later in this document.

Function URLEncode(ByVal p_Request As String) As String
    Dim Counter As Integer
    Dim ASCIICode As Integer

    For Counter = Len(p_Request) To 1 Step -1
        ASCIICode = Asc(Mid(p_Request, Counter, 1))
        Select Case ASCIICode
            Case 48 To 57, 65 To 90, 97 To 122
                ' don't touch alphanumeric chars and already handled spaces
            Case 32
                ' replace space with "+"
                p_Request = Left(p_Request, Counter - 1) & "+" & Mid(p_Request, Counter + 1)
            Case Else
                ' replace punctuation chars with "%hex"
                p_Request = Left(p_Request, Counter - 1) & "%" & Hex$(ASCIICode) & _
Mid(p_Request, Counter + 1)
        End Select

    URLEncode = p_Request
End Function