Merchant matcher specification (schema 1)
One algorithm, implemented once per client. Every implementation must pass every case in fixtures.json. Reference implementation: neptune-mobile/lib/core/merchant_logos/merchant_matcher.dart.
Rule zero: a wrong logo is worse than none. Every ambiguity returns no match.
Input
name (counterparty or merchant name as the bank sent it), account (any digits), iban, descriptor (a card statement's merchant field, ISO 8583 DE43 style: name, city, country), text (the row's free description). Any of them may be absent. Order: account, name, descriptor, text. Clients pass text except for transfers and salaries, where the description is a person's purpose, not a merchant.
Signals, strongest first
| Signal | Fires when | Score |
|---|---|---|
account | the account/IBAN equals exactly one registered account | 1 |
exact | the whole normalised name equals one merchant name or alias | 1 |
token | a run of consecutive name tokens, joined, equals an alias of 5+ characters | 1 |
fuzzy | a run of tokens is within the typo budget of an alias of 5+ characters | 1 - typos / length |
text | a run of description tokens equals an alias of 5+ characters, or is one typo from an alias of 7+ | as above |
Order: account, then name, then text. text exists for voucher purchases: the statement row of a voucher names only its product, inside a fixed Arabic sentence, and carries no provider id. It is never fuzzy and never matches an acronym; two merchants in one description give no match.
Accounts
- Libyan IBAN:
LY+ 2 check digits + 3 bank + 3 branch + 15 account (25 characters). Spaces, dashes and case are ignored. Check digits are not verified for matching. - Account key: digits only (Eastern digits converted), 8 to 15 digits, left-padded with zeros to 15. So a 14-digit account and its 15-digit IBAN form (filler
0after the branch code) give the same key. - Index accounts are
BBB:AAAAAAAAAAAAAAA(bank code, 15-digit account), or a bare account. - With an IBAN, match on bank + account. Without one, match on the account alone, and only if exactly one merchant holds it.
Names
Normalise, then split into tokens:
ؤسسة company co ltd limited llc est inc corp plc sarl jsc the and
- Eastern digits to Western; remove harakat (U+064B to U+0652), superscript alef (U+0670) and tatweel (U+0640).
- Lower-case Latin; fold Latin accents;
أ إ آ ٱtoا,ىtoي,ةtoه,ؤtoو,ئtoي; Persian shapesک ی ھ ڤ پ چtoك ي ه ف ب ج; Latinptobandvtof(Arabic has neither, so Libyan Latin spelling swaps them: Bresto is Presto). - Anything that is not a letter or digit becomes a space.
- In words of 5+ letters collapse doubled letters (Prestto); shorter words keep them (LTT).
- Strip one Arabic prefix
وال بال فال كال لل الwhen 3+ letters remain.
Latin al/el stay as tokens: joining tokens makes Al-Madar, AL MADAR and ALMADAR equal.
Windows: every run of 1 to 5 consecutive tokens, joined without spaces.
قاولات» is not the airline Oya).
exact: all tokens joined equal an alias (3+ characters).
- A merchant whose window hit lies strictly inside another merchant's longer window hit is dropped:
GOOGLE *YouTubeis YouTube (aliasGoogle YouTube), not Google. fuzzy: weighted optimal-string-alignment distance in half-typos. Adding, dropping or swapping a vowel (a e i o u y ا و ي ى ه) costs 1: that is how a name's spelling drifts (Libyna, Libiana, برستو, ليبيانه). Any edit touching a consonant, and a neighbour swap, costs 2: that makes another word (Almadar is not Almadak). Budget by alias length: 0 under 5 letters, 1 (one vowel slip) from 5, 2 from 8, 4 from 12, 6 from 16. A window that is only a prefix of the alias, or the alias of it, is another word ("Libyan" is not "Libyana") and needs 0. Truncation: a window that ends the name, is 8+ characters, is 70%+ of the alias length and is a prefix of it scores at least 0.9.- Coverage: a
fuzzyor truncated window, and an any-order match that needed a typo, must hold at least 80% of the name's letters, not counting where the terminal stands (libya ly tripoli benghazi misrata zawia sabhaand their Arabic). "BARDEM AL MADAK" leaves BARDEM unexplained and gets no logo. text(a description) forgives one vowel slip on aliases of 7+ letters, never a consonant, only in Arabic-script windows (a Latin narrative is dictionary words: "delivery" is not Deliveroo), and never applies the truncation rule or the coverage rule (it is a sentence).- Any order: every word (3+ letters) of a multi-word alias present in the name, in any order, each within its typo budget (exact in
text), scores 0.95 (token/text). Words held by more than 50 aliases are not used to find candidates. - Candidates come from a letter-pair index (an edit destroys at most two pairs); pairs held by more than 400 aliases are skipped.
Choosing
Service marks yield: merchants of category payments (banks, wallets, rails, card schemes) carry a payment for someone else. When any other merchant also scored, they are dropped before ranking ("LYPAY Transfer . Libyana" is Libyana, "PAYPAL *NETFLIX" is Netflix). In a descriptor whose match is a service mark (or nothing) and that has a *, the part after the first * is matched as a descriptor too, and a non-service result wins ("TABBY*NOON" is noon).
Best score per merchant. If the top two merchants are within 0.02 of each other, no match.
Kind of place must agree (names and descriptors, not text): when the name announces a kind of place (pharmacy, hospital, restaurant, café, bakery, fuel, hotel, groceries, shopping, travel, transport, education, shipping, by the same word lists clients use for generic icons) the chosen merchant's category must allow it; otherwise no match. "AL MADAR CAFE" holds the telecom's alias and is a café. Allowed kinds per category: telecom {shopping}; ecommerce {shopping, groceries, shipping}; airline {travel, hotel, transport}; supermarket {groceries, shopping, bakery}; fuel {fuel, shopping, café, restaurant, groceries}; pharmacy {pharmacy, hospital}; restaurant {restaurant, café, bakery}; education {education}; shipping {shipping}; vouchers, fashion {shopping}; transport {transport, travel}; utilities, payments, government, entertainment, software {}; other or missing: any.
Evidence order, strongest first: account or IBAN, merchant ID, the whole name equal to an alias, an alias window, then typo-tolerant windows. Only the last needs coverage; every one but the account and the whole name must pass the kind check. Tags are labels for people (portal search, review); they never select a logo.
Budgets
Under 2 ms per row on a low-end Android; the reference runs ~80 µs per row against 2,000 merchants on the development Mac. Results are cached per (name, account, iban).