Объектууд¶

Энэ хуудсаар: API-ийн хариу ба webhook-ийн data.object-д ирэх объект бүрийн талбар, төрөл, утгыг шалгана. Лавлах — кодоо бичихдээ хажууд нь нээж хэрэглэнэ.

Payment intent нь өөрийн хуудастай: Payment intent. Энд бусад нь.

Нийтлэг дүрэм (API-ийн нийтлэг дүрэм):

Мөнгө — бүхэл ₮ (integer), валют үргэлж MNT.
Цаг — RFC 3339, UTC (2026-10-22T09:00:00Z).
«null болно» гэсэн талбар хариунд үргэлж байна, утга нь null байж болно; бусад нь хэзээ ч null биш.
Шинэ талбар minor хувилбарт нэмэгдэж болно — мэдэхгүй талбарыг үл тоомсорлоорой.

Refund¶

POST /payment-intents/{id}/refunds-ийн хариу, refund.succeeded / refund.failed-ийн data.object. Тайлбар: Буцаалт.

Талбар	Төрөл	null	Утга
`id`	string		`re_` + 24 base62
`object`	string		`"refund"`
`intent_id`	string		буцаасан intent (`pi_…`)
`amount`	integer		буцаасан дүн, ₮
`status`	string		`pending` · `succeeded` · `failed`
`reason`	string		таны өгсөн шалтгаан (≤ 255), эсвэл `""`. Хүний мэдэгдэлд хэзээ ч гарахгүй
`failure_code`	string	тийм	`failed` үед: `insufficient_funds` · `settlement_shortfall` · `refund_rejected` (Алдааны код)
`livemode`	boolean		live эсэх
`created_at`	string (цаг)

{
  "id": "re_2kLm9Pq4Rs6Tu8Vw0Xy1Za3B",
  "object": "refund",
  "intent_id": "pi_4fQ2mX8kLp0aZr7TbN3cVw9E",
  "amount": 10000,
  "status": "succeeded",
  "reason": "supplier_failed",
  "failure_code": null,
  "livemode": true,
  "created_at": "2026-10-22T09:00:00Z"
}

Settlement¶

GET /settlements (items[]), GET /settlements/{id}, settlement.paid-ийн data.object. Зөвхөн live. Тайлбар: Тооцоо.

Талбар	Төрөл	null	Утга
`id`	string		`st_` + 24 base62
`object`	string		`"settlement"`
`status`	string		`pending` · `paid` · `failed`
`cutoff`	string (цаг)		энэ мөчөөс өмнө capture хийгдсэн төлбөрүүд орсон
`gross`	integer		төлбөрүүдийн нийлбэр
`refunds`	integer		суутгасан буцаалтын нийлбэр
`reserve_refunds` · `holdback` · `released`	integer		үргэлж `0` (энэ платформд нөөц/holdback байхгүй; OMAS-ын нийцлийн талбар)
`fee`	integer		энэ тооцоо бодитоор авсан шимтгэл; буцаасан нь авснаас их бол сөрөг
`net`	integer		`gross − refunds − fee`
`recovered`	integer		өмнөх тооцооноос илүү гарсан буцаалтын суутгал (`clearing_carried_in − clearing_carried_out`; сөрөг = дараагийнх руу шилжсэн)
`paid`	integer		payout данс руу шилжсэн дүн (`0` байж болно)
`intent_count` · `refund_count`	integer		орсон төлбөр, буцаалтын тоо
`destination_masked`	string	тийм	payout данс, сүүлийн 4 оронтой (`******0042`)
`holdback_release_at`	string (цаг)	тийм	үргэлж `null`
`livemode`	boolean		`true`
`created_at`	string (цаг)
`paid_at`	string (цаг)	тийм	`paid` болсон мөч
`fee_assessed`	integer		төлбөрүүдэд бодогдсон шимтгэл
`fee_returned`	integer		буцаалтаар буцсан шимтгэл (дүрэм `refund_fee`-тэй бол)
`fee_carried_in` · `fee_carried_out`	integer		өмнөхөөс ирсэн / дараагийнх руу шилжсэн шимтгэл
`clearing_carried_in` · `clearing_carried_out`	integer		өмнөхөөс ирсэн / дараагийнх руу шилжсэн буцаалтын илүүдэл
`failure_code`	string	тийм	`failed` үед (Алдааны код)
`sub_merchant`	string (UUID)	тийм	дэд худалдагчийн тооцоо бол түүний id; апп-ын өөрийнх бол `null`

