Overview

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 is generated.

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

Three routes, no batch

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

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.
• 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.
• confidence is a score, not a probability. Noryo has measured that its ordering is not monotonic at the top of the range. See Confidence.
• The key carries the environment: nry_mer_sbx_ for Sandbox, nry_mer_live_ for Production, on the same URL. See Environments.
• The raw descriptor is not retained, and the content of a result is kept for 90 days. See Retention and 410.
• Every error is an RFC 9457 Problem Details object whose code field is the only machine contract. See Errors and the error catalogue.

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.

Where to start

1. Quickstart: one enrichment, its replay, its read-back and its refresh, with real responses.
2. Core concepts: the API's vocabulary on one page.
3. Authentication and API keys: getting and presenting a key.
4. Requests: headers, idempotency, formats and validation.
5. Enrichments: create, read, refresh, statuses and lifecycle.
6. Operations: rate limits, retries, timeouts, errors and request IDs.