Статус ба төлөв

Нэхэмжлэл болон төлбөрийн статусуудын утга, төлбөрийн амьдралын мөчлөгийн state machine.

gov-pay-д хоёр төрлийн статус байдаг: нэхэмжлэлийн статус (invoice) ба төлбөрийн статус (payment). Эдгээр нь хоорондоо холбоотой боловч ялгаатай объектын төлөв учраас тусад нь ойлгох нь чухал.

Нэхэмжлэлийн статус

InvoiceDto.status талбар нь нэхэмжлэлийн одоогийн төлвийг илэрхийлнэ.

Статус	Утга
`open`	Төлөгдөөгүй, төлбөр хүлээж буй нэхэмжлэл. Төлбөр хийх боломжтой.
`paid`	Төлөгдсөн. Холбоотой төлбөр `confirmed` болсон үед энэ статус руу шилждэг.
`overdue`	Хугацаа хэтэрсэн (`dueDate` өнгөрсөн) боловч төлөгдөөгүй.
`canceled`	Цуцлагдсан нэхэмжлэл.

Зөвхөн open (эсвэл overdue) статустай нэхэмжлэлд төлбөр хийнэ. Хугацаа хэтэрсэн нэхэмжлэлийг шүүхдээ Тайлан/summary-ийн оронд GET /reports/summary (open, overdue, paid, totalAmountDue) ашиглаж нийт төлөвийг харж болно.

Төлбөрийн статус

POST /payments-ээр төлбөр үүсгэх үед төлбөрийн объект дараах статусуудаар дамжина.

Статус	Утга
`pending`	Төлбөр үүссэн, гэхдээ төрийн систем рүү хараахан илгээгдээгүй эхний төлөв.
`submitted`	Төрийн системд (MoF) илгээгдсэн. Энэ үед `payment.submitted` webhook event илгээгдэнэ.
`confirmed`	MoF баталсан — төлбөр амжилттай төлөгдсөн. `payment.confirmed` webhook event илгээгдэнэ.
`failed`	Төрийн систем татгалзсан. `POST /payments` нь `422 { success:false, refNum, message }` буцаана.
`canceled`	`DELETE /payments/{id}`-ээр цуцлагдсан. Холбоотой нэхэмжлэлүүд `open` руу буцна.

failed нь синхрон үр дүн — POST /payments дуудах үед 422 HTTP статусаар шууд буцна. submitted → confirmed шилжилт нь асинхрон бөгөөд MoF талаас баталсан үед болдог тул webhook-аар сонсох эсвэл GET /payments/{id}-ээр polling хийж мэдэх ёстой.

Аль ч мөчид төлбөрийн одоогийн статусыг GET /payments/{id} ашиглан шалгаж болно:

curl -H "X-API-Key: $API_KEY" \
  https://tts.qpay.mn/api/v1/payments/{id}

{
  "id": "…",
  "status": "confirmed",
  "amount": 150000,
  "invoiceId": "…",
  "invoiceIds": ["…"],
  "paidAt": "2026-06-29T08:21:00.000Z"
}

Төлбөрийн амьдралын мөчлөг (state machine)

Нэхэмжлэлийн статустай холбоо

Төлбөрийн статусын шилжилт нь холбоотой нэхэмжлэлүүдийн статусыг шууд өөрчилнө:

confirmed болоход — тухайн төлбөрт холбоотой нэхэмжлэл(үүд) paid болно. invoiceIds-д жагсаасан бүх нэхэмжлэл төлөгдсөнд тооцогдоно.
canceled болоход — холбоотой нэхэмжлэлүүд open руу буцна. Өөрөөр хэлбэл цуцлалт нь нэхэмжлэлийг дахин төлбөр хүлээх төлөвт оруулдаг тул шаардлагатай бол дахин POST /payments хийж болно.

DELETE /payments/{id} нь submitted болон confirmed аль аль төлвөөс цуцлах боломжтой ба { id, canceled } буцаана. Цуцлалтын дараа нэхэмжлэлийн статус open болсныг GET /invoices/{id}-ээр баталгаажуулж болно.

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

Төлбөр — POST /payments, идемпотентность, QR угсралт.
Webhook тойм — payment.submitted, payment.confirmed event.
Гарын үсэг шалгах — webhook-ийн HMAC-SHA256 баталгаажуулалт.
Алдааны кодууд — 422 болон бусад статус кодын дэлгэрэнгүй.
Орчин — sandbox / production base URL.