# Overview

> What Noryo Merchant API does, its three routes, the rules to know before writing any code, and where to start.

Noryo Merchant API turns a raw bank descriptor (the `descriptor`, as the bank prints it on a statement) into a merchant identity: a name, a category, a logo and a location when they are known, and a confidence score. The API answers in JSON over HTTPS. Its machine contract is an OpenAPI 3.1 document, from which the [API reference](https://developer.noryo.app/en-GB/merchant/reference) is generated.

This documentation describes what the server actually does. A capability that does not exist is not described.

## Three routes, no batch

```http
POST /merchant/v1/enrichments
GET  /merchant/v1/enrichments/{enrichment_id}
POST /merchant/v1/enrichments/{enrichment_id}/refresh
```

| Route | What it does | What it costs |
|---|---|---|
| `POST /merchant/v1/enrichments` | Enriches a descriptor and returns a result identified by an `enrichment_id` | 1 unit if the result is `resolved`, nothing otherwise |
| `GET /merchant/v1/enrichments/{enrichment_id}` | Reads a past result back | Never billed |
| `POST /merchant/v1/enrichments/{enrichment_id}/refresh` | Recomputes the identity and returns a **new** `enrichment_id` | 1 unit if the result is `refresh_recalculated`, nothing otherwise |

One request carries one transaction. There is no batch route.

## Rules to know before writing any code

- **A `200` does not mean a merchant was found.** Read `enrichment.status`: `not_found` is a normal, complete answer. See [Reading the response](https://developer.noryo.app/en-GB/merchant/reading-the-response).
- **A create call needs at least one identifier**: the `Idempotency-Key` header, the `external_transaction_id` field, or both. With neither, the API refuses with `400 identifier_required`. See [The two identifiers](https://developer.noryo.app/en-GB/merchant/identifiers).
- **`confidence` is a score, not a probability.** Noryo has measured that its ordering is not monotonic at the top of the range. See [Confidence](https://developer.noryo.app/en-GB/merchant/results/confidence).
- **The key carries the environment**: `nry_mer_sbx_` for Sandbox, `nry_mer_live_` for Production, on the same URL. See [Environments](https://developer.noryo.app/en-GB/merchant/authentication/environments).
- **The raw descriptor is not retained**, and the content of a result is kept for 90 days. See [Retention and 410](https://developer.noryo.app/en-GB/merchant/retention).
- **Every error is an RFC 9457 Problem Details object** whose `code` field is the only machine contract. See [Errors](https://developer.noryo.app/en-GB/merchant/error-handling) and the [error catalogue](https://developer.noryo.app/en-GB/errors).

## Version and host

The version belongs to the family: `/merchant/v1`. A future `merchant/v2` would live beside `v1` rather than replace it.

The host is not part of the contract. Noryo may serve the API from more than one domain, and no hostname enters any identity, hash or signature. The contract currently declares `https://api.noryo.app`: put that value in your base URL configuration rather than in your code. See [Versioning and governance](https://developer.noryo.app/en-GB/merchant/governance).

## Where to start

1. [Quickstart](https://developer.noryo.app/en-GB/merchant/quickstart): one enrichment, its replay, its read-back and its refresh, with real responses.
2. [Core concepts](https://developer.noryo.app/en-GB/merchant/concepts): the API's vocabulary on one page.
3. [Authentication](https://developer.noryo.app/en-GB/merchant/authentication) and [API keys](https://developer.noryo.app/en-GB/merchant/authentication/api-keys): getting and presenting a key.
4. [Requests](https://developer.noryo.app/en-GB/merchant/requests): headers, idempotency, formats and validation.
5. [Enrichments](https://developer.noryo.app/en-GB/merchant/enrichments): create, read, refresh, statuses and lifecycle.
6. [Operations](https://developer.noryo.app/en-GB/merchant/operations): rate limits, retries, timeouts, errors and request IDs.

> **Note** Sandbox is free and carries a lifetime allowance of 2,000 units per organisation. Production is not self-service: it opens after Noryo has reviewed an application. See [Sandbox](https://developer.noryo.app/en-GB/merchant/sandbox) and [Going live](https://developer.noryo.app/en-GB/merchant/going-live).

---

Canonical page: https://developer.noryo.app/en-GB/merchant