Parsers

Description:
Merchant matching endpoints support the use of parsers as a way to identify attributes within the transaction string, such as merchant name, city, state, and country. The parser guides the processor to specific attributes in the string and reassembles the data values into a cleaner string for improved match accuracy. While parsers can be beneficial when using the v2 endpoint, they are not required nor necessary because of enhanced AI matching capabilities available in the V2 endpoint.

When to Use:
The parsers are effective for strings that are fixed-width. If the string is not fixed-width format, omit the parser parameter in the request. NOTE: Parser type can be changed per request.

How to Use:
Parser Name: VISA
Endpoint: /v2/partners/{{partner_id}}/merchants/cleanse-transaction/?parser=VISA
Predefined Parser Instructions:

Max Length of Fixed Width String for VISA2 parser is 40 characters.

Sample Transaction:

"S H E L L   O I L                                          C  H  I  C  A  G  O                    I  L  U  S"
 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

Input Sample:

{
    "merchantDescription": "SHELL OIL               CHICAGO     ILUS",
    "mcc": "5541"
}

Output Sample:

{
    "matchType": "SIMILAR",
    "matchScore": 0.96,
    "network": "VISA",
    "transId": "df0304a5-ebfd-4ffa-8bf3-9572b830bd41",
    "transType": "debit",
    "ucic": "e2c96790-fd69-11e8-9ff7-bf083b0e566c",
    "uaic": "123456",
    "matchDetail": {
        "cleansed": "SHELL OIL CHICAGO",
        "merchant": {
        "classification": "SHELL",
        "logoUrl": "",
        "location": {
            "city": "CHICAGO",
            "state": "IL",
            "zip": "",
            "country": "US"
        }
        },
        "category1": {
        "classification": "GAS STATIONS",
        "logoUrl": ""
        },
        "category2": {
        "classification": "TRANSPORTATION & AUTOMOTIVE",
        "logoUrl": "https://merchantlogos.net/vehicle.svg"
        },
        "mcc": {
        "classification": "SERVICE STATIONS (WITH OR WITHOUT ANCILLARY SERVICES)",
        "logoUrl": "https://merchantlogos.net/fuel.svg"
        }
    }
}                                

Parser Name: VISA2
Endpoint: /v2/partners/{{partner_id}}/merchants/cleanse-transaction/?parser=VISA2
Predefined Parser Instructions:

Max Length of Fixed Width String for VISA2 parser is 43 characters

Sample Transaction:

 WENDY'S       DENVER                   COUS
 0123456789012345678901234567890123456789012

Input Sample:

{
    "merchantDescription": "WENDY'S                  DENVER        COUS",
    "mcc": "5812"
}

Output Sample:

{
    "matchType": "DIRECT",
    "matchScore": 1,
    "network": "VISA2",
    "transId": "103045c8-a67f-4557-ac71-ff331a7c9618",
    "transType": "debit",
    "matchDetail": {
        "cleansed": "WENDYS DENVER",
        "merchant": {
        "classification": "WENDY'S",
        "logoUrl": "https://merchantlogos.net/wendys.com.png",
        "location": {
            "city": "DENVER",
            "state": "CO",
            "zip": "",
            "country": "US"
        }
        },
        "category1": {
        "classification": "FAST FOOD RESTAURANTS",
        "logoUrl": ""
        },
        "category2": {
        "classification": "FOOD AND DINING",
        "logoUrl": "https://merchantlogos.net/dinner.svg"
        },
        "mcc": {
        "classification": "EATING PLACES AND RESTAURANTS",
        "logoUrl": "https://merchantlogos.net/dining-room-cutlery-set-of-three-pieces-in-siloutte.svg"
        }
    }
}                              

Parser Name: custom

Endpoint: /v2/partners/{{partner_id}}/merchants/cleanse-transaction/?parser=custom
Parser Definition: The property parserDefinition of the post body is required when using the parser=custom query string parameter.

"parserDefinition": {
    "maxLength": 44,
    "fields": [
        {
            "name": "merchant",
            "start": 0,
            "length": 26
        },
        {
            "name": "city",
            "start": 27,
            "length": 13
        },
        {
            "name": "state",
            "start": 40,
            "length": 2
        },
        {
            "name": "country",
            "start": 42,
            "length": 2
        }
    ]
}

Sample Transaction:

"M C D O N A L D ' S    R  E  S  T  A  U  R  A  N  T                    C  L  E  V  E  L  A  N  D              I  L  U  S"
 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

Input Sample:

{
    "merchantDescription": "MCDONALD'S RESTAURANT      CLEVELAND    OHUS",
    "parserDefinition": {
        "maxLength": 44,
        "fields": [
            {
                "name": "merchant",
                "start": 0,
                "length": 26
            },
            {
                "name": "city",
                "start": 27,
                "length": 13
            },
            {
                "name": "state",
                "start": 40,
                "length": 2
            },
            {
                "name": "country",
                "start": 42,
                "length": 2
            }
        ]
    }
}

Output Sample:

{
    "matchType": "DIRECT",
    "matchScore": 1,
    "network": "custom",
    "transId": "c482137b-cb53-4efd-8773-35bc7d3b9239",
    "transType": "debit",
    "ucic": "e2c96790-fd69-11e8-9ff7-bf083b0e566c",
    "uaic": "123456",
    "matchDetail": {
        "cleansed": "MCDONALDS RESTAURANT",
        "merchant": {
        "classification": "MCDONALD'S",
        "logoUrl": "https://merchantlogos.net/mcdonalds.com.png",
        "location": {
            "city": "CLEVELAND",
            "state": "OH",
            "zip": "",
            "country": "US"
        }
        },
        "category1": {
        "classification": "FAST FOOD RESTAURANTS",
        "logoUrl": ""
        },
        "category2": {
        "classification": "FOOD AND DINING",
        "logoUrl": "https://merchantlogos.net/dinner.svg"
        }
    }
}