Skip to content

Versioning and compatibility

How the API changes, what your integration MUST tolerate, and what never changes without notice.

1. Rules

  • The major is in the path: /api/v1/miniapp, and bridge_version in the bridge (now 1). A breaking change = a new major (/v2) — the old one keeps running beside it.
  • Minors only add: new fields, event types, states, error codes, bridge methods, routes. Existing fields are never renamed, retyped, re-meant or removed.
  • The server's version is the module's (now modules/miniapp 1.9.0) — with mn/en notes in the history (chronicle) of «Mini апп-ууд» in the App Store.

2. Your integration MUST

  • Ignore unknown fields — do not parse JSON with a strict schema (additionalProperties: false).
  • Answer 2xx to unknown event types (accept and do nothing) — a 5xx brings them back until the retry schedule ends.
  • Treat an unknown status / failure_code as «not final, unknown» and read again with GET.
  • Handle an unknown error code by its HTTP status (4xx do not retry, 5xx retry).
  • Treat object ids (pi_…, evt_…) as opaque strings — do not rely on their length or structure.

3. OMAS compatibility

Gerege mini apps implement OMAS 1.0 (openpay's mini app standard) — a backend written for OMAS works by changing its values only:

  • the manifest is also read as openpay-miniapp.json;
  • webhooks also carry the OpenPay-Signature and OpenPay-Event-Id headers;
  • the token endpoint also takes grant_type=launch_code and a JSON body;
  • an app intent that expires sends payment_intent.canceled + status: "expired" (the new payment_intent.expired goes to claimless intents only).

4. Deprecation

Anything to be removed is announced at least 6 months ahead, with Deprecation and Sunset headers (RFC 8594) in its answers — «удахгүй» (nothing is deprecated today). The current example: the default mapp_… / gma_cs_… pair (every scope) keeps working now that scoped gk_… keys have shipped; a date to stop it will be announced separately.

5. Change history

Every version's changes (mn/en) — Changelog (generated from the same source as the history of «Mini апп-ууд» in the App Store).