Талбарын толь

InvoiceDto болон төлбөрийн хариуны бүх талбарын утга, төрөл, жишээ — бусад хуудас энэ толь руу заана.

Энэ хуудас нь gov-pay channel-api буцаадаг үндсэн объектуудын талбар бүрийн утга, төрөл, жишээг нэг дор цуглуулсан толь. API-ийн бусад хуудаснууд талбарын тайлбарыг давтахын оронд энд заана.

InvoiceDto

GET /invoices, GET /invoices/{id}, GET /invoices/ref/{refNum}, GET /invoices/{id}/refresh зэрэг бүх нэхэмжлэлийн endpoint нэг ижил InvoiceDto бүтцийг буцаана.

Статусын утгуудын дэлгэрэнгүйг Статус ба төлөв хуудаснаас үз.

Prop

Type

source талбар PUBLIC channel-api-д буцаагдахгүй. Энэ нь дотоод гарал үүслийн мэдээлэл бөгөөд партнёрт ил гаргадаггүй. InvoiceDto-д зөвхөн дээрх талбарууд л агуулагдана — бусад талбар хүлээж болохгүй.

InvoiceDto жишээ

{
  "id": "6f1c2e4a-0b3d-4e5f-8a91-2c3d4e5f6a7b",
  "description": "Тээврийн хэрэгслийн албан татвар",
  "amount": 150000,
  "status": "open",
  "dueDate": "2026-07-15T00:00:00.000Z",
  "issuedAt": "2026-06-01T03:12:00.000Z",
  "vehicleNo": "УБ 1234 АА",
  "payer": {
    "register": "УХ12345678",
    "name": "Бат-Эрдэнэ"
  },
  "payee": {
    "id": "mof-tax-01",
    "name": "Татварын ерөнхий газар"
  },
  "year": 2026
}

GET /invoices жагсаалтын хариу

GET /invoices нь нэг шүүлтүүрээр (ttd=, vehicle= эсвэл taxRef= — яг нэг) нэхэмжлэлийн жагсаалт буцаана.

Талбар	Төрөл	Тайлбар
`invoices`	`InvoiceDto[]`	Шүүлтүүрт тохирох нэхэмжлэлүүдийн массив.
`total`	`number`	Дүнгийн нийлбэр (₮), нэхэмжлэлийн тоо ширхэг БИШ. Жагсаалтын бүх `amount`-ийн нийлбэр.

total нь тоо ширхэг гэж андуурч болохгүй. Энэ нь жагсаалт дахь бүх нэхэмжлэлийн дүнгийн нийлбэр төгрөгөөр. Нэхэмжлэлийн тоог авахын тулд invoices.length ашигла.

{
  "invoices": [
    {
      "id": "6f1c2e4a-0b3d-4e5f-8a91-2c3d4e5f6a7b",
      "description": "Тээврийн хэрэгслийн албан татвар",
      "amount": 150000,
      "status": "open",
      "dueDate": "2026-07-15T00:00:00.000Z",
      "issuedAt": "2026-06-01T03:12:00.000Z",
      "vehicleNo": "УБ 1234 АА",
      "payer": { "register": "УХ12345678", "name": "Бат-Эрдэнэ" },
      "payee": { "id": "mof-tax-01", "name": "Татварын ерөнхий газар" }
    }
  ],
  "total": 150000
}

Төлбөрийн хариу

POST /payments амжилттай үед 201, GET /payments/{id} нь төлбөрийн одоогийн төлвийг буцаана. Доорх талбарууд эдгээр хариунд гарч ирнэ.

Талбар	Төрөл	Тайлбар
`id`	`string` (UUID)	Төлбөрийн дотоод ID. Статус шалгах (`GET /payments/{id}`), цуцлах (`DELETE /payments/{id}`), webhook-ийн давхардал шүүхэд ашиглана.
`status`	`string` (enum)	Төлбөрийн төлөв: `pending`, `submitted`, `confirmed`, `failed`, `canceled`. Статус ба төлөв хуудсыг үз.
`amount`	`number`	Төлсөн дүн төгрөгөөр (₮).
`invoiceId`	`string` (UUID)	Энэ төлбөртэй холбоотой үндсэн нэхэмжлэлийн ID.
`invoiceIds`	`string[]` (UUID)	Энэ төлбөрт хамаарах бүх нэхэмжлэлийн ID-ийн массив. `confirmed` болоход эдгээр бүгд `paid` болно.
`paidAt`	`string` (ISO 8601, заавал биш)	Төлбөр баталгаажсан (`confirmed`) огноо цаг. `confirmed` болоогүй үед байхгүй байж болно.
`qpay`	`object`	QR болон банк/wallet deeplink-үүд. Зөвхөн `POST /payments` хариунд гарна. Бүтцийг доор үз.

POST /payments нь PUBLIC API-д нэг нэхэмжлэл авна (body { invoiceId, amount? }), массив биш. Гэхдээ хариун дахь invoiceIds нь нэгээс олон элемент агуулж болно — серверийн талд холбогдсон нэхэмжлэлүүд багтана.

qpay объект

POST /payments хариун дахь qpay нь gov-pay-ийн server талд угсарсан төлбөрийн QR ба deeplink-үүдийг агуулна.

Талбар	Төрөл	Тайлбар
`qrText`	`string`	EMVCo QR-ийн түүхий текст (raw payload).
`qrImage`	`string` (base64 PNG)	QR зургийн base64-дэлгэцэнд `data:image/png;base64,<qrImage>` болгож харуулна.
`shortUrl`	`string` (заавал биш)	Богино URL (хувилбараас хамаарч байж болно).
`urls`	`object[]`	Банк/wallet тус бүрийн deeplink жагсаалт. Элемент бүр `{ name, description, logo, link }`.

{
  "success": true,
  "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "status": "submitted",
  "amount": 150000,
  "invoiceId": "6f1c2e4a-0b3d-4e5f-8a91-2c3d4e5f6a7b",
  "invoiceIds": ["6f1c2e4a-0b3d-4e5f-8a91-2c3d4e5f6a7b"],
  "qpay": {
    "qrText": "00020101021…",
    "qrImage": "iVBORw0KGgoAAAANSUhEUgAA…",
    "shortUrl": "https://s.tts.qpay.mn/abc123",
    "urls": [
      {
        "name": "Khan Bank",
        "description": "Хаан банк апп",
        "logo": "https://…/khanbank.png",
        "link": "khanbank://q?qr=…"
      }
    ]
  }
}

QR-ийг хэрхэн харуулах, qrStandard (qpay / govstd), deeplink угсралтын дэлгэрэнгүйг QR стандартууд болон Төлбөр хуудаснаас үз.

Амжилтгүй төлбөрийн хариу

POST /payments амжилтгүй бол 422 статустайгаар дараах бүтэц буцна:

{
  "success": false,
  "refNum": "MOF-2026-000123",
  "message": "Нэхэмжлэл аль хэдийн төлөгдсөн"
}

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

Статус ба төлөв — нэхэмжлэл болон төлбөрийн статусуудын утга, state machine.
QR стандартууд — qrStandard, qpay объект, deeplink харуулах.
Алдааны кодууд — 400/422 болон бусад статус кодын дэлгэрэнгүй.
Төлбөр — POST /payments, идемпотентность, QR угсралт.
Webhook тойм — payment.submitted, payment.confirmed event-ийн payload.
Орчин — sandbox / production base URL.