Тэнцэтгэл: net = gross − refunds − fee, paid = net − holdback + released − reserve_refunds − recovered.

{
  "id": "st_7QwErTy2UiOp4AsDf6GhJk8L",
  "object": "settlement",
  "status": "paid",
  "cutoff": "2026-10-21T16:00:00Z",
  "gross": 100000,
  "refunds": 5000,
  "reserve_refunds": 0,
  "fee": 2000,
  "net": 93000,
  "holdback": 0,
  "released": 0,
  "recovered": 0,
  "paid": 93000,
  "intent_count": 3,
  "destination_masked": "******0042",
  "holdback_release_at": null,
  "livemode": true,
  "created_at": "2026-10-22T08:58:00Z",
  "paid_at": "2026-10-22T08:59:00Z",
  "refund_count": 1,
  "fee_assessed": 2000,
  "fee_returned": 0,
  "fee_carried_in": 0,
  "fee_carried_out": 0,
  "clearing_carried_in": 0,
  "clearing_carried_out": 0,
  "failure_code": null,
  "sub_merchant": null
}

GET /settlements/{id} нь дээрх талбарууд дээр intents[] (id, amount, fee, reference (null болно), confirmed_at (null болно)), refund_items[] (id, intent_id, amount, fee_returned, source) ба truncated-ийг нэмнэ — мөр 1000-аас олон бол truncated: true, эхний 1000 нь л ирнэ.

{
  "id": "st_7QwErTy2UiOp4AsDf6GhJk8L",
  "object": "settlement",
  "status": "paid",
  "…": "…",
  "intents": [
    { "id": "pi_4fQ2mX8kLp0aZr7TbN3cVw9E", "amount": 65000, "fee": 1300, "reference": "order_8812", "confirmed_at": "2026-10-21T03:12:00Z" }
  ],
  "refund_items": [
    { "id": "re_2kLm9Pq4Rs6Tu8Vw0Xy1Za3B", "intent_id": "pi_4fQ2mX8kLp0aZr7TbN3cVw9E", "amount": 5000, "fee_returned": 0, "source": "clearing" }
  ],
  "truncated": false
}

Terminal¶

/terminals…-ийн хариу (жагсаалт нь {"data": [Terminal]}). Тайлбар: Gerege App-аар төлөх.

Талбар	Төрөл	null	Утга
`id`	string (UUID)		intent-ийн `terminal_id`
`object`	string		`"terminal"`
`code`	string		серверийн олгосон 10 тэмдэгт (`23456789abcdefghjkmnpqrstuvwxyz`), хэзээ ч өөрчлөгдөхгүй
`url`	string		sticker-ийн QR ба NFC tag-д бичих хаяг: `https://geregeapp.mn/pay/t/<code>` — дүн агуулахгүй
`label`	string		1–60, төлөх цонхонд Face ID-аас өмнө харагдана
`location`	string		≤ 120, эсвэл `""`
`reference`	string	тийм	таны дугаар (`^[A-Za-z0-9_.:-]{1,64}$`), апп дотор давтагдахгүй
`sub_merchant`	string (UUID)	тийм	терминалын дэд худалдагч
`status`	string		`active` · `disabled`
`created_at` · `updated_at`	string (цаг)

{
  "id": "4b8e6c1a-2d3f-4a5b-9c7d-0e1f2a3b4c5d",
  "object": "terminal",
  "code": "7k2m9x4q3p",
  "url": "https://geregeapp.mn/pay/t/7k2m9x4q3p",
  "label": "Машин №7",
  "location": "СБД, 1-р хороо",
  "reference": "vm-7",
  "sub_merchant": "9a7c5e3b-1d2f-4e6a-8b0c-7d9e1f3a5b7c",
  "status": "active",
  "created_at": "2026-10-22T08:00:00Z",
  "updated_at": "2026-10-22T08:00:00Z"
}

SubMerchant¶

