API Adding Level 3 Data To A Visa Sale

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

Request Response

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