Level 3 data is additional information that may be applied to enrich a transaction’s reporting value to both the merchant and the customers. Generally, merchant service providers offer reduced or qualified pricing for transactions that are processed with Level 3 data.
Level 3 data may be added to any Visa or MasterCard sale that is approved and pending settlement. Some level 3 data, specifically enhanced data such as Invoice and Customer Reference ID, may overlap with data provided with the base transaction. Enhanced data, when applied, will always overwrite such data that may already be stored with the transaction.
Level 3 data consists of enhanced data and 1 or more line item records. This information is intended to describe the details of the transaction and the products or services rendered. However, defaults may be applied in the event that some data is missing or unknown. So, all required fields must be present, even if their values are empty. Empty values will be overwritten with PayTrace defaults.
Please note that Visa and MasterCard each have their own requirements for level 3 data, so your application should be able to determine if the transaction being updated in a Visa or a MasterCard before formatting and sending the request. All Visa account numbers begin with “4” and contain 16 digits. All MasterCard account numbers begin with “5” and also contain 16 digits.
Level 3 records contain sub name/value pairs that are delimited w/ URL sensitive characters ( = and + ). Requests following the "parmList=" characters must be URL encoded to save accurately.
Add Level 3 Data to Visa Request
Required Name Value Pairs
UN, PSWD, TERMS, METHOD, TRANXID
Optional Name Value Pairs For Add Level 3 Data to Visa Request
INVOICE, CUSTREF, TAX, NTAX, MERCHANTTAXID, CUSTOMERTAXID, CCODE, DISCOUNT, FREIGHT, DUTY, SOURCEZIP, SZIP, SCOUNTRY, ADDTAX, ADDTAXRATE
Optional Name Value Pairs For Line Item Detail to Visa Request
CCODELI, PRODUCTID, DESCRIPTION, QUANTITY, MEASURE, UNITCOST, ADDTAXLI, ADDTAXRATELI, DISCOUNTLI, AMOUNTLI
- Please note that each name/value pair is separated by the traditional ~ and followed by a |. However, name/value pairs included in the LINEITEM parameter are separated by the = symbol and followed by a + symbol. So, no values in a Level3Visa request should contain a ~, |, +, or = symbols. The example request below contains 1 Line Item record.
Sample Add Level 3 Data to Visa Request
‘format the request string to add level 3 data to a Visa transaction strRequest = “UN~demo123|PSWD~demo123|TERMS~Y|METHOD~Level3Visa|” strRequest = strRequest & “TRANXID~1234|INVOICE~12345|CUSTREF~1234|TAX~-1|NTAX~0|” strRequest = strRequest & “MERCHANTTAXID~123456789|CUSTOMERTAXID~987654321|” strRequest = strRequest & “SOURCEZIP~97201|SZIP~99201|SCOUNTRY~US|” strRequest = strRequest & “CCODE~1234|DISCOUNT~0|FREIGHT~0|DUTY~0|ADDTAX~0|” strRequest = strRequest & “ADDTAXRATE~0|LINEITEM~CCODELI=12345678+” strRequest = strRequest & “PRODUCTID=TESTPRODUCT+DESCRIPTION=TEST DESCRIPTION+” strRequest = strRequest & “QUANTITY=1+MEASURE=LBS+UNITCOST=1+ADDTAXLI=0+” strRequest = strRequest & “ADDTAXRATELI=0+DISCOUNTLI=0+AMOUNTLI=1+|” strResponse = SendPayTraceAPIRequest(strRequest) ‘defined in Referencing the API Page
Returned Name Value Pairs
Each request to add level 3 data sent to the PayTrace API should elicit a response. However, your application should validate the response to ensure it is not empty. Your application will also need to parse the response to determine if errors occurred. Your application will certainly also need to display any errors or successful responses to the user.
Responses elicited from a Level3VISA request will always return either one or more error messages or a response.
Example of Parsing an Add Level 3 Data to Visa Transaction 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 strResponseMessage 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)) = "RESPONSE" Then strResponseMessage = arrPair(1) End If next Else StrError = StrError & “The response from the PayTrace API was invalid." End if If StrError <> “” then MsgBox “Level 3 request was not successful per the following error: ” & StrError Else MsgBox “Level 3 request was successful: ” & strResponseMessage End if