/sub-merchants…-ийн хариу (жагсаалт нь {"data": [SubMerchant]}).

Талбар	Төрөл	null	Утга
`id`	string (UUID)		intent-ийн `sub_merchant_id`
`object`	string		`"sub_merchant"`
`code`	string		таны платформ дахь id (`^[A-Za-z0-9_.:-]{1,40}$`), өөрчлөгдөхгүй
`display_name`	string		1–80, төлж буй хүнд харагдана
`legal_name`	string		≤ 160, эсвэл `""`
`reg_no`	string		≤ 20, эсвэл `""`
`status`	string		`active` · `disabled`
`payouts_configured`	boolean		эзэмшигч payout дансаа баталсан эсэх — `false` бол live төлбөр `payouts_not_configured`
`payout_account`	string	тийм	батлагдсан данс, сүүлийн 4 оронтой (`******3456`)
`payout_linked_at`	string (цаг)	тийм	баталсан мөч
`created_at` · `updated_at`	string (цаг)

{
  "id": "9a7c5e3b-1d2f-4e6a-8b0c-7d9e1f3a5b7c",
  "object": "sub_merchant",
  "code": "owner-17",
  "display_name": "Батаа ХХК",
  "legal_name": "Батаа ХХК",
  "reg_no": "6543210",
  "status": "active",
  "payouts_configured": true,
  "payout_account": "******3456",
  "payout_linked_at": "2026-10-22T08:30:00Z",
  "created_at": "2026-10-22T08:00:00Z",
  "updated_at": "2026-10-22T08:30:00Z"
}

PayoutLink¶

POST /sub-merchants/{sid}/payout-link-ийн хариу, GET …/payout-links ({"data": [PayoutLink]}, шинэ нь эхэнд, ≤ 50). Тайлбар: Payout данс.

Талбар	Төрөл	null	Утга
`id`	string (UUID)
`object`	string		`"payout_link"`
`sub_merchant`	string (UUID)
`status`	string		`pending` · `approved` · `declined` · `canceled` (шинэ хүсэлт орлосон) · `superseded` (дараагийн батлагдсан холболт орлосон) · `expired` (хариугүй 7 хоног өнгөрсөн)
`account_masked`	string		хүссэн данс, сүүлийн 4 оронтой
`requested_at`	string (цаг)
`expires_at`	string (цаг)		`requested_at` + 7 хоног
`decided_at`	string (цаг)	тийм	баталсан / татгалзсан мөч
`terms`	object		`{"mn", "en"}` — эзэмшигч батлахдаа юуг зөвшөөрч байгаа (доор)

terms (хоёр хэл, үргэлж ижил): «Энэ данс руу орсон төлбөрүүдийн буцаалтыг (төлбөрөөс хойш 90 хоногийн дотор) энэ данснаас хасна.» / «Refunds of payments made into this account (within 90 days of each payment) are taken back from this account.»

{
  "id": "5d1f0a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
  "object": "payout_link",
  "sub_merchant": "9a7c5e3b-1d2f-4e6a-8b0c-7d9e1f3a5b7c",
  "status": "pending",
  "account_masked": "****************2345",
  "requested_at": "2026-10-22T08:10:00Z",
  "expires_at": "2026-10-29T08:10:00Z",
  "decided_at": null,
  "terms": {
    "mn": "Энэ данс руу орсон төлбөрүүдийн буцаалтыг (төлбөрөөс хойш 90 хоногийн дотор) энэ данснаас хасна.",
    "en": "Refunds of payments made into this account (within 90 days of each payment) are taken back from this account."
  }
}

Event¶

Webhook бүрийн body, мөн GET /events · GET /events/{id}-ийн хариу — яг ижил byte (гарын үсэг зурсан хадгалсан body). data.object-ийн төрөл нь type-аас хамаарна — Event-ийн лавлах, Events API.

Талбар	Төрөл	Утга
`id`	string	`evt_` + 24 base62 — давхардлыг үүгээр арилга (`Gerege-Event-Id` толгойтой ижил)
`type`	string	`payment_intent.succeeded` г.м.
`created_at`	string (цаг)	event үүссэн мөч, секунд хүртэл
`livemode`	boolean
`app`	string	апп-ын slug
`data.object`	object	PaymentIntent, Refund, Settlement, AppStatus, Consent эсвэл WebhookTest

