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

SmartPay Agent API нь терминал (POS, касс, апп) болон EPay төлбөрийн шилжүүлэгчийн хооронд байрлах хаалга юм. Тэрээр хоёр ажил хийнэ: нэхэмжлэх/QR-ын REST үйлчилгээ үзүүлэх, мөн банкнаас төлбөр орсон агшинд яг тухайн терминал руу Socket.IO-оор шууд мэдэгдэл түлхэх.

Тойм#

Сервис нь дараах хоёр сувгийг зэрэг барина:

Хамгийн чухал ойлголт: төлбөр орсныг та лавлаж мэдэхгүй, харин мэдэгдэл хүлээж авна. Терминал нь Socket.IO холболтоо байнга нээлттэй барьж notify event-ийг сонсох ёстой.

Гүйлгээний бүтэн урсгал#

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

Сервис амьд эсэхийг шалгах хамгийн хурдан арга:

curl https://agent.epayment.mn/api
# {"message":"Hello API"}

Нэвтрэлт#

Танд EPay-ээс нэг client key олгогдоно. Түүнийгээ хоёр өөр газар өөр нэрээр дамжуулна:

Endpoint тус бүрийн шаардлага:

WebSocket — холболт үүсгэх#

Socket.IO v4 ашиглана (серверийнхтэй үндсэн хувилбар таарах ёстой). Үндсэн namespace /. Холбогдохдоо handshake-ийн auth-д apiKey болон terminalId хоёрыг өгнө.

Node.js / React Native

import { io } from 'socket.io-client'; // ^4

const craccount  = '100900020012'; // танай хүлээн авах данс
const terminalNo = '1';            // терминалын дугаар (зөвхөн цифр)

const socket = io('https://agent.epayment.mn', {
  auth: {
    apiKey: process.env.EPAY_CLIENT_KEY,
    terminalId: `${craccount}-${terminalNo}`,
  },
  // transports-ыг ЗААВАЛ default-аар нь үлдээ — доорх анхааруулгыг үз
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 10000,
});

socket.on('connect', () => {
  console.log('holbogdloo', socket.id, socket.io.engine.transport.name);
});

socket.on('notify', ({ body, wallResponse }) => {
  // body        — банкнаас ирсэн гүйлгээний мэдээлэл
  // wallResponse — EPay switch рүү дамжуулсны хариу (алдаатай ч байж болно)
  console.log('tolbor orloo', body.tamount, body.bank_refnum);
});

socket.on('connect_error', (err) => console.error('connect_error', err.message));
socket.on('disconnect', (reason) => console.warn('salsan', reason));

Хөтөч

<script src="https://cdn.socket.io/4.8.1/socket.io.min.js"></script>
<script>
  const socket = io('https://agent.epayment.mn', {
    auth: { apiKey: 'CLIENT_KEY', terminalId: '100900020012-1' },
  });
  socket.on('notify', (data) => console.log('notify', data));
</script>

Room нэршил#

Сервер нь холбогдсон socket бүрийг terminalId-тэй яг ижил нэртэй room-д оруулна. Мэдэгдэл ирэхэд дараах томьёогоор room-ыг олж түлхэнэ:

room = "<craccount>-<terminalId>"
        │            └── notify биетийн tmean доторх ST: -ийн ард байгаа ЦИФРҮҮД
        └── notify биетийн craccount талбар (хүлээн авагчийн данс)

Жишээ:  craccount = 100900020012
        tmean     = "QPAY 915023802387369 ST:1,REF:0000093;"
        →  room   = "100900020012-1"

Тиймээс таны терминал auth.terminalId-даа яг энэ мөрийг дамжуулах ёстой. Ганц тэмдэгт зөрвөл (жишээ нь ST:01 гэж бодоод ...-01 гэж холбогдвол) мэдэгдэл огт хүрэхгүй бөгөөд ямар ч алдаа гарахгүй.

notify event#

Терминал зөвхөн нэг event сонсоно — notify. Payload нь хоёр хэсэгтэй:

{
  "body": {
    "crBankbic": "MOFUMNUB",
    "dbBankbic": "KHANMNUB",
    "craccount": "100900020012",
    "dbaccount": "5027328504",
    "craccountname": "ТӨРИЙН САН",
    "dbaccountname": "БАТ",
    "tmean": "QPAY 915023802387369 ST:1,REF:0000093;",
    "bank_refnum": "001240573605",
    "tdate": "2026-09-08 11:42:07",
    "tamount": 1000,
    "add_data": "",
    "debt_bankid": "",
    "crbankcode": "",
    "ref_num": "0000093"
  },
  "wallResponse": {
    "success": true,
    "message": "Received",
    "switchResponse": { }
  }
}

Заавал мөрдөх дүрэм#

1. terminalId заавал. Түүнгүйгээр холбогдвол сервер холболтыг тэр дор нь таслана (disconnect).
2. Холболтоо байнга нээлттэй бай. Мэдэгдэл ирэх агшинд тухайн room-д нэг ч socket байхгүй бол сервер юу ч хийхгүй — мэдэгдэл алга болно. Дараалал, дахин илгээлт, хадгалалт байхгүй.
3. Reconnect-ээ асаа. Socket.IO-гийн үндсэн reconnect-ыг унтраахгүй. Сүлжээ тасарсан богино хугацаанд орсон төлбөр буцаж ирэхгүй тул (2-р дүрэм) сэргэсний дараа GET /check-ээр нөхөж тулгах нь зүйтэй.
4. Нэг room-д олон socket байж болно. Хоёр төхөөрөмж ижил terminalId-гаар холбогдвол хоёуланд нь мэдэгдэл очно. Давхардлаас сэргийлэхийн тулд bank_refnum-аар дедупликац хий.
5. Идэмхий бус (idempotent) боловсруул. Ижил bank_refnum дахин ирвэл хоёр дахь баримт бүү хэвлэ.

