Gerege хөгжүүлэгч

Gerege App-аар төлөх — ямар ч систем (вэб дэлгүүр, мобайл апп, касс, kiosk, вендинг машин, нэхэмжлэх) хүнээс Gerege App-аар төлбөр авах нээлттэй API. Хүн QR уншуулж, sticker-т утсаа хүргэж эсвэл холбоос нээгээд, дүнг Gerege App-ын өөрийн цонхонд харж Face ID-аар төлнө; мөнгө Gerege Wallet данснаас таны данс руу орно. Мөн mini app — Gerege App дотор нээгддэг таны вэб апп.

Сервер тал: modules/miniapp 1.9.0 (2026-10-27). API: https://geregeapp.mn/api/v1/miniapp.

Хамгийн богино жишээ

curl https://geregeapp.mn/api/v1/miniapp/payment-intents \
  -u "$GEREGE_CLIENT_ID:$GEREGE_CLIENT_SECRET" -H 'Idempotency-Key: order-1001' -H 'Content-Type: application/json' \
  -d '{"amount": 3500, "description": "Захиалга №1001", "presentment": "qr"}'
# → {"id": "pi_…", "status": "requires_confirmation", …, "pay_url": "https://geregeapp.mn/pay/…"}

pay_url-ийг QR болгоно → хүн төлнө → payment_intent.succeeded webhook. Алхам алхмаар: 15 минутад анхны test төлбөр.

Төлөх дөрвөн арга

	Хэнд	Хүн яаж төлөх
redirect	вэб дэлгүүр, мобайл апп	checkout-оос pay_url руу → утсанд Gerege App нээгдэнэ → таны return_url руу буцна
qr	касс, kiosk, POS, нэхэмжлэх	дэлгэц/цаасан дээрх QR-ийг Gerege App-аар уншуулна
terminal	вендинг машин, байнгын sticker, NFC tag	машины sticker-ийг уншуулна / NFC-д утсаа хүргэнэ — дүн нь тэр мөчийн сагснаас
app	Gerege App доторх mini app	апп дотор bridge-ээр төлөх цонх

Аль нь танд: Урсгалаа сонгох. Ялгаа ба claim: Төлбөрийн урсгалууд ба claim.

Эндээс эхэл

• Туршиж үзэх хөгжүүлэгч

  ---

  Test түлхүүрээр 15 минутад эхний төлбөр, мөнгө хөдлөхгүй.

  Quickstart

• Вэб дэлгүүр, апп

  ---

  Checkout-д «Gerege App-аар төлөх»: redirect, return_url, webhook, буцаалт.

  Gerege App-аар төлөх

• Вендинг, sticker, NFC

  ---

  Терминал бүртгэж, сагс уяж, гарсан бол capture — гараагүй бол cancel.

  Терминалаар test төлбөр

• Олон эзэмшигчтэй платформ

  ---

  Эзэмшигч бүр дэд худалдагч: өөрийн payout данс, өөрийн тооцоо.

  Худалдагч, дэд худалдагч, терминал

• Kiosk, касс, POS

  ---

  Сагс бүрт шинэ QR, payment_intent.claimed → «утсаараа баталгаажуул».

  Quickstart

• Mini app хөгжүүлэгч

  ---

  Gerege App дотор апп: manifest, нээлт → token, bridge, төлбөр.

  Mini app

Ойлголт

Ойлголтын тойм	Бүх объект нэг зурагт; худалдагч ба mini app; нэр томьёо
Төлбөрийн амьдралын мөчлөг	Төлөв бүр, webhook, барьцаа ба capture, хугацаанууд
Test ба live	Хоёр орчин, тест дүн, review ба live болох
Мөнгөний урсгал	Payout данс, тооцоо, шимтгэл, бодит банк руу гаргах
Аюулгүй байдлын загвар	Secret хаана, URL дүнгүй, төлөх цонхонд бүртгэлийн нэрс
Хүний мэдээлэл · Давталт · Хувилбар