{
  "id": "evt_Vec0000000000000000000003",
  "type": "refund.succeeded",
  "created_at": "2026-10-22T09:00:00Z",
  "livemode": true,
  "app": "esim",
  "data": { "object": { "id": "re_2kLm9Pq4Rs6Tu8Vw0Xy1Za3B", "object": "refund", "…": "…" } }
}

AppStatus¶

app.status_changed-ийн data.object: апп-ын status эсвэл review_status өөрчлөгдсөн.

Талбар	Төрөл	null	Утга
`object`	string		`"app"`
`slug`	string
`status` · `previous_status`	string		`draft` · `active` · `maintenance` · `disabled`
`review_status` · `previous_review_status`	string		`draft` · `in_review` · `approved` · `rejected` · `suspended`
`review_note`	string	тийм	татгалзсан, түдгэлзүүлсэн үеийн операторын тэмдэглэл

{
  "object": "app",
  "slug": "esim",
  "status": "active",
  "review_status": "suspended",
  "previous_status": "active",
  "previous_review_status": "approved",
  "review_note": "Хэрэглэгчийн гомдол шалгагдаж байна"
}

consent.revoked-ийн data.object: хүн апп-аа салгасан, тэр хүний бүх token аль хэдийн хүчингүй.

Талбар	Төрөл	Утга
`object`	string	`"consent"`
`user_ref`	string	тухайн хүний pairwise нэр (`sub` / `ref`)
`revoked_at`	string (цаг)

{ "object": "consent", "revoked_at": "2026-10-22T09:00:00Z", "user_ref": "u_78a08c3afb344c1b4b765aead45e1693" }

WebhookTest¶

webhook.test-ийн data.object (консолын тест илгээлт, livemode үргэлж false).

Талбар	Төрөл	null	Утга
`object`	string		`"webhook_test"`
`message`	string		`"Gerege App webhook test"`

{ "message": "Gerege App webhook test", "object": "webhook_test" }

Нийтийн /pay харагдац¶

GET /api/v1/miniapp/pay/{token} ба GET /api/v1/miniapp/pay/t/{code} — нэвтрэлтгүй, компьютер дээрх /pay/… хуудас уншдаг. Хувийн мэдээлэл байхгүй: тайлбар, reference, metadata, хэн claim хийсэн — алга.

Талбар (`payment`)	Төрөл	null	Утга
`object`	string		`"payment"`
`merchant`	object		`{name, icon_url}` — апп-ын батлагдсан нэр, дүрс
`terminal`	object	тийм	`{code, label, location}`
`amount` · `currency`	integer · string
`status`	string		intent-ийн төлөв
`claimed`	boolean		хэн нэгэн claim хийсэн эсэх («утсаараа баталгаажуулна уу»)
`expires_at`	string (цаг)
`livemode`	boolean

{
  "object": "payment",
  "merchant": { "name": "Vending.mn", "icon_url": "https://vending.mn/icon-512.png" },
  "terminal": { "code": "7k2m9x4q3p", "label": "Машин №7", "location": "СБД, 1-р хороо" },
  "amount": 3500,
  "currency": "MNT",
  "status": "requires_confirmation",
  "claimed": false,
  "expires_at": "2026-10-22T09:05:00Z",
  "livemode": true
}

/pay/t/{code} нь {"object": "terminal", "merchant", "terminal", "pending"} — pending нь терминалын claim хийгдээгүй нээлттэй live intent (дээрх payment объект) эсвэл null. Танигдаагүй, идэвхгүй терминал эсвэл түдгэлзсэн худалдагч → 404.

{
  "object": "terminal",
  "merchant": { "name": "Vending.mn", "icon_url": "https://vending.mn/icon-512.png" },
  "terminal": { "code": "7k2m9x4q3p", "label": "Машин №7", "location": "СБД, 1-р хороо" },
  "pending": null
}

Token ба /me¶

