Олон эзэмшигчтэй платформ — дэд худалдагч¶

Энэ хуудсаар

Юу хийх: нэг худалдагч апп дотор олон эзэмшигчийн (машины эзэд, маркетплейсийн дэлгүүрүүд, франчайз) мөнгийг эзэмшигч бүрийн өөрийн дансанд оруулах — данс бүрийг түүний эзэмшигч өөрөө Gerege App-д баталсны дараа. Хугацаа: ~2 цаг (+ эзэмшигч бүр батлах). Хэрэгтэй: худалдагч апп ба live түлхүүр (бичих нь live-д л), эзэмшигч бүрийн Gerege Wallet данс (хүний эсвэл байгууллагын).

Платформ (vending.mn шиг: машин бүр өөр эзэнтэй) нэг худалдагч апп. Эзэмшигч бүр — дэд худалдагч: өөрийн payout данс, өөрийн тооцооны урсгал, өөрийн клиринг; дүрэм (шимтгэл, хуваарь) нь апп-ынх.

1. Хэн юуг эзэмших¶

Байгууллага (таны workspace)
 └─ Худалдагч апп «Vending.mn»  ── түлхүүр, webhook, review, шимтгэлийн дүрэм
     ├─ Дэд худалдагч «Батаа ХХК» (code: owner-17) ── payout: ******4560 (Батаа ХХК-ийн админ баталсан)
     │    ├─ Терминал «Машин №7»
     │    └─ Терминал «Машин №9»
     └─ Дэд худалдагч «Сараа» (code: owner-42) ── payout: ******8812 (Сараа өөрөө баталсан)
          └─ Терминал «Машин №12»

Intent нь терминалынхаа дэд худалдагчийг автоматаар авна, эсвэл sub_merchant_id-аар (терминалгүй qr, redirect-д) заана. Хүнд төлөх цонхонд дэд худалдагчийн display_name харагдана.

2. Дэд худалдагч бүртгэх¶

curl https://geregeapp.mn/api/v1/miniapp/sub-merchants -u "$GEREGE_LIVE_ID:$GEREGE_LIVE_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"code": "owner-17", "display_name": "Батаа ХХК", "legal_name": "Батаа Трейд ХХК", "reg_no": "1234567"}'

{
  "id": "9a7c5d1e-…", "object": "sub_merchant", "code": "owner-17",
  "display_name": "Батаа ХХК", "legal_name": "Батаа Трейд ХХК", "reg_no": "1234567", "status": "active",
  "payouts_configured": false, "payout_account": null, "payout_linked_at": null,
  "created_at": "2026-10-27T09:00:00Z", "updated_at": "2026-10-27T09:00:00Z"
}

code — таны платформын эзэмшигчийн ID (^[A-Za-z0-9_.:-]{1,40}$), байгалийн idempotency key: дахин POST → тэр мөр 200. Хэзээ ч өөрчлөгдөхгүй (PATCH → 400 code_immutable).
display_name 1–80 (хүнд харагдана), legal_name ≤ 160, reg_no ≤ 20.
PATCH /sub-merchants/{id} — нэрс, reg_no, status: "active" | "disabled". GET /sub-merchants, GET …/{id}.
Бичих нь зөвхөн live түлхүүр эсвэл консол (test → 403 live_only) — дэд худалдагч хоёр орчинд нэг бүртгэл, live capture хаашаа явахыг шийддэг тул sandbox secret түүнийг өөрчилж болохгүй.

3. Payout холболт — эзэмшигч өөрөө батална¶

Таны сервер эзэмшигчийн орлогыг дурын данс руу чиглүүлж чадахгүй. Чадвал таны сервер эвдэрсэн өдөр бүх эзэмшигчийн мөнгийг нэг дор өөр тийш эргүүлэх зам болно. Тиймээс та хүсэлт гаргаж, дансны эзэмшигч Gerege App-д Face ID-аар батална:

