Ойлголтын тойм¶

Бүх объект нэг зурагт: хэн юуг эзэмших, юу юутай холбогдох. Нарийн дүрмийг тус бүрийн хуудаснаас уншина.

1. Эзэмшлийн мод¶

Байгууллага (workspace — eID-ээр нээсэн хуулийн этгээд, гишүүд, role)
└─ «Mini апп-ууд» суусан (mn.gerege.miniapp)
   └─ Апп ─ kind: "miniapp" | "merchant"     slug, нэр, icon — бүртгэл, review
      ├─ API түлхүүр      нэртэй, орчинтой (test/live), scope-той client id/secret (Basic)
      ├─ Webhook endpoint орчин бүрт ≤ 5, тус бүр өөрийн secret → event бүр гарын үсэгтэй
      ├─ Тест хэрэглэгч   байгууллагын идэвхтэй гишүүд (≤ 50)
      ├─ Терминал         sticker / NFC / машин (code, url, label, location)       ┐ merchant
      ├─ Дэд худалдагч     олон эзэмшигчийн нэг (code, нэр, payout холболт)        ┘
      ├─ Payment intent   нэг төлбөр: дүн, төлөв, presentment, барьцаа
      │  └─ Refund        буцаалт (бүтэн / хэсэгчлэн, 90 хоног)
      ├─ Payout данс      мөнгө орох Gerege Wallet данс (оператор тохируулна)
      └─ Settlement       тооцоо: клирингээс payout руу, шимтгэл хасаад (оператор асаана)

Хүн (Gerege App, eID) ── claim / confirm ──▶ Payment intent      (Gerege Wallet данснаас барьцаа)
Оператор (Гэрэгэ пэй) ── review, payout, шимтгэлийн дүрэм, мөнгө гаргалт

2. Худалдагч ба mini app¶

Хоёулаа нэг registry-ийн апп — ижил credential, webhook, review, тооцоо, аналитиктай. Ялгаа нь хүн хаанаас төлөх.

	`kind: "miniapp"`	`kind: "merchant"`
Юу	Gerege App дотор нээгддэг таны вэб апп	Gerege App-аас гадуурх таны систем (вэб, апп, касс, машин)
Launcher-т	гарна (батлагдсан бол)	хэзээ ч гарахгүй
Manifest, entry URL, origin	заавал	байхгүй (`409 merchant_no_manifest`)
Intent үүсгэх	хүний access token (`Bearer`, `payments` scope)	апп-ын client credential (`Basic`)
`presentment`	`app`	`qr`, `redirect`, `terminal`
Хүнийг юугаар таних	апп-д тогтмол pairwise `sub` (хүн зөвшөөрөл өгсөн)	төлбөр бүрт санамсаргүй `user_ref` (зөвшөөрөл өгөөгүй)
Review юу шалгах	manifest, icon, хуулийн хуудас, UX	хуулийн хуудас, webhook, live secret, бизнес

Хоёр зам хэзээ ч холилдохгүй: хүний token-оор claimless intent, client credential-аар app intent үүсгэх боломжгүй (400 presentment_required / validation_error).

mini app:   Хүн ─▶ Gerege App ─launch─▶ таны frontend ─▶ таны backend ─token─▶ Gerege API
                       ▲ bridge requestPayment                       │ intent (Bearer)
                       └──────── төлөх цонх, Face ID ◀───────────────┘
merchant:   Таны backend ─intent (Basic)─▶ Gerege API ─▶ pay_url / терминалын url
            Хүн ─уншуулна─▶ Gerege App ─claim, confirm─▶ Gerege API ─webhook─▶ таны backend

3. Гурван хил¶

Нууц нь серверт. Client secret, access token, webhook secret зөвхөн таны backend-д. Frontend, мобайл апп, терминал, машин тэдгээрийг хэзээ ч барихгүй, Gerege API-г шууд дуудахгүй.
Мөнгийг зөвхөн хүн хөдөлгөнө. Та төлбөр хүснэ (intent); дүнг хүн Gerege App-ын өөрийн цонхонд харж, дансаа сонгож, Face ID-аар батална. Таны URL, QR, sticker дүн агуулахгүй.
Таних нь бүртгэлээс. Төлөх цонхонд хэн авч байгааг (апп-ын батлагдсан нэр, терминалын нэр/байршил, дэд худалдагчийн нэр) бүртгэлээс харуулна — таны бичсэн текстээс биш.

Дэлгэрэнгүй: Аюулгүй байдлын загвар.

4. Нэр томьёо¶

Нэр	Утга
Host	Gerege App — iOS (`WKWebView`). Хүний нэвтрэлт, зөвшөөрөл, төлбөрийн баталгаажуулалтыг эзэмшинэ. Android ба вэб host — «удахгүй»
Апп	Registry дэх таны бүртгэл (`miniapp` эсвэл `merchant`)
Payment intent (`pi_…`)	Нэг төлбөрийн хүсэлт ба түүний төлөв (Амьдралын мөчлөг)
Presentment	Хүн intent-д яаж хүрэх: `app`, `redirect`, `qr`, `terminal` (Урсгалууд)
Claim	Хүн claimless intent-ийг Gerege App-д өөртөө авах (Урсгалууд)
Барьцаа (hold)	Хүний дансанд түгжсэн мөнгө — capture хийвэл авна, cancel/хугацаа дуусвал буцна
Терминал	Байнгын цэг (sticker, NFC, машин) — Худалдагч, дэд худалдагч, терминал
Дэд худалдагч	Олон эзэмшигчтэй платформын нэг эзэмшигч — өөрийн payout, тооцоо
Payout данс	Таны орлого орох Gerege Wallet данс (Мөнгөний урсгал)
Settlement (`st_…`)	Клирингээс payout руу тооцоо, шимтгэл хасаад
`user_ref` / `sub`	Хүний нэрээ нууцалсан id (`u_` + 32 hex) — Хүний мэдээлэл
Оператор	Платформын эзэн «Гэрэгэ пэй» — review, payout данс, шимтгэлийн дүрэм, мөнгө гаргалт
Test / live	Хоёр орчин; credential-ийн орчин intent-ийн `livemode`-ыг шийднэ (Test ба live)

5. Credential-ийн угтвар¶

Угтвар	Юу	Хаана
`gk_live_…` · `gk_test_…`	API түлхүүрийн client id — нууц биш	`Basic`-ийн хэрэглэгчийн нэр, лог
`gks_live_…` · `gks_test_…`	API түлхүүрийн secret (checksum-тай) — нууц	зөвхөн таны сервер
`mapp_…` · `mapp_test_…` · `gma_cs_…`	апп-ын анхдагч (legacy) client id · secret — бүх scope	manifest-ийн `client_id`; хуучин интеграци
`whsec_…`	webhook secret — нууц	гарын үсэг шалгах
`gml_…`	launch code (60 с, нэг удаа)	mini app-ын нээлт
`gma_at_…` · `gma_rt_…`	хүний access (30 мин) · refresh token	mini app-ын backend
`pi_…` · `re_…` · `evt_…` · `st_…` · `we_…`	intent · refund · event · settlement · webhook endpoint id	лог, тусламж

gks_(live|test)_[A-Za-z0-9_-]{43}_[0-9A-Za-z]{6} хэлбэр танигдахуйц — repo, лог-д secret scanning-ээр хайж болно.