POST /oauth/token → {token_type: "Bearer", access_token, expires_in, refresh_token, scope, user: {ref, sub, verified, locale}}; GET /me → {ref, sub, verified, locale, scope, environment} ба зөвшөөрсөн бол email (profile.email), phone (profile.phone, E.164). ref ба sub нь ижил pairwise утга. Дэлгэрэнгүй: Mini app-ын нээлт ба token.

{
  "token_type": "Bearer",
  "access_token": "gma_at_…",
  "expires_in": 1800,
  "refresh_token": "gma_rt_…",
  "scope": "profile.basic payments",
  "user": { "ref": "u_9f2c4e7a1b3d5f60718293a4b5c6d7e8", "sub": "u_9f2c4e7a1b3d5f60718293a4b5c6d7e8", "verified": true, "locale": "mn" }
}

WebhookEndpoint¶

/webhook-endpoints… (live түлхүүр, webhooks:write) ба консолын /dev/apps/{id}/webhook-endpoints…-ийн хариу. Жагсаалт {"data": [WebhookEndpoint], "next_cursor": null}; үүсгэх (201) ба secret солих (200) нь {"endpoint": WebhookEndpoint, "webhook_secret": "whsec_…", "notice": "…"} — secret зөвхөн тэр хариунд. Тайлбар: Webhook.

Талбар	Төрөл	null	Утга
`id`	string		`we_` + 24 base62
`object`	string		`"webhook_endpoint"`
`environment` · `livemode`	string · boolean		`test` / `live` — endpoint зөвхөн өөрийн орчны event-ийг авна
`url`	string		https, нийтийн хаяг
`description`	string		≤ 200, эсвэл `""`
`event_types`	string[]		шүүлтүүр, ≤ 20; `[]` = бүх event (`webhook.test` шүүлтүүрт орохгүй — тест үргэлж хүрнэ)
`status`	string		`active` · `disabled` (та унтраасан) · `auto_disabled` (5 хоног бүх хүргэлт амжилтгүй)
`disabled_reason`	string	тийм	`auto_disabled` үеийн шалтгаан
`legacy`	boolean		`true` = endpoint №1 — апп-ын хуучин ганц webhook URL-аас шилжсэн (консолын `POST /dev/apps/{id}/webhook` үүнийг засна)
`previous_secret_until`	string (цаг)	тийм	secret солисны дараа хуучин нь хамт гарын үсэг зурах хугацааны төгсгөл (24 цаг)
`failing_since`	string (цаг)	тийм	бүх хүргэлт амжилтгүй болж эхэлсэн мөч; амжилттай хүргэлт арилгана
`last_success_at`	string (цаг)	тийм	сүүлийн амжилттай хүргэлт
`deliveries_24h`	object	(жагсаалтад л)	`{delivered, failing}` — сүүлийн 24 цагийн хүргэлт
`created_at` · `updated_at`	string (цаг)

{
  "id": "we_8kQ2mX4pL7zR1tV9bN3cW5yA",
  "object": "webhook_endpoint",
  "environment": "live",
  "livemode": true,
  "url": "https://shop.mn/hooks/gerege",
  "description": "Захиалгын сервер",
  "event_types": ["payment_intent.succeeded", "refund.succeeded", "refund.failed"],
  "status": "active",
  "disabled_reason": null,
  "legacy": false,
  "previous_secret_until": null,
  "failing_since": null,
  "last_success_at": "2026-10-27T03:12:09Z",
  "created_at": "2026-10-20T08:00:00Z",
  "updated_at": "2026-10-20T08:00:00Z"
}

TerminalBatch¶

POST /terminals/batch-ийн хариу (200) — мөр бүрийн үр дүн, илгээсэн дарааллаар. Нэг ч буруу мөр (400 validation_error, terminals[i].…) бол batch бүхэлдээ татгалзагдаж энэ объект ирэхгүй.

Талбар	Төрөл	null	Утга
`object`	string		`"terminal_batch"`
`data[].index`	integer		мөрийн дугаар (0-ээс)
`data[].status`	string		`created` · `existing` (тэр `reference` бүртгэлтэй — давталт аюулгүй) · `failed` · `skipped` (оролдоогүй — batch-аа дахин илгээ)
`data[].terminal`	Terminal	тийм	`created` / `existing` үед
`data[].error`	object	(`failed` үед л)	`{code, error}` — `reference_taken`, `invalid_sub_merchant` г.м.
`created` · `existing` · `failed` · `skipped`	integer		тоо