curl https://geregeapp.mn/api/v1/miniapp/sub-merchants/9a7c5d1e-…/payout-link -u "$GEREGE_LIVE_ID:$GEREGE_LIVE_SECRET" \
  -H 'Content-Type: application/json' -d '{"account": "MN75 0098 0009 8123 4560"}'

{
  "id": "5f1e…", "object": "payout_link", "sub_merchant": "9a7c5d1e-…", "status": "pending",
  "account_masked": "******4560", "requested_at": "2026-10-27T09:05:00Z", "expires_at": "2026-11-03T09:05: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."
  }
}

account — MN IBAN (MN + 18 орон) эсвэл 10 оронтой Gerege Wallet дансны дугаар; зай, зураас болно. Данс идэвхтэй, MNT байх ёстой (үгүй бол 400 validation_error, path: "account"). Өмнөх pending хүсэлт canceled болно. Минутад ≤ 30 хүсэлт (хүсэлт бүр хүнд push илгээдэг).
Хэнээс асуух нь дэвтэрт бүртгэлтэй дансны эзэмшигчээс:

Данс	Хэн батлах
Хүний Gerege Wallet	тэр хүн өөрөө
Байгууллагын Gerege Wallet данс	тэр байгууллагын одоогийн бүх админ мэдэгдэл авна; аль нэг нь батална (батлах агшинд админ хэвээр эсэхийг дахин шалгана)
Gerege App-ын хүн ч, байгууллага ч биш	`422 account_unsupported`

Байгууллагад админ алга → 422 no_admin; админуудыг түр тодорхойлж чадаагүй → 503 directory_unavailable (энэ нь «үгүй» биш — дахин оролдоно уу). 3. Эзэмшигч (админ) мэдэгдэл авна: «Данс холбох хүсэлт» — текст нь зөвхөн таны апп-ын батлагдсан нэр (таны бичсэн текст хэзээ ч биш — түгжээтэй дэлгэц дээрх хэн нэгний үг фишинг суваг). Хүсэлтийг нээхэд апп, дэд худалдагчийн нэр/хуулийн нэр/регистр, далдалсан данс ба terms товчны дэргэд харагдана → Face ID → батлах эсвэл татгалзах (Gerege App: Тохиргоо → Хэтэвч → «Худалдагч ба байгууллага»; API нь GET /api/v1/miniapp/me/payout-links, POST …/{id}/approve · …/decline бэлэн). 4. terms — батлах нь юу гэсэн үг: тооцоо унтраалттай (off/shadow — production одоо shadow) үед дэд худалдагчийн төлбөр шууд энэ данс руу орж, тэдгээрийн буцаалт (90 хоногийн дотор) энэ данснаас гарна. Тооцоо on үед буцаалт эхлээд клирингээс. Эзэмшигч үүнийг мэдэж зөвшөөрсөн байх ёстой — тиймээс хүсэлт, мэдэгдэл, батлах дэлгэц, таны хариу (terms) дөрвүүлээ хэлнэ. Өөрийн UI-д эзэмшигчид мөн харуулна уу. 5. Батлагдмагц дэд худалдагчийн payouts_configured: true, payout_account: "******4560", өмнөх approved холболт superseded.

Төлөвүүд: pending | approved | declined | canceled | superseded | expired (expired = 7 хоногт хариулаагүй). GET /sub-merchants/{id}/payout-links — сүүлийн 50, шинэ нь эхэнд. Эзэмшигч батлах үед данс таных биш/идэвхгүй болсон бол 409 account_unavailable; core banking хариулаагүй бол 502 core_unavailable (хэзээ ч «үгүй» биш).

4. Төлбөр авах¶

Терминалын intent: sub_merchant_id орхино — терминалынх. Өөр дэд худалдагч өгвөл 400 validation_error.
qr/redirect: "sub_merchant_id": "9a7c…".
Live intent нь дэд худалдагчийн payout батлагдаагүй бол үүсэхгүй: 409 payouts_not_configured — хүнд төлж чадахгүй төлбөрийн цонх харуулахгүйн тулд. Test intent-д payout хэрэггүй.
Идэвхгүй дэд худалдагч → 409 sub_merchant_disabled.

