SmartPay Agent API — интеграцийн заавар

Төрийн сангийн (МОФ) QR нэхэмжлэх үүсгэх, төлбөрийн callback хүлээн авах заавар.

Орчин ба хаяг#

ОрчинХаяг
Продhttps://agent.epayment.mn/api
Тестhttps://dev-agent.epayment.mn/api
Анхаар

Тест орчинд үүсгэсэн нэхэмжлэхэд callback ирэхгүй.

Authentication#

Хүсэлт бүрт X-Api-Key header шаардлагатай. Key-г EPay өгнө.

http
X-Api-Key: <key>

Нэхэмжлэх үүсгэх#

POST/api/invoicesX-Api-Key
json
{
  "header": {
    "from_": { "system_owner": "E-Health", "institution_id": "9077219", "institution_name": "ГССҮТ" },
    "to_":   { "system_owner": "MOF",      "institution_id": "9131787", "institution_name": "Төрийн сан" },
    "version": "1.0",
    "bussines_service": "Payment",
    "bussines_message_type": "Qrcode",
    "creation_date": "2026-09-21T14:53:16.000Z",
    "expire_date":   "2026-10-11T14:53:16.000Z",
    "timestamp":     "2026-09-21T14:53:16.000Z"
  },
  "detail": {
    "ref_num": "8820260325155660",
    "terminal_id": "1",
    "tamount": 100,
    "tmean": "Emchilgeenii-tulbur",
    "url": "https://agent.epayment.mn/api/notify"
  }
}

header#

Бүх талбар заавал, бүгд string. version, bussines_service, bussines_message_type гурав дээрх утгаараа тогтмол. creation_date, expire_date, timestamp нь ISO 8601. institution_id нь тоо биш, string.

detail#

ТалбарТөрөлЗаавалТайлбар
ref_numstring✔Нэхэмжлэхийн дугаар. Давтагдашгүй байна
terminal_idstring | number✔Терминал буюу салбарын дугаар
tamountnumber—Төлөх дүн
tmeanstring—Гүйлгээний утга. Зөвхөн ASCII, зайгүй
urlstring—Таны callback URL. http:// эсвэл https://. Жишээнд EPay-ийн туршилтын /notify бичсэн — бодит ашиглалтад өөрийнхөөрөө соль

🚨 tmean-д кирилл үсэг, зай хэрэглэхгүй#

Заавал мөрдөнө

tmean-д зөвхөн ASCII тэмдэгт, зайгүй бичнэ: латин үсэг, цифр болон - _ . /.

Жишээ
✅ ЗөвEmchilgeenii-tulbur · INV-20260921-001 · Tolbor_9077219
❌ БурууЭмчилгээний төлбөр · Emchilgeenii tulbur · Tolbor №12

Хариу — HTTP 200#

json
{
  "header": { "from_": { "system_owner": "MOF", "...": "..." }, "...": "..." },
  "detail": {
    "ref_num": "8820260325155660",
    "tamount": 100,
    "terminal_id": 1,
    "tmean": "1050022,ST:1;REF:8820260325155660;Emchilgeenii-tulbur",
    "success": "true",
    "message": "Амжилттай бүртгэлээ.",
    "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAg0AAAINCAIAAAAyetvD...",
    "deep_link": [
      { "name": "Khan bank", "description": "Хаан банк",
        "logo": "https://qpay.mn/q/logo/khanbank.png",
        "link": "khanbank://q?qPay_QRcode=00020101021226540014A0000008430001..." },
      { "name": "Socialpay", "descrip": "Socialpay", "logo": "...",
        "link_add": "socialpay-payment://q?qPay_QRcode=00020101021226540014A0000008430001..." }
    ]
  }
}

1. detail.success-ийг шалгана. Утга нь string: "true" эсвэл "false". HTTP 200 ирсэн ч "false" байж болно. "false" үед message-ийг уншина, QR ашиглахгүй.

2. QR-ыг зураг болгон үзүүлэх — detail.qr_code нь base64 PNG:

html
<img src="data:image/png;base64,{{detail.qr_code}}">

