Толь бичиг

gov-pay channel-api интеграцид хэрэглэгддэг гол нэр томьёоны тодорхойлолт.

Энэ хуудас нь gov-pay channel-api-г интеграцлахад тааралддаг гол нэр томьёог тайлбарлана. Дэлгэрэнгүй мэдээллийг холбогдох хуудаснаас үзнэ үү.

ID-ийн талаар нэг зүйлийг анхаарна уу: нэхэмжлэл нь хоёр өөр танигчтай. ref_num нь төрийн системийн (MoF) нэхэмжлэлийн дугаар, gov-pay invoice id нь gov-pay доторх UUID. Эдгээр нь ялгаатай тул хооронд нь андуурч болохгүй.

Танигч ба субъектууд

Нэр томьёо	Тайлбар
ТТД	Татвар төлөгчийн дугаар буюу регистр. `GET /invoices?ttd=` шүүлтүүрт болон `payer.register` талбарт ашиглагдана.
ref_num (refNum)	MoF (Сангийн яам) талын нэхэмжлэлийн дугаар. `GET /invoices/ref/{refNum}`-аар нэхэмжлэлийг шууд MoF-аас татна. Төлбөр амжилтгүй болсон үед `422` хариунд `refNum` буцаана.
gov-pay invoice id	gov-pay доторх нэхэмжлэлийн дотоод UUID. `InvoiceDto.id` талбар, мөн `GET /invoices/{id}`, `GET /invoices/{id}/refresh`, `POST /payments` (`invoiceId`)-д ашиглагдана. ref_num-аас ялгаатай — энэ нь gov-pay-ийн дотоод танигч, ref_num нь дугаар. Буруу хэлбэрийн UUID → `400`.
payer (төлөгч)	Нэхэмжлэлийг төлөх ёстой этгээд. `InvoiceDto.payer` нь `{ register, name }` бүтэцтэй.
payee (хүлээн авагч)	Төлбөрийг хүлээн авах төрийн байгууллага. `InvoiceDto.payee` нь `{ id, name }` бүтэцтэй.
source (эх сурвалж)	Нэхэмжлэл хаанаас үүссэнийг заана (жишээ нь `mof`, `etax`, `police`). PUBLIC API-д буцаагдахгүй — энэ талбар нь дотоод зориулалттай тул партнёрт нуугдсан.

Нэхэмжлэл ба төлбөр

Нэр томьёо	Тайлбар
InvoiceDto	Нэхэмжлэлийн public хариу. Талбарууд: `id`, `description`, `amount` (₮, тоон утга), `status`, `dueDate`, `issuedAt`, `vehicleNo`, `payer`, `payee`, `year?`.
Нэхэмжлэлийн статус	`open` (нээлттэй), `paid` (төлөгдсөн), `overdue` (хугацаа хэтэрсэн), `canceled` (цуцлагдсан).
total (`GET /invoices` хариунд)	Шүүлтээр олдсон нэхэмжлэлүүдийн дүнгийн нийлбэр (₮), тоо ширхэг БИШ.
DB cache vs refresh	`GET /invoices/{id}` нь gov-pay-ийн DB cache-ээс уншина. `GET /invoices/{id}/refresh` нь ШИНЭЭР татна.
Төлбөрийн статус	`pending` → `submitted` → `confirmed`; эсвэл `failed`; эсвэл `canceled`. `submitted` = төрийн системд илгээгдсэн; `confirmed` = MoF баталсан (төлөгдсөн); `canceled` = холбогдох нэхэмжлэлүүдийг `open` руу буцаана.
settlement / тооцоо	өдрийн тооцоо. `POST /payments/report` (`{ financeDay }`)-аар тухайн санхүүгийн өдрийн `entries[]`-ийг авна.

Дэлгэрэнгүйг Төлбөр хуудаснаас үзнэ үү.

Аюулгүй байдал ба найдвартай байдал

Нэр томьёо	Тайлбар
X-API-Key	Партнёрийн API key. `/health/*`-аас бусад бүх endpoint-д шаардлагатай header. Байхгүй/буруу → `401`, идэвхгүй партнёр → `403`.
Идемпотентность (idempotency)	`POST /payments`-д `X-Idempotency-Key` header-ээр давтан хүсэлтийг хамгаална. Ижил key-ээр (партнёр тус бүрд) дахин илгээвэл cache-лагдсан хариу + `"message": "idempotent"` буцаана. Key болгож өөрийн хүсэлтийн UUID-г ашигла.
Rate limit	API key тус бүрд: 5/сек, 60/мин, 1000/цаг (Redis-д тоологдоно). Хэтэрвэл → `429`.

QR ба deeplink

Нэр томьёо	Тайлбар
qrStandard	Партнёрийн QR стандарт: `qpay` (EMVCo tag 27, AID + QPP_QR) эсвэл `govstd` (tag 26, MN scheme). EMVCo QR болон банкны deeplink-ийг gov-pay ВСЕГДА server талд угсарна. Стандарт солихыг хүсвэл gov-pay-тэй холбогдоно.
qpay (хариун дахь объект)	`POST /payments` амжилттай хариунд орох QR мэдээлэл: `{ qrText, qrImage, shortUrl?, urls[] }`. `qrImage` нь base64 PNG — `data:image/png;base64,<qrImage>` болгож харуулна.
urls[]	Банк/wallet тус бүрийн deeplink жагсаалт. Элемент бүр `{ name, description, logo, link }` бүтэцтэй.

Webhook

Нэр томьёо	Тайлбар
Webhook	Үйл явдал тохиолдоход gov-pay-ээс таны `url` руу илгээх HTTP мэдэгдэл. `POST /webhooks` (`{ url, secret, events[] }`)-аар бүртгэнэ. `GET /webhooks` нь secret-ийг БУЦААХГҮЙ.
Event	`payment.submitted` (payload `{ id, invoiceId }`) ба `payment.confirmed` (payload `{ id, amount }`). Хүргэлтийн header: `X-GovPay-Event`.
HMAC гарын үсэг	Webhook биеийн HMAC-SHA256 (таны secret-ээр тооцсон), `X-GovPay-Signature` header-ээр ирнэ. Хүлээн авагч талдаа дахин тооцож тулгаж шалгана.

Webhook-ийн ажиллагааг Webhook, гарын үсгийн баталгаажуулалтыг Гарын үсэг шалгах хуудаснаас үзнэ үү.

Webhook хүлээн авагч нь 5 секундын дотор хурдан 2xx буцааж, idempotent (payment id-аар давхардлыг шүүх) байх ёстой.

Холбоотой хуудаснууд

Орчин — Sandbox / Production / Local dev base URL-ууд.
Төлбөр — төлбөрийн урсгал, статусын шилжилт.
Алдааны кодууд — 400, 401, 403, 404, 422, 429, 5xx.
Webhook — webhook бүртгэл ба хүргэлт.
Гарын үсэг шалгах — HMAC-SHA256 баталгаажуулалт.