Concepts overview¶

Every object in one picture: who owns what, and what connects to what. The detailed rules are on each object's page.

1. The ownership tree¶

Organisation (workspace — a legal entity opened with eID, its members, roles)
└─ «Mini апп-ууд» installed (mn.gerege.miniapp)
   └─ App ─ kind: "miniapp" | "merchant"     slug, name, icon — registry, review
      ├─ API keys         named, per environment (test/live), scoped client id/secret (Basic)
      ├─ Webhook endpoint ≤ 5 per environment, each with its own secret → every event signed
      ├─ Test users       active members of the organisation (≤ 50)
      ├─ Terminal         sticker / NFC / machine (code, url, label, location)    ┐ merchant
      ├─ Sub-merchant     one of many owners (code, name, payout link)           ┘
      ├─ Payment intent   one payment: amount, state, presentment, hold
      │  └─ Refund        full / partial, within 90 days
      ├─ Payout account   the Gerege Wallet account money goes to (set by the operator)
      └─ Settlement       from clearing to payout, less the fee (switched on by the operator)

Person (Gerege App, eID) ── claim / confirm ──▶ Payment intent      (a hold on their Gerege Wallet account)
Operator (Gerege Pay)    ── review, payout, fee rules, withdrawals

2. Merchants and mini apps¶

Both are an app in one registry — the same credentials, webhooks, review, settlements and analytics. What differs is where the person pays.

	`kind: "miniapp"`	`kind: "merchant"`
What	your web app opened inside Gerege App	your system outside Gerege App (web, app, till, machine)
In the launcher	yes (once approved)	never
Manifest, entry URL, origins	required	none (`409 merchant_no_manifest`)
Creates intents with	the person's access token (`Bearer`, `payments` scope)	the app's client credentials (`Basic`)
`presentment`	`app`	`qr`, `redirect`, `terminal`
Knows the person as	a pairwise `sub`, stable per app (the person consented)	a random `user_ref` per payment (no consent given)
Review checks	manifest, icon, legal pages, UX	legal pages, webhook, live secret, the business

The two paths never cross: a person's token cannot make a claimless intent and client credentials cannot make an app intent (400 presentment_required / validation_error).

mini app:   Person ─▶ Gerege App ─launch─▶ your frontend ─▶ your backend ─token─▶ Gerege API
                       ▲ bridge requestPayment                       │ intent (Bearer)
                       └──────── payment sheet, Face ID ◀────────────┘
merchant:   Your backend ─intent (Basic)─▶ Gerege API ─▶ pay_url / the terminal's url
            Person ─scans─▶ Gerege App ─claim, confirm─▶ Gerege API ─webhook─▶ your backend

3. Three boundaries¶

Secrets stay on the server. Client secrets, access tokens and webhook secrets live in your backend only. A frontend, a mobile app, a terminal or a machine never holds them and never calls the Gerege API directly.
Only the person moves money. You ask for a payment (an intent); the person sees the amount in Gerege App's own sheet, picks the account and confirms with Face ID. Your URLs, QRs and stickers carry no amount.
Names come from the registry. The payment sheet shows who is charging (the app's approved name, the terminal's label and location, the sub-merchant's name) from the registry — not from text you wrote.

More: Security model.

4. Terms¶

Term	Meaning
Host	Gerege App — iOS (`WKWebView`). Owns the person's sign-in, consent and payment confirmation. Android and web hosts are «удахгүй»
App	your entry in the registry (`miniapp` or `merchant`)
Payment intent (`pi_…`)	one request for payment and its state (Payment lifecycle)
Presentment	how the person reaches the intent: `app`, `redirect`, `qr`, `terminal` (Presentments)
Claim	the person taking a claimless intent as theirs in Gerege App (Presentments)
Hold	money locked on the person's account — captured, or released on cancel / expiry
Terminal	a fixed spot (sticker, NFC, machine) — Merchants, sub-merchants, terminals
Sub-merchant	one owner on a multi-owner platform — their own payout and settlement
Payout account	the Gerege Wallet account your takings go to (Money flow)
Settlement (`st_…`)	from clearing to payout, less the fee
`user_ref` / `sub`	the person's pseudonymous id (`u_` + 32 hex) — Personal data
Operator	the platform's owner, Gerege Pay — review, payout accounts, fee rules, withdrawals
Test / live	two environments; the credential's environment sets the intent's `livemode` (Test and live)

5. Credential prefixes¶

Prefix	What	Where
`gk_live_…` · `gk_test_…`	an API key's client id — not secret	the user name in `Basic`, logs
`gks_live_…` · `gks_test_…`	an API key's secret (with a checksum) — secret	your server only
`mapp_…` · `mapp_test_…` · `gma_cs_…`	the app's default (legacy) client id · secret — every scope	the manifest's `client_id`; older integrations
`whsec_…`	webhook secret — secret	verifying signatures
`gml_…`	launch code (60 s, single use)	a mini app's launch
`gma_at_…` · `gma_rt_…`	the person's access (30 min) · refresh token	a mini app's backend
`pi_…` · `re_…` · `evt_…` · `st_…` · `we_…`	intent · refund · event · settlement · webhook endpoint id	logs, support

The gks_(live|test)_[A-Za-z0-9_-]{43}_[0-9A-Za-z]{6} shape is recognisable — secret scanning can find it in repositories and logs.