Танилцуулга / Архитектур

Архитектур

PayGrid системийн ерөнхий зураг, сервисийн жагсаалт, network zone, data flow болон Estonia A2A canonical flow-ийг 17 алхамаар. Энэ нь PLAN/04-ARCHITECTURE.md ба PLAN/03-ESTONIA-MODEL.md баримтуудаас гаргасан.

1. Системийн тойм

PayGrid нь нэг hostname (paygrid.mn)-ын дор, олон давхаргат gateway-ийн ард Go дээр бичигдсэн микросервисүүдээс бүрдэнэ. Үндсэн оролт нь HTTPS public endpoint, гадаад зуучлал нь Mongolbank Switch-руу болон X-Road (rp.gerege.mn) сүлжээгээр тус тусдаа явна.

2. Сервисийн жагсаалт

Phase 1-аас зөвхөн paygrid-api, paygrid-clearing, paygrid-mock-bank, paygrid-mock-wallet-аар single-host docker-compose-аар paygrid.mn server дээр амьдарч байна. Phase 2-аас FRM, audit-export, e-ID client services-уудаар нэмэгдэнэ.

3. Network zones

Дөрвөн тусгаарласан хэсэг: гадаад internet-ээс зөвхөн Zone A-руу хүрнэ; чухал DB / HSM / settlement Zone B-д; e-ID Mongolia Zone C-д (X-Road), Mongolbank Switch Zone D-д (тусдаа leased line) холбогдоно.

Strict security group rules zone хооронд. Zone A-аас DB-руу шууд хандах эрх байхгүй — paygrid-api → Zone B service mesh-аар л.

4. Data flow — гол хэрэглээний жишээ

Хэтэвчний хэрэглэгч банкны данснаасаа cafemonkey@gerege merchant-руу 25,000 ₮ шилжүүлэх жишээгээр.

1. Хэтэвч PSP → paygrid-api

   HTTPS public mTLS. POST /v1/payments/sepa-credit-transfers — Berlin Group NextGenPSD2 + PayGrid extensions (binding_jws, creditorAlias, frm_score).

2. paygrid-api gateway

   JWT шалгах, idempotency-key check, AliasService → creditor alias resolve, RoutingEngine → debtor BIC inferred from IBAN, FRMEngine score (velocity, sanctions, PEP, AML).

3. FRM хатуу block эсвэл pass

   Если score > threshold → 422 + alert ops + audit. Бусад тохиолдолд → bank PISP API forward.

4. Bank PISP API (NextGenPSD2)

   Khan/Golomt/TDB-аар https://bank.mn/psd2/v1/payments/sepa-credit-transfers. mTLS + bank's PSU access token. scaRedirect URL буцна.

5. Bank app SCA via e-ID Mongolia

   Хэрэглэгч bank app-руу Universal Link-ээр шилжинэ. Bank ↔ rp.gerege.mn шууд X-Road. PayGrid involved биш. PIN2 confirm дотор Threshold ECDSA-2P-аар sign.

6. Bank executes

   Bank debits debtor account, builds ISO 20022 pacs.008 message with attestation в SplmtryData.

7. paygrid-clearing pacs.008 хүлээж авна

   Schema validate → routing lookup (creditor IBAN → creditor PSP) → ledger_entries INSERT → forward pacs.008 to creditor PSP → wait pacs.002 ACSC → emit pacs.002 to debtor bank → webhook to PSP.

8. Хэтэвч PSP webhook

   HMAC-SHA256 signed. Хэтэвч хэрэглэгчийн balance-ыг өөрийн ledger дээр credit. Хэрэглэгч "Paid" дэлгэц харна.

9. Async EOD settlement

   paygrid-clearing цаг тутамд net position-ыг pair бүр-аар тооцож, DNS batch-ыг Mongolbank Switch-руу submit. Switch-аас Mongolbank-аар RTGS-аар final settle.

5. Component-уудын үүрэг

paygrid-api

