Before a transaction may be processed through the PayTrace API Secure Checkout page, a corresponding order must be created and validated. All validation requests will need to be directed to paytrace.com/api/validate.pay .
Validating an Order
Required Name Value Pairs
UN, PSWD, AMOUNT, TRANXTYPE, ORDERID, TERMS
Please note that TRANXTYPE may also be set to “CreateCustomer” or “UpdateCustomer” to provide an interface to manage customers with out first processing a transaction. ORDERID will be stored as the CUSTID unless an email address is provided without the HIDEPASSWORD~Y parameter and value in the redirect call - in which case the email address will be used.
Also, TRANXTYPE may be set to SALECUSTOMER to both process a sale and create a stored customer profile.
Please note that some check processors, such as GETI, do not support Authorization, Refund, Forced Sale,and Void requests.
Optional Name Value Pairs That Can Be Included In An Order Validation
- RETURNURL, Optional URL that can allow for a dynamic URL to be used for the silent post response from PayTrace. If not provided, PayTrace will use the silent post URL stored within the Manage API Checkout page.
- APPROVEURL, Optional URL that the customer will have the option of selecting if their transaction is approved via the PayTrace API Secure Checkout
- DECLINEURL, Optional URL that the customer will have the option of selecting if their transaction is declined via the PayTrace API Secure Checkout
- FORCEEMAIL, Setting in the PayTrace API Secure Checkout that may be set to ‘Y’ if the customer’s email address is required.
- FORCEADDRESS, Setting in the PayTrace API Secure Checkout that may be set to ‘Y’ if the customer’s billing address is required.
- FORCECSC, Setting in the PayTrace API Secure Checkout that may be set to ‘Y’ if the customer’s CSC security code is required.
Sample Order Validation Request
Dim strRequest, strResponse ‘declare variables that are used in various code samples in this document Function SendPayTraceSecureCheckoutRequest(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", "https://paytrace.com/api/validate.pay", 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 SendPayTraceSecureCheckoutRequest = l_Response End Function 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 Next URLEncode = p_Request End Function ‘format the request string to email a receipt for transaction ID 1498 to firstname.lastname@example.org strRequest = “UN~demo123|PSWD~demo123|TERMS~Y|TRANXTYPE~Sale|” strRequest = strRequest & “ORDERID~1234|” strResponse = SendPayTraceAPIRequest(strRequest) ‘defined in Referencing the API Page
Example of Parsing an Order Validation Response
‘declare tools to loop through the response and store the current name / value pair Dim arrResponse() as String Dim arrPair() as String Dim Counter as Integer ‘declare the tools to store the values of the appropriate responses Dim strError As String Dim strOrderID As String Dim strAuthkey As String ‘check to make sure the response was not empty/invalid if strResponse <> “” and inStr(strResponse,”|”) > 0 and inStr(strResponse,”~”) > 0 then arrResponse = split(strResponse, “|”) ‘split the response into an array of name/value pairs for Counter = 0 to uBound(arrResponse)-1 arrPair = split(arrResponse(Counter), “~”) If UCase(arrPair(0)) = "ERROR" Then StrError = strError & arrPair(1) ElseIf UCase(arrPair(0)) = "ORDERID" Then strOrderID = arrPair(1) ElseIf UCase(arrPair(0)) = " AUTHKEY" Then strAuthkey = arrPair(1) End If next Else StrError = StrError & “The response from the PayTrace API was invalid." End if If StrError <> “” then MsgBox “OrderID was not successful per the following error: ” & StrError Else MsgBox “OrderID transaction was successful: ” & strAuthkey End if