Лавлах: Webhook · Алдааны код · Хөгжүүлэгчийн sandbox.

Хэрэгжилтийн төлөв

«удахгүй» = стандарт эсвэл төлөвлөгөөнд байгаа ч энэ платформ дээр одоогоор хэрэгжээгүй.

Хэсэг	Төлөв
Gerege App-аар төлөх API: kind: "merchant", claimless intent (qr, redirect, terminal), терминал, дэд худалдагч, эзэмшигчийн баталдаг payout холболт, payment_intent.claimed / .expired	✓
Gerege App (iOS): апп доторх QR товч, NFC уншигч → claim → төлөх цонх; payout холболт батлах; мөнгө гаргах	✓ (TestFlight 121-ээс хойшх build)
Камераар уншуулах (/pay Universal Link), компьютер дээрх /pay хуудас, App Clip	«удахгүй» — хүний алхмыг API-аар тоглуулж болно (Quickstart)
Mini app: registry, manifest шалгалт, review, нээлт, consent (profile.email, profile.phone), token, /me, requires_verified / min_age	✓
Payment intent (automatic, manual capture, capture_within), цуцлах, буцаалт, test горим, апп-ын max_amount	✓
Webhook: орчин бүрт ≤ 5 endpoint (event шүүлтүүр, тус бүр secret, автомат унтраалт), гарын үсэг, retry, secret солих 24 цаг давхцалтай, шууд хүргэлт, хүргэлтийн лог, дахин илгээх, webhook.test; events API (GET /events, 30 хоног)	✓ (API; консолын дэлгэц цөмд)
Нэртэй, scope-той, IP allowlist-тэй API түлхүүр (gk_… / gks_…), preset, солих (roll), хүчингүй болгох	✓ test түлхүүр; live-ийг шинэ API-аар (дахин нэвтрэлттэй) — «удахгүй», одоо анхдагч хосоор
Тест хэрэглэгч, консолын тест төлбөр, статистик, launcher-ийн layout	✓
Тооцоо (операторын шимтгэл, хуваарь, fee / net, settlement.paid), (апп, дэд худалдагч)-ын тооцоо	✓ (оператор апп бүрт асаана)
Gerege Wallet: байгууллагын данс, бодит банк руу мөнгө гаргах хүсэлт	✓
Консолын «Худалдагч» бүртгэл, утасгүй симуляц, самбарын төлбөр/тайлан	«удахгүй»
Хувь хүний sandbox байгууллага; гэрээнд eID гарын үсэг; бизнесийн профайл (KYB), go-live checklist, хязгаар	«удахгүй»
Sticker-ийн PDF хэвлэх хуудас, терминалын batch	«удахгүй»
Дүнтэй хэсэгчилсэн capture; урт хугацаатай нэхэмжлэх (expires_in > 1800 с)	«удахгүй»
Android host, вэб host; npm дээрх SDK	«удахгүй»

Стандарт ба SDK

Mini app хэсэг нь openpay-ийн OMAS 1.0 (OpenPay Mini App Standard)-ын Gerege хэрэгжилт: ижил manifest, нээлт → token, bridge, гарын үсэг; ялгаа нь нэр (gerege), зам (/api/v1/miniapp), credential-ийн угтвар (gma_…). Энэ баримтад ЗААВАЛ (MUST), ХОРИГЛОНО (MUST NOT), ЗӨВЛӨЖ БАЙНА (SHOULD), БОЛНО (MAY) нь RFC 2119-ийн утгаар.

Server SDK: @gerege/miniapp-node (TypeScript) ба Go (sdk/go: webhook шалгалт, худалдагчийн төлбөрийн client miniapp.NewClient; mini app-ын token-д golang.org/x/oauth2) — хараахан нийтэд гараагүй; SDK-гүйгээр бичихэд энэ баримт хангалттай. Frontend-д host window.gerege-ийг өөрөө inject хийнэ (Bridge).