For developers
An open registry for any bank, wallet, fintech or app: one JSON file describes every company, with its logos on a CDN. Free, with no key and no sign-up. Run by Neptune, and not reserved for its own apps.
Quick start
- Index
https://logos-cdn.neptune.ly/v1/index.json- Logo
https://logos-cdn.neptune.ly/v1/logo/{logo}-{96|256}.webp- Schema
- JSON Schema for the index
curl -s https://logos-cdn.neptune.ly/v1/index.json
const base = 'https://logos-cdn.neptune.ly/v1/';
const idx = await (await fetch(base + 'index.json')).json();
const m = idx.merchants.find((m) => m.id === 'amazon');
const logo = base + idx.logoPath
.replace('{logo}', m.logo).replace('{size}', 96);
Index format
Each company has a stable id, names (Arabic first), aliases (alternative names and card-statement forms such as AMZN Mktp), tags, category, accounts as bank:15-digit, merchantIds as network:id, and logo, the image fingerprint. The full definition is in the schema.
Caching and updates
- Fetch the index at most once a day, with
If-None-Match; you get304when nothing changed. The CDN keeps it for minutes and revalidates. - Logo files are named by the fingerprint of their content, so they never change (
immutable); cache them forever. - The index and the logos send
Access-Control-Allow-Origin: *, so they work from any site or app. - A withdrawn company disappears from the next index; delete what you cached for it when you update.
Matching a transaction to a company
- The account first. A Libyan IBAN, or an account number with its bank code. An account match settles it.
- Then the name, normalised. Lower case; the hamza forms, yaa and taa marbuta fold into one letter each; P=B and V=F; words such as “company”, Ltd and the Arabic article are dropped.
- Typos are weighed. An extra, missing or swapped vowel (Libyna, Libiana, برستو) is forgiven from 5 letters; changing a consonant makes another word (Almadar / Almadak), so it is forgiven only in long names.
- A fuzzy match must explain the whole name. It counts only when it covers 80% of the name’s letters, leaving out the city or country: “BARDEM AL MADAK” is another shop.
- The kind of place must agree. A name that says “café”, “pharmacy” or “hotel” never takes the logo of a company in another line of business.
- In doubt, no logo. When two merchants are equally close, neither is shown. A wrong logo is worse than none.
The full matching specification, which our own apps follow, with the shared test cases.
Stability and versions
- Within
schema: 1changes are additive only: new optional fields or new categories may appear, and no existing field changes meaning. Ignore what you do not know. - Any breaking change ships as
schema: 2under/v2/, and/v1/keeps working. - Published logo URLs never change, and a company’s
idis never reused.
Terms of use
- Free for any commercial or non-commercial use, with no key.
- Logos are their owners’ trademarks. Show them only to identify the company in a transaction or a list, never in an advert or in a way that suggests partnership or endorsement.
- We withdraw any logo its owner asks us to, so refresh your copy daily.
- Crediting the source (“Logos from the Neptune registry”) is appreciated, not required.
- The service is provided as is, without warranty. Do not use it unlawfully or to impersonate a company.
Identify your app
Send a User-Agent header that names your app with every request, as the OpenStreetMap and Wikimedia policies ask:
User-Agent: YourApp/1.0 (com.your.app; dev@your.app)
It tells us who relies on the registry, so we can write to them before any change. We count daily totals per app and country only, with no IP addresses and no data about people. A request without it works as usual.
Privacy
Match on the user’s device. Never send their statement or transactions to any server, ours included: the whole index is with you, and we have no need to know what anyone buys.
Contact and status
Integration questions, a mistake about a company, or a takedown request: logos@neptune.ly.
Index last published: 2026-11-18 20:02 UTC. The index’s version field holds the same value; use it to tell whether your copy is current.