REST endpoint-ууд#

Health check. Сервис амьд эсэхийг шалгана.

curl https://agent.epayment.mn/api
# 200  {"message":"Hello API"}

МОФ (Төрийн сан)-д нэхэмжлэх үүсгэнэ. Agent API нь биетийг шалгаад МОФ-ийн /epayment руу дамжуулж, хариуг нь өөрчлөхгүйгээр буцаана.

Хүсэлт

{
  "header": {
    "from_": {
      "system_owner":     "…",
      "institution_id":   "…",
      "institution_name": "…"
    },
    "to_": {
      "system_owner":     "…",
      "institution_id":   "…",
      "institution_name": "…"
    },
    "version":               "…",
    "bussines_service":      "…",
    "bussines_message_type": "…",
    "creation_date":         "…",
    "expire_date":           "…",
    "timestamp":             "…"
  },
  "detail": {
    "ref_num":     "0000093",
    "terminal_id": "1",
    "tamount":     1000,
    "tmean":       "…",
    "url":         "…"
  }
}

Хариу

МОФ-ийн хариу тэр чигтээ буцна. Гол талбарууд нь detail.qr_code (QR-ын EMVCo payload) болон detail.deep_link (банкны аппуудын жагсаалт).

МОФ форматын EMVCo QR-ын payload-ыг локалаар үүсгэнэ. Гадагш ямар ч дуудлага хийхгүй, ямар ч нэхэмжлэх бүртгэхгүй — зөвхөн мөр эвлүүлж CRC-г нь бодно.

curl -X POST https://agent.epayment.mn/api/generate-qr \
  -H 'Content-Type: application/json' \
  -d '{
    "amount":         "1000.00",
    "merchantName":   "TEST MERCHANT",
    "billNumber":     "BILL-1",
    "storeLabel":     "STORE-1",
    "referenceLabel": "REF-1",
    "registerNO":     "1234567"
  }'

{
  "qrCode": "00020101021226540014A00000084300010108MOFUMNUB0220MN63009001009000000052049399530349654071000.005502025802MN5913TEST MERCHANT6011Ulaanbaatar62540106BILL-10307STORE-10505REF-1060712345670809MOFQRCODE7403GOV8002036304A000"
}

Үүсэх QR-ын тогтмол утгууд

tpay.gov.mn дээрх нэхэмжлэхийн төлвийг лавлана. Мэдэгдэл алдагдсан үед нөхөн тулгах зориулалттай.

curl -H 'X-Api-Key: CLIENT_KEY' \
  'https://agent.epayment.mn/api/check?ref=0000093'

Боломжит хариунууд

Банк / МОФ талаас дуудагддаг callback. Терминалын програм үүнийг дуудахгүй — гэхдээ юу болж байгааг ойлгоход хэрэгтэй тул баримтжуулав.

Хүсэлт хүлээж авмагц сервер дараах гурван зүйлийг хийнэ:

1. tmean-ээс ST:<цифр>-ийг салгаж терминалыг тодорхойлно.
2. EPay-ийн epay-to-customer-wall руу дамжуулж switch-д «paid» бүртгүүлнэ.
3. <craccount>-<terminalId> room руу notify event түлхэнэ.

Түгээмэл алдаа#

Оношилгоо#

1. Сервис амьд эсэх

curl -i https://agent.epayment.mn/api
# 200 {"message":"Hello API"} → сервис амьд

2. Socket.IO хүрч байгаа эсэх

curl 'https://agent.epayment.mn/socket.io/?EIO=4&transport=polling'
# 0{"sid":"…","upgrades":["websocket"],"pingInterval":25000,…}

Ийм хариу ирвэл сүлжээ, Cloudflare, ingress бүгд журамтай — асуудал таны клиентийн тохиргоонд байна (ихэвчлэн transports эсвэл URL).

3. Холбогдсон боловч мэдэгдэл ирэхгүй байна

Дараах дарааллаар шалга:

1. socket.connected === true мөн үү? disconnect event-ээ лог руу бич.
2. Холбогдохдоо өгсөн terminalId-гаа хэвлэ. Тэр нь <craccount>-<ST-ийн цифр> хэлбэртэй байна уу?
3. Бодит гүйлгээний tmean-ийг банкнаас/МОФ-оос ав. Түүн доторх ST:-ийн ард байгаа цифр таны terminalId-ийн сүүлийн хэсэгтэй яг таарч байна уу?
4. Таарахгүй байвал room зөрсөн байна — terminalId-гаа засаад дахин холбогд.
5. Бүгд таарч байгаад ирэхгүй бол EPay-д хандаж, тухайн bank_refnum-ыг хэлж лог шалгуулна.

Нэвтрүүлэх өмнөх шалгалт#

• Socket.IO клиент v4 эсэх.
• transports заагаагүй (default) эсэх.
• Socket.IO URL-д /api байхгүй эсэх.
• terminalId нь <craccount>-<terminalId> хэлбэртэй, дансны дугаар нь бодитой эсэх.
• Reconnect асаалттай, disconnect/connect_error логлогдож байгаа эсэх.
• bank_refnum-аар дедупликац хийдэг эсэх.
• Апп нээгдмэгц socket холбогдож, хаагдтал нээлттэй үлддэг эсэх.
• Client key нь тохиргооноос ирдэг, эх кодод хатуу бичигдээгүй эсэх.
• Эхлээд dev-agent.epayment.mn дээр туршсан эсэх.