Models

Noryo Merchant API exchanges few objects, all described in the OpenAPI contract and in the API reference. This section presents them from the integrator's point of view: what each field guarantees, when it is present, and when it is null.

The map of objects

Enrichment
├── enrichment_id
├── merchant ─────── Merchant | null
│                    ├── name, category, logo_url, confidence
│                    └── location ── { city, postal_code } | null
├── enrichment ───── status, reason, environment, source, customized
└── usage ────────── billable, units, deduplicated, deduplicated_by

How the identifiers relate

Four identifiers circulate, each at its own scale:

How they relate:

• A transaction has one or more enrichments: the first one, then one per refresh. One of them is its current result. See Lifecycle.
• An Idempotency-Key designates a single request for 24 hours, hence at most one enrichment.
• A request can give several attempts: each retry has its own Noryo-Request-Id, even when it returns the memorised response.
• An enrichment without external_transaction_id belongs to no transaction: it is not deduplicated and cannot be refreshed.

Presence rules

• merchant is always present: an object, or null when the status is not_found.
• merchant.location is always present when merchant is an object: an object, or null.
• merchant.category and merchant.logo_url are omitted when unknown.
• enrichment.reason is always present: a reason, or null.
• usage.deduplicated_by is always present: external_transaction_id, or null.

Write a client that ignores response fields it does not know, and that accepts an optional field being absent.