{
  "object": "terminal_batch",
  "data": [
    { "index": 0, "status": "created", "terminal": { "id": "4b8e6c1a-2d3f-4a5b-9c7d-0e1f2a3b4c5d", "object": "terminal", "code": "7k2m9x4q3p", "…": "…" } },
    { "index": 1, "status": "failed", "terminal": null, "error": { "code": "invalid_sub_merchant", "error": "…" } }
  ],
  "created": 1, "existing": 0, "failed": 1, "skipped": 0
}

Statement¶

GET /statements?from=&to=&sub_merchant_id=&format=json|csv (settlements:read) — апп-ын мөнгөний хөдөлгөөн мөр бүрээр, Улаанбаатарын өдрөөр. format=csv бол ижил мөрүүд CSV-ээр (UTF-8 BOM, ,, толгой: date, type, payment_intent, refund, settlement, sub_merchant, reference, gross, fee, net, balance_after, currency). Тайлбар: Тайлан.

Талбар	Төрөл	null	Утга
`object`	string		`"statement"`
`app_id`	string (UUID)
`sub_merchant`	string (UUID)	тийм	`sub_merchant_id` өгсөн бол тэр урсгал (`""` өгвөл апп-ын өөрийнх — `null`)
`environment`	string		түлхүүрийн орчин
`from` · `to`	string		`YYYY-MM-DD` (хоёулаа орно), `timezone`: `Asia/Ulaanbaatar`
`currency`	string		`MNT`
`streams[]`	object		урсгал бүр (апп-ын өөрийн, дэд худалдагч бүрийн): `{sub_merchant, opening_balance, closing_balance}`
`totals`	object		`{captured, refunded, fees, settlement_paid, net}`
`data[].date` · `data[].at`	string		Улаанбаатарын огноо · UTC мөч
`data[].type`	string		`captured` · `refunded` · `fee` · `settlement_paid` · `fee_carried` · `clearing_carried`
`data[].payment_intent` · `refund` · `settlement` · `sub_merchant` · `reference`	string	тийм	мөрийн холбогдох объект
`data[].gross` · `fee` · `net`	integer		мөрийн дүн (₮, тэмдэгтэй)
`data[].balance_after`	integer		тухайн урсгалын клирингийн үлдэгдэл мөрийн дараа
`data[].currency`	string		`MNT`

Нэг тайлан ≤ 100 000 мөр (422 statement_too_large — хугацааг богиносго). Тооцоо асаагүй урсгалд (өнөөдрийн ихэнх апп, мөн test) capture бүр шууд payout данс руу явсан тул captured мөрийн дараа ижил дүнтэй settlement_paid мөр гарч, үлдэгдэл 0 хэвээр.

Key¶

Консолын «Түлхүүр» (/dev/apps/{id}/keys…) — server API биш: түлхүүрийг зөвхөн консол үүсгэж, харна. Үүсгэх, солих хариу нэмэлтээр client_secret (нэг удаа), notice, солих үед previous_key-тэй. Дүрэм: API-ийн нийтлэг дүрэм.

Талбар	Төрөл	null	Утга
`id`	string (UUID)		консолын id
`object`	string		`"api_key"`
`name` · `environment`	string		≤ 60 · `test` / `live`
`client_id`	string		`gk_live_…` / `gk_test_…` (хуучин хос бол `mapp_…`)
`secret_hint`	string	тийм	secret-ийн сүүлийн 4 тэмдэгт
`scopes`	string[]		`payments:read` г.м.
`allowed_ips`	string[]		CIDR; `[]` = хаанаас ч
`legacy`	boolean		«Анхдагч түлхүүр» (хуучин `mapp_…` хос)
`status`	string		`active` · `expired` · `revoked`
`created_by`	object	тийм	`{user_id, name}`
`created_at` · `expires_at` · `last_used_at` · `revoked_at`	string (цаг)	`created_at`-аас бусад нь тийм	`last_used_at` минутад нэгээс олонгүй шинэчлэгдэнэ
`last_used_ip` · `revoke_reason` · `rolled_from` · `rolled_to`	string	тийм