Core concepts
The vocabulary of Noryo Merchant API on one page: descriptor, enrichment, economic identity, identifiers, statuses, units and environments.
This page defines the terms used throughout the documentation. Field and value names stay exactly as the API returns them.
The descriptor and the enrichment
| Term | Definition |
|---|---|
descriptor | The raw bank label, as it appears on the statement (CB MCDONALDS PARIS 4519). It is the only required field of a request. Noryo does not retain it. |
| Enrichment | The result of a call that was settled: a merchant identity (or the absence of one), a status, and what the call cost. |
enrichment_id | The public identity of a result, shaped enr_<uuid>. A refresh produces a new result, hence a new enrichment_id; the old one keeps pointing at the old result. |
merchant | The merchant identity: name, category, logo_url, location, confidence. It is null when the status is not_found. |
What identifies a transaction
| Term | Definition |
|---|---|
| Economic identity | The six fields descriptor, amount, currency, occurred_at, country and mcc, compared in a canonical form. Two calls that differ only by amount are two distinct enrichments. |
external_transaction_id | Your identifier for the transaction. It carries economic deduplication: the same transaction sent twice is billed once. It does not expire. |
Idempotency-Key | A request header that protects the transport: a network retry replays the memorised response instead of recomputing. 24-hour window. |
The two identifiers do not replace each other. See The two identifiers.
What the response says
| Term | Definition |
|---|---|
enrichment.status | resolved, partial, not_found or refresh_recalculated. Read it first, before merchant. See Statuses. |
enrichment.reason | A public reason from a closed list for partial and not_found, null otherwise. |
confidence | A model confidence score between 0 and 1. It is not a calibrated probability. See Confidence. |
usage | What this call cost: billable, units, deduplicated, deduplicated_by. |
| Unit | The unit in which usage is counted. A resolved or refresh_recalculated result is 1 unit; partial and not_found are 0. |
Who calls, and where
| Term | Definition |
|---|---|
| Organisation and workspace | An organisation groups workspaces; an API key belongs to a workspace. Results, idempotency keys and deduplication are scoped to a workspace and an environment. The Sandbox allowance is counted per organisation. |
| Environment | sandbox or production. The key prefix carries it and the server confirms it; the response repeats it in enrichment.environment. |
| Scopes | enrich:read allows reading (GET), enrich:write allows creating and refreshing. |
Noryo-Request-Id | The identifier of one HTTP attempt, shaped req_<uuid>. It is in the header of every response and in the body of every error. |
code | The machine code of a Problem Details error, for example idempotency_key_reuse. It is the only part of an error to build logic on. |
What Noryo does with your input
All six economic fields enter the economic identity, but only descriptor currently drives resolution. In particular, country does not filter the answer: this is a measured choice, explained in Reading the response.
To decide whether two requests carry the same transaction, Noryo compares a canonical form rather than the bytes you sent: descriptor is normalised (Unicode NFC, lower case, collapsed whitespace), occurred_at is reduced to the second in UTC, while currency, country and mcc are compared verbatim. That is why currency and country must be upper case. See Formats.
Published on 2026-10-08 21:04 UTC (version 1).