Мөнгө барьцаалагдсан үед дэд худалдагчийг идэвхгүй болгохгүй

Идэвхгүй дэд худалдагч шинэ мөнгө авахгүй — requires_capture төлөвтэй intent-ийг capture хийхэд 409 payouts_not_configured ирнэ. Эхлээд тэр дэд худалдагчийн барьцаатай intent-уудыг capture эсвэл cancel хий, дараа нь disabled.

5. Тооцоо — дэд худалдагч бүрт¶

Тооцооны горим (оператор)	Capture-ийн мөнгө	Буцаалт
`off` / `shadow` (анхдагч; production одоо `shadow`)	шууд дэд худалдагчийн батлагдсан payout данс руу	тэр данснаас (`terms`)
`on` + апп-д асаалттай	дэд худалдагчийн клиринг руу; шимтгэл апп-ын дүрмээр; хуваарийн дагуу payout руу	эхлээд клирингээс

Тооцоо (апп, дэд худалдагч) урсгал бүрт тусдаа: өөрийн дараалал, carry, shortfall. Апп-ын өөрийн урсгал (sub_merchant: null) — дэд худалдагчгүй intent-үүд.
GET /settlements, GET /settlements/{id} (live) ба settlement.paid webhook-ийн Settlement объект "sub_merchant": "<id>" | null-тэй — эзэмшигч бүрт тайлангаа үүгээр задална.
Шимтгэлийн томьёо, carry — Mini app төлбөр §7.
Дэд худалдагчаар задалсан CSV тайлан — «удахгүй» (самбар).

6. Эзэмшигч солигдох, гарах¶

Payout данс солих — шинэ payout-link хүсэлт; эзэмшигч батлахад хуучин нь superseded. Батлах хүртэл хуучин данс хэвээр.
Машин шинэ эзэнд — шинэ дэд худалдагч (шинэ code), payout батлуулаад PATCH /terminals/{id} {"sub_merchant_id": "<шинэ>"}. Хуучин эзэмшигчийн аль хэдийн capture хийсэн мөнгө (ба тооцоонд байгаа) түүнд үлдэнэ.
Эзэмшигч гарсан — барьцаатай intent-ээ дуусгаад (§4) PATCH /sub-merchants/{id} {"status": "disabled"}. Мөр устгагдахгүй — түүх, буцаалтад хэрэгтэй.

7. Код¶

Node (@gerege/miniapp-node):

const owner = await gerege.subMerchants.create({ code: "owner-17", display_name: "Батаа ХХК", reg_no: "1234567" });
const link = await gerege.subMerchants.requestPayoutLink(owner.id, { account: "MN75 0098 0009 8123 4560" });
showToOwner(link.status, link.expires_at); // эзэмшигч Gerege App-аас батална; terms-ийг өөрийн UI-д ч харуул

// Дараа нь (cron эсвэл эзэмшигчийн самбар нээгдэхэд):
const current = await gerege.subMerchants.retrieve(owner.id);
if (current.payouts_configured) enableMachines(owner.id);

Go (sdk/go):

owner, err := c.SubMerchants.Create(ctx, miniapp.CreateSubMerchantParams{Code: "owner-17", DisplayName: "Батаа ХХК"})
link, err := c.SubMerchants.RequestPayoutLink(ctx, owner.ID, "MN750098000981234560")
links, err := c.SubMerchants.ListPayoutLinks(ctx, owner.ID) // pending → approved

terms талбарыг одоогийн SDK-ийн PayoutLink төрөл хараахан агуулаагүй (JSON-д байгаа) — шинэчлэгдэнэ.

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

Хэсэг	Төлөв
Дэд худалдагч, payout-link хүсэлт ба `terms`, хүний/байгууллагын данс, (апп, дэд худалдагч)-ын тооцоо	✓
Gerege App-ын батлах дэлгэц (Face ID, `terms` товчны дэргэд)	✓ (iOS)
Дэд худалдагчаар задалсан тайлан, самбарын дэлгэц	«удахгүй»