• Berlin Group NextGenPSD2 server endpoint бүгд
• PayGrid extensions: /v1/aliases/*, /v1/psp/*, /v1/qr/*
• Idempotency key handling (Redis-backed, 24ц TTL)
• Authentication: mTLS pinning + JWT (ES256 / RS256) + per-participant rate limit
• OpenAPI 3.x spec auto-generated (oapi-codegen)

Alias Service (DICT)

• Operations: register, resolve, revoke, verify (Confirmation of Payee)
• Validation: PSP attestation JWS required, alias uniqueness within type
• Cache: Redis 5-минут TTL
• Audit: бүх operation hash-chained log-аар

Routing Engine

• BIC → participant lookup; IBAN bank prefix → BIC inference
• Same PSP (intra) → bypass PayGrid; different PSP → PayGrid clearing; cross-network → forward to bank

FRM Engine

• Velocity (per-account, per-IBAN, per-IP)
• Geo anomaly detection
• Sanctions screening (OFAC, UN, EU, Mongolbank list)
• PEP + AML structuring patterns
• Action: PASS SOFT_CHALLENGE HARD_BLOCK INVESTIGATE

Settlement Engine (paygrid-clearing)

Дэлгэрэнгүй Settlement хуудсанд. Гол үүрэг нь pacs.008 routing, bilateral nostro position tracking, hourly + EOD batch generation, Mongolbank Switch DNS submit, reconciliation.

e-ID Mongolia Client

X-Road client subsystem MN/COM/<reg>/PAYGRID-CLIENT, зөвхөн PayGrid-ийн өөрийн service-side signing (батч instruction, audit export, incident report)-аар. Хэрэглэгчийн SCA-аас оролцохгүй. Дэлгэрэнгүй →

QR Service

EMVCo TLV encoder/decoder, CRC-16/CCITT-FALSE checksum, PayGrid Tag 81 mn.paygrid:// URI, PNG/SVG/EPS image renderer. QR Switch дэлгэрэнгүй →

6. Estonia canonical flow — 17 алхам

PayGrid-ыг build хийх template нь Estonia банкуудын Smart-ID-аар A2A төлбөр шийддэг production-grade flow юм. PLAN/03-ESTONIA-MODEL.md-аас verbatim бичигдсэн. Доор тоймлосон 17 алхамыг Mongol context-руу шилжүүлэхэд зөвхөн 5 substitution л хэрэгтэй: SEB → Khan/Golomt/TDB, Smart-ID → e-ID Mongolia, TIPS → Mongolbank Switch DNS, EUR → MNT, m.seb.ee → khanbank.mn гэх мэт.

1. User initiates in RP

   Хэрэглэгч хэтэвч/Bolt-ийн төстэй апп-аас "Pay with Khan Bank" товч дарна.

2. PSP creates PISP request

   RP backend → PSP (Trustly equivalent — энэ тохиолдолд хэтэвч өөрөө) → bank NextGenPSD2 PISP API.

3. Universal Link to Bank App

   Bank scaRedirect URL-ыг буцаана; iOS/Android Universal Link/App Link-аар bank-ы native app нээгдэнэ.

4. Bank app resolves payment

   Bank app-аар paymentId-аар backend-аас бүх details татна.

5. Authentication (skip if cached)

   Cached биш бол e-ID Mongolia /auth/initiate X-Road call.

6. Bank shows payment confirmation

   Дүн, payee, IBAN, reference харагдах screen.

7. Bank computes Dynamic Linking hash

   SHA-512 over (amount, currency, creditor_name, creditor_iban, reference, end_to_end_id) — PSD2 RTS Article 5.

8. Bank calls e-ID Mongolia for SIGN

   X-Road POST /sign/initiate with document_hash + 200-аас доош дэлгэрэнгүй текст + verificationCodeChoice interaction.

9. e-ID Mongolia push to user phone

   APNs/FCM шифрлэгдсэн notification — sessionID, displayText, 3 verification code (1 нь зөв).

10. User enters PIN2

    PIN2-аар device-side key share decrypt; threshold ECDSA-2P 1-р round-аар m_M phone-аас, 2-р round-аас m_S server-аас; combine: signature = m_S × m_M (mod n).

11. Bank long-polls e-ID session

    GET /session/{id}?timeoutMs=120000 — state COMPLETE болоход буцна. Result: signature CMS, cert chain, TSA token.

12. Bank validates signature

    ECDSA verify; cert chain to e-ID Mongolia trust root; QcStatement check; OCSP fresh; documentNumber matches account owner.

13. Bank executes via PayGrid

    Bank constructs pacs.008 with SCA attestation in SplmtryData → POST to paygrid-clearing.

14. PayGrid clearing

    Validate, ledger_entries, forward pacs.008 to creditor PSP, await pacs.002 ACSC, return pacs.002 to debtor bank.

15. PayGrid webhook to PSP

    HMAC-SHA256 signed. Хэтэвч хэрэглэгчид push notification.

16. Bank app returns to RP via Universal Link

    iOS/Android OS routes back to original wallet/Bolt app.

17. RP confirms to user

    "✓ Payment confirmed — 25,000 ₮ paid via Khan Bank".

7. Deployment topology

Phase 1 — Sandbox (одоо)

• Single Linux server (Ubuntu 24.04), 38.180.254.229
• Docker Compose stack: postgres-16, redis-7, paygrid-api, paygrid-clearing, paygrid-mock-bank, paygrid-mock-wallet
• nginx host-аас TLS termination + Let's Encrypt
• HSM mode = SoftHSM
• e-ID = DEMO_MODE (in-process stub)
• Switch = mock (log + return success)

Phase 2 — Multi-host pilot

• 2+ servers (Улаанбаатар primary, Эрдэнэт secondary)
• Synchronous PostgreSQL replication
• WireGuard mesh; Cloud HSM integration
• Per-server Prometheus + Loki monitoring

Phase 3 — Production K8s

• Kubernetes cluster + Helm charts
• 3 paygrid-api pods, 2 clearing, 1 FRM (HPA scaling)
• Postgres primary + 2 replicas (32GB) + service mesh option
• Active-active HSM cluster (Thales Luna or AWS CloudHSM)
• Multi-region (UB + Erdenet); DDoS edge

8. Scaling, reliability targets

Эх сурвалж: PLAN/04-ARCHITECTURE.md, PLAN/03-ESTONIA-MODEL.md. Дараагийн хуудас: API лавлагаа →