Тооцоо (settlement)¶

Хүний төлсөн мөнгө таны данс руу хэзээ, ямар замаар, ямар шимтгэлтэйгээр очихыг, тооцооны объектыг хэрхэн уншиж тулгахыг тайлбарлана. Уншихад ~10 минут. Хэрэгтэй: settlements:read scope-той live API түлхүүр (test түлхүүр тооцоо хардаггүй).

Мөнгө хаагуур явах¶

Хоёр зам бий; аль нь хэрэгжих нь оператор таны апп-д тооцоог асаасан эсэхээс хамаарна.

	Тооцоо асаагүй (одоогийн бүх апп)	Тооцоо асаалттай
Capture	мөнгө шууд апп-ын payout данс руу (дэд худалдагчийн intent бол түүний батлагдсан payout данс руу)	мөнгө апп-ын клиринг рүү (апп-ын өөрийнх ба дэд худалдагч бүрийнх тусдаа урсгал)
Шимтгэл	авагдахгүй	төлбөр бүрт capture-ийн үед тогтож, тооцоогоор платформд шилжинэ
Буцаалт	payout данснаас	клирингээс
Payout данс руу	capture бүрт	хуваарийн дагуу тооцоогоор: цэвэр дүн (дүн − буцаалт − шимтгэл)
`GET /settlements`	хоосон	тооцоонууд

Одоогоор production-д ямар ч апп-д тооцоо асаагүй — бүх capture шууд payout данс руу ордог, шимтгэлгүй. Оператор апп-д тооцоо асаахаас өмнө төлбөрийн дүрэм (Шимтгэл) ба payout данс (Payout данс) тохируулна. Асаахаас өмнө capture хийгдсэн төлбөр хэзээ ч тооцоонд орохгүй (шимтгэлгүй хэвээр, буцаалт нь payout данснаас). Апп-ын тооцоог унтраавал шинэ capture дахин payout руу шууд явж, клирингт үлдсэнийг тооцоо дуусгасаар байна.

Хуваарь ба cutoff¶

Хуваарь нь операторын төлбөрийн дүрэмд (апп бүрт):

`schedule`	Хэзээ
`daily`	өдөр бүр `settle_time`-д
`weekdays`	Даваа – Баасан `settle_time`-д (баярын өдрийн хуанли хараахан алга)
`weekly:mon` … `weekly:sun`	долоо хоногт нэг удаа, тэр гарагт
`manual`	хэзээ ч өөрөө биш — оператор гараар

settle_time нь Улаанбаатарын цаг (HH:MM), delay_days (T+N) нь 0–14.
Cutoff — тухайн ажиллалт аль хүртэлх төлбөрийг хамрах: T+N үед ажиллалтын (Улаанбаатарын) өдрөөс N өдрийн өмнөх өдрийн төгсгөл хүртэл capture хийгдсэн төлбөр (жишээ нь T+1, 10:00 → өчигдрийн 24:00 хүртэлх). T+0 бол ажиллалтын мөч хүртэлх бүгд.
Дүрэм байхгүй бол анхдагч: шимтгэл 0, ажлын өдөр (weekdays) 10:00, T+1.
Тооцооны job 15 минут тутам ажилладаг — тооцоо товлосон цагаас 15 минут хүртэл хоцорч болно. Алгасагдсан ажиллалт алдагдахгүй: дараагийн ажиллалтын cutoff түүнийг хамарна.
Түдгэлзүүлсэн апп-ыг хуваарийн дагуу тооцохгүй (оператор гараар л).

Settlement объект¶

GET /settlements/{id}, GET /settlements ба settlement.paid webhook-ийн data.object:

{
  "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
}

Талбар	Утга
`cutoff`	энэ мөчөөс өмнө capture хийгдсэн төлбөрүүд орсон
`gross` · `intent_count`	орсон төлбөрүүдийн нийлбэр ба тоо
`refunds` · `refund_count`	хасагдсан буцаалтууд (энэ эсвэл өмнөх тооцоонд орсон төлбөрийнх)
`fee`	энэ тооцоо авсан шимтгэл (`fee_assessed − fee_returned + fee_carried_in − fee_carried_out`); буцаасан нь авснаасаа их бол сөрөг
`fee_assessed` · `fee_returned`	төлбөрүүдийн шимтгэл · буцаалтаар буцсан шимтгэл
`fee_carried_in` · `fee_carried_out`	өмнөх тооцооноос шилжиж ирсэн · дараагийнх руу шилжсэн шимтгэл (авах мөнгө байгаагүй бол)
`clearing_carried_in` · `clearing_carried_out`	өмнөх тооцоонуудын дараа клирингээс гарсан, тэр тооцооны дүнгээс хэтэрсэн буцаалт — энд суутгагдсан · дараагийнх руу шилжсэн
`recovered`	`clearing_carried_in − clearing_carried_out`
`net`	`gross − refunds − fee`
`paid`	payout данс руу шилжсэн дүн, `net − holdback + released − reserve_refunds − recovered` (≥ 0; 0 байж болно)
`holdback` · `released` · `reserve_refunds` · `holdback_release_at`	үргэлж `0` / `null` — нөөц (holdback) байхгүй
`destination_masked`	payout данс, сүүлийн оронгууд л
`sub_merchant`	дэд худалдагчийн урсгал бол түүний id, апп-ын өөрийнх бол `null`
`failure_code`	`failed` үед: `insufficient_funds`, `destination_unavailable`, `limit_exceeded`, `idempotency_conflict`, `rejected`
`livemode`	үргэлж `true`

