Enrich a transaction descriptor

Returns a merchant identity for a raw bank descriptor.

At least one identifier is required — an Idempotency-Key header, an external_transaction_id, or both. Without one, the deduplication branch is skipped entirely and two identical calls would produce two billed events that nothing can tell apart. The API refuses rather than let that happen.

Request

application/jsonCreateRequest

Response

Settled. A 200 does not mean a merchant was found — read enrichment.status. not_found is a normal, complete answer.

application/jsonEnrichment

Possible errors

Code
Status	Code	Title
`400`	`identifier_required`	Identifier required An economic identifier is required to resolve this transaction.
`400`	`invalid_idempotency_key`	Invalid Idempotency-Key The Idempotency-Key header is missing or malformed.
`400`	`invalid_json`	Invalid JSON body The request body is not valid JSON.
`400`	`invalid_request`	Invalid request The request does not match the documented shape.
`400`	`unsupported_canonicalization`	Unsupported canonicalization The requested canonicalization version is not supported.
`401`	`invalid_api_key`	Invalid API credential The API credential is missing, malformed, revoked, or unknown.
`402`	`no_active_subscription`	No active subscription No active subscription covers this operation.
`402`	`sandbox_quota_exhausted`	Sandbox quota exhausted The organization has used its Sandbox allowance. Move to Production to continue.
`403`	`account_inactive`	Account inactive The organization or the workspace is not active.
`403`	`insufficient_scope`	Insufficient scope The credential does not carry the scope this operation requires.
`403`	`production_not_enabled`	Production access not enabled This credential is not allowed to call the production environment.
`409`	`idempotency_key_reuse`	Idempotency key reused This idempotency key was already used with a different request.
`409`	`input_mismatch`	Input mismatch The submitted input does not match the input stored for this identifier.
`409`	`refresh_not_available`	Refresh not available This enrichment cannot be refreshed.
`409`	`transaction_id_conflict`	Transaction identifier conflict This transaction identifier was already used with a different request.
`410`	`result_content_expired`	Result content expired The result content was purged and is no longer available.
`413`	`request_entity_too_large`	Request entity too large The request body exceeds the documented size limit.
`415`	`unsupported_media_type`	Unsupported media type The request body must be sent as application/json.
`429`	`rate_limited`	Rate limited Too many requests. Retry after the delay given by Retry-After.
`500`	`internal_error`	Internal error An unexpected error occurred. Quote the request_id when contacting support.
`503`	`busy`	Service busy The service is temporarily contended. Retry after the delay given by Retry-After.
`503`	`engine_error`	Engine error The enrichment engine failed to produce a result. This attempt is not billable.
`503`	`pricing_not_activated`	Pricing not activated Billing is not activated for this operation yet. Retry later.

All errors

POST/merchant/v1/enrichments

Serverhttps://api.noryo.app

Sandbox and Production share the API surface; the credential decides which.

IDEMPOTENCY_KEY=$(uuidgen)
curl -sS -X POST 'https://api.noryo.app/merchant/v1/enrichments' \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "descriptor": "CB MCDONALDS PARIS 4519",
  "external_transaction_id": "tx_8f21c0"
}'

Shell

Authorization

Header: Authorization
Type: http
Scheme: bearer

Authorization: Bearer nry_mer_sbx_<key_id>.<secret>

The prefix carries the environment: nry_mer_sbx_ for Sandbox, nry_mer_live_ for Production. The secret is shown once, at creation, and is never recoverable. There is no rotation operation: to replace a key, create a new one, deploy it, then revoke the old one.

Response samples

Schema structure

{
  "enrichment_id": "enr_7f3c1e20-…",
  "merchant": {
    "name": "McDonald's",
    "category": "alimentation.restaurant",
    "logo_url": "<string · uri>",
    "location": {
      "city": "PARIS",
      "postal_code": "75018"
    },
    "confidence": "<number · 0–1>"
  },
  "enrichment": {
    "status": "<string>",
    "reason": "<string>",
    "environment": "<string>",
    "source": "<string>",
    "customized": "<boolean>",
    "rules": [
      {
        "id": "<string · uuid>",
        "version": "<integer ≥ 1>"
      }
    ]
  },
  "usage": {
    "billable": "<boolean>",
    "units": "<integer>",
    "deduplicated": "<boolean>",
    "deduplicated_by": "<string>"
  }
}

JSON

Was this page helpful?