3. QR-ыг өөрсдөө зурах — EMV мөрийг detail.deep_link[]-ийн холбоос дахь qPay_QRcode= параметрээс авч URL-decode хийнэ:

text
khanbank://q?qPay_QRcode=<EMV мөр>

Талбарын нэр ихэвчлэн link, SocialPay дээр link_add. Бүх холбоост ижил EMV мөр байна.

4. detail.deep_link нь банк, түрийвчийн жагсаалт — «банкаа сонгох» дэлгэцэд ашиглана.

Callback (EPay → таны сервер)#

Төлбөр хийгдмэгц EPay нь detail.url руу POST-оор JSON body илгээнэ.

json
{
  "crBankbic": "MOFUMNUB",
  "dbBankbic": "CAXBMNUB",
  "craccount": "100900020012",
  "craccountname": "ТӨРИЙН САН",
  "dbaccount": "5027328504",
  "dbaccountname": "МӨНХ-ИРЭЭДҮЙ БОЛД",
  "tmean": "0202 988061376061653 ST:1;REF:8820260325155660;",
  "bank_refnum": "988061376061653",
  "tdate": "2026-09-21 22:54:44",
  "tamount": 100,
  "add_data": "",
  "debt_bankid": "",
  "crbankcode": "",
  "ref_num": "8820260325155660"
}

Талбарууд#

ТалбарТайлбар
ref_numНэхэмжлэх үүсгэхэд өгсөн дугаар. Нэхэмжлэхийг үүгээр таина
tamountТөлөгдсөн дүн
bank_refnumТөлбөрийн давтагдашгүй дугаар. Давхардлыг үүгээр шүүнэ
tdateYYYY-MM-DD HH:mm:ss, Улаанбаатарын цаг (UTC+8)
tmeanГүйлгээний утга. Задлахгүй
crBankbicҮргэлж "MOFUMNUB"
dbBankbicТөлөгчийн банкны BIC (AGMOMNUB Хаан, GLMTMNUB Голомт, CAXBMNUB Хас, STBMMNUB Төрийн)
dbaccount / dbaccountnameТөлөгчийн данс, нэр. Хоосон "" байж болно
craccount / craccountnameТогтмол "100900020012" / "ТӨРИЙН САН"
add_data, debt_bankid, crbankcodeҮргэлж хоосон ""

14 талбар үргэлж бүрэн ирнэ.

Хүлээн авах талын шаардлага#

  • 2xx статус буцаана. Response body нь ямар ч байж болно.
  • 10 секундэд багтана.
  • Давхардлыг bank_refnum-аар шүүнэ. Боловсруулсан бол дахин бүртгэлгүйгээр 200 буцаана.
  • Сүлжээний алдаа, timeout, 5xx, 408, 429 үед EPay 0 сек → 5 сек → 30 сек зайтай, нийт 3 удаа retry хийнэ. Бусад 4xx дээр retry хийхгүй.

Callback ирэхгүй тохиолдол#

  • detail.url өгөөгүй, эсвэл http/https биш
  • detail.success нь "false" байсан
  • expire_date дээр 1 хоног нэмсэн хугацаанаас хойш төлөгдсөн
  • Тест орчинд үүсгэсэн нэхэмжлэх

Алдаа#

НөхцөлHTTPХийх зүйл
X-Api-Key байхгүй эсвэл буруу401Key-гээ шалгана
Request body-гийн бүтэц буруу400Мессежийн дагуу засна
МОФ татгалзсанМОФ-ийн статусМессежийг хэрэглэгчид харуулна
МОФ-д хүрэхгүй байна502Ижил ref_num-аар дахин оролдоно
HTTP 200 + detail.success: "false"200message-ийг уншиж засна

Нэвтрүүлэх дараалал#

  1. Тест орчны key авч dev-agent дээр нэхэмжлэх үүсгэн хариуг шалгана.
  2. Postman цуглуулгын 2-р хүсэлтээр callback URL-ээ шалгана.
  3. Прод key авна.
  4. Прод дээр 100₮-ийн туршилтын нэхэмжлэх үүсгэн төлж, callback ирснийг баталгаажуулна.
  5. Бодит ашиглалтад шилжинэ.