Буцаах шимтгэл, carry-ийн тоо нь бүхэл ₮, бүх тэнцэтгэл сервер дээр шалгагдана — paid-ийг өөрөө дахин бодох хэрэггүй, харин тулгалтдаа эдгээр тэнцэтгэлийг ашиглаж болно.

Төлөв¶

`status`	Утга
`pending`	тооцоо бодогдож мөр нь хөлдсөн, дэвтэрт бичигдэж байна (хариу тодорхойгүй бол ижил key-ээр дахин)
`paid`	`paid` дүн payout данс руу шилжсэн (`paid_at`); `settlement.paid` илгээгдэнэ
`failed`	дэвтэр татгалзав (`failure_code`) — оператор ижил мөрөөр дахин оролдох эсвэл хүчингүй болгоно; хүчингүй болсон тооцооны төлбөрүүд дараагийн тооцоонд орно

Апп-ын нэг урсгалд нээлттэй (pending / failed) тооцоо нэгээс илүүгүй — дараагийнх нь өмнөхөө дуусахыг хүлээнэ. Хүчингүй болгосон (void) тооцоог апп-ын backend хардаггүй; консолд харагдана. Юу ч хөдлөхгүй тооцоо (бүгд шимтгэл эсвэл carry) шууд paid болж paid: 0-тэй settlement.paid илгээнэ.

Жишээ¶

Дүрэм: шимтгэл 2 % (fee_bps: 200), refund_fee: false, daily 10:00, T+1.

Огноо (UB)	Юу болов	Клирингт	Payout данс руу
10-21	3 төлбөр: 10 000, 25 000, 65 000 (шимтгэл 200 + 500 + 1 300)	100 000	0
10-21	3-р төлбөрөөс 5 000 буцаав	95 000	0
10-22 00:00	50 000 төлбөр (шимтгэл 1 000) — яг cutoff-ын мөчид тул дараагийн тооцоонд	145 000	0
10-22 10:00	Тооцоо (cutoff 10-22 00:00): gross 100 000, refunds 5 000, fee 2 000 → `paid` 93 000	50 000	93 000
10-22	1-р төлбөрөөс 10 000 буцаав (тооцоонд орсон; клирингт 50 000 бий)	40 000	93 000
10-22	3-р төлбөрөөс 45 000 буцаах хүсэлт → клирингт 40 000 < 45 000 → `refund.failed` (`settlement_shortfall`)	40 000	93 000
10-23 10:00	Тооцоо: gross 50 000, refunds 10 000, fee 1 000 → `paid` 39 000	0	132 000

Шалгалт: хүмүүс 150 000 төлж 15 000 буцаан авсан; платформын шимтгэл 3 000; та 132 000 = 150 000 − 15 000 − 3 000.

Shortfall. Тооцоонд орж таны данс руу шилжсэн төлбөрийн буцаалт клирингт одоо байгаа мөнгөнөөс (дараагийн төлбөрүүдээс) гарна. Клиринг хүрэлцэхгүй бол буцаалтыг settlement_shortfall-аар татгалзана — авлага (буцаалтыг урьдчилж, дараагийн тооцоонуудаас суутгах) хараахан хийгдээгүй; оператор ийм буцаалтуудын жагсаалтыг хардаг.

Carry. Тооцооны дараа клирингээс гарсан буцаалт тухайн тооцооны gross-оос их бол илүүдэл нь дараагийн тооцоонд суутгагдана (clearing_carried_*); авах мөнгө байхгүй шимтгэл (жишээ нь бүтэн буцаалт, refund_fee: false) дараагийн тооцоонд шилжинэ (fee_carried_*).

Унших — API¶

Апп-ын backend (settlements:read scope-той API түлхүүрээр Basic, эсвэл payments зөвшөөрөлтэй хүний token), зөвхөн live — test credential үргэлж хоосон жагсаалт авна.

curl -sS "https://geregeapp.mn/api/v1/miniapp/settlements?status=paid&limit=20" \
  -u "$GEREGE_CLIENT_ID:$GEREGE_CLIENT_SECRET"
# → {"items": [Settlement, …], "next_cursor": "st_…" | null, "has_more": true | false}

Параметр	Утга
`status`	`pending` · `paid` · `failed`; өөр → `400 invalid_status`
`cursor`	өмнөх хуудасны `next_cursor`; буруу → `400 invalid_cursor`
`limit`	1 – 100, анхдагч 20; өөр → `400 invalid_limit`

Шинэ нь эхэнд. GET /settlements/{id} нь Settlement + intents[] (id, amount, fee, reference, confirmed_at) + refund_items[] (id, intent_id, amount, fee_returned, source) + truncated — мөр 1000-аас олон бол эхний 1000 ба truncated: true. Дэд худалдагчийн тооцоонуудыг sub_merchant-аар ялга. Суулгацад тооцооны сан алга бол 503 settlements_unavailable.

Хөгжүүлэгчийн консол ижил тооцоонуудыг (хүчингүй болгосныг оруулаад) апп бүрээр харуулна. Мөнгөний мөр бүрийг (JSON эсвэл CSV) Тайлан-аас татна (мөн settlements:read).

Webhook¶

settlement.paid — тооцоо paid болох мөчид, үргэлж livemode: true, data.object = Settlement. paid 0 байж болно. Event-ийн лавлах.