Sandbox орчин тохируулах

Sandbox credential авч, эхний дуудлагаа туршиж, production руу шилжихэд бэлдэх алхамууд.

Production-д гаргахаас өмнө бүх интеграцийг sandbox орчинд бүрэн туршихыг зөвлөж байна. Sandbox нь production-той ижил API гэрээтэй (endpoint, талбар, алдааны код) боловч жинхэнэ төлбөр хийгдэхгүй, туршилтын өгөгдөл дээр ажиллана.

Орчны ялгаа, base URL-уудын талаар Орчин хуудаснаас дэлгэрэнгүй уншина уу.

1. Sandbox credential авах

Sandbox-д хандах X-API-Key-г gov-pay өөрөө олгоно — partner self-service бүртгэл байхгүй.

gov-pay багтай холбогдож sandbox партнёр болохоо мэдэгдэнэ.
Танд тусдаа sandbox X-API-Key олгоно (production key-ээс өөр, солилцож болохгүй).
Хамт туршилтын утгууд — жишээ ТТД (ttd), улсын дугаар (vehicle), татварын лавлах (taxRef) — өгнө. Эдгээр утга нь sandbox-ийн туршилтын өгөгдөлтэй тохирно.

Sandbox key болон production key-г хооронд нь холиж болохгүй. Sandbox key-г production base URL руу (эсвэл эсрэгээр) илгээвэл 401 буцна. Дэлгэрэнгүйг Нэвтрэлт ба түлхүүр хэсгээс үзнэ үү.

2. Sandbox base URL

Бүх sandbox дуудлага дараах үндсэн хаягийг ашиглана (бүх зам /api/v1 угтвартай):

https://sandbox-tts.qpay.mn/api/v1

Локал хөгжүүлэлтэд http://localhost:5600/api/v1-г ашиглаж болно. Production-ийн хаяг (https://tts.qpay.mn/api/v1)-г зөвхөн чек дууссаны дараа сольж тавина.

3. Эхний дуудлага хийх

Sandbox key болон gov-pay-ээс өгсөн туршилтын ТТД-г ашиглан нэхэмжлэлийн жагсаалтыг татаж үзнэ. GET /invoices нь яг нэг шүүлтүүр шаарддаг (ttd, vehicle, эсвэл taxRef) — хоёр ба түүнээс олныг өгвөл 400 буцна.

curl -H "X-API-Key: $SANDBOX_API_KEY" \
  "https://sandbox-tts.qpay.mn/api/v1/invoices?ttd=TEST_TTD"

Амжилттай бол 200 статустай, нэхэмжлэлийн жагсаалт болон нийт дүн буцна. total нь нэхэмжлэлүүдийн дүнгийн нийлбэр (төгрөгөөр), тоо ширхэг биш:

{
  "invoices": [
    {
      "id": "5f8d0a3e-1b2c-4d6e-8a9f-0c1d2e3f4a5b",
      "description": "2024 оны орлогын татвар",
      "amount": 150000,
      "status": "open",
      "dueDate": null,
      "issuedAt": null,
      "vehicleNo": null,
      "payer": { "register": "6129722", "name": "Лидер вишн групп" },
      "payee": { "id": "6097898", "name": "ТАТВАРЫН ЕРӨНХИЙ ГАЗАР" }
    }
  ],
  "total": 150000
}

Хариу дахь id нь gov-pay системийн дотоод UUID. Дараагийн алхамд төлбөр үүсгэхдээ (POST /payments, body { "invoiceId": "<id>" }) яг энэ id-г ашиглана — refNum-г биш. Төлбөрийн урсгалыг Төлбөр хэсгээс үзнэ үү.

Холболтоо шалгах

Хэрэв X-API-Key дамжуулалт ажиллаж байгаа эсэхэд эргэлзвэл, auth шаардахгүй health endpoint-оор сервис амьд эсэхийг шалгаж болно:

curl "https://sandbox-tts.qpay.mn/api/v1/health/ready"

{ "status": "ok", "db": "up", "timestamp": "2026-06-29T00:00:00.000Z" }

Дараа нь дээрх GET /invoices дуудлагыг гүйцэтгэ. Хариу 401 ирвэл key буруу/байхгүй, 403 ирвэл партнёр идэвхгүй гэсэн үг. Бүх кодын утгыг Алдааны кодууд хэсгээс үзнэ үү.

4. Туршихыг зөвлөх урсгалууд

Sandbox-д дараах гол урсгалуудыг бүрэн туршаарай:

Урсгал	Endpoint
Нэхэмжлэл хайх (3 шүүлтүүр тус бүр)	`GET /invoices?ttd=` \| `?vehicle=` \| `?taxRef=`
Нэхэмжлэлийн дэлгэрэнгүй	`GET /invoices/{id}`
Төлбөр үүсгэх + QR авах	`POST /payments`
Төлбөрийн статус хянах	`GET /payments/{id}`
Webhook бүртгэх + гарын үсэг шалгах	`POST /webhooks`

Идемпотентность болон давтан хүсэлтийг туршихын тулд POST /payments-д X-Idempotency-Key header-ийг өөрийн хүсэлтийн UUID-ээр дамжуулж үзээрэй. Webhook-ийн гарын үсгийг хэрхэн баталгаажуулахыг Гарын үсэг шалгах, webhook-ийн ерөнхий урсгалыг Webhook хэсгээс үзнэ үү.

5. Production руу шилжихийн өмнө шалгах зүйлс

Sandbox-д амжилттай туршсаны дараа production руу шилжихийн өмнө дараахыг баталгаажуул:

Base URL солих: бүх дуудлага https://tts.qpay.mn/api/v1-г ашиглаж байгаа эсэх (sandbox хаяг хаана ч үлдэхгүй байх).
Production key: gov-pay-ээс авсан тусдаа production X-API-Key-г аюулгүй (env/secret store) хадгалсан, sandbox key-г кодоос устгасан байх.
Алдааны код боловсруулалт: 400 (буруу шүүлтүүр/UUID), 401/403 (auth), 404 (олдсонгүй), 422 (төлбөр амжилтгүй), 429 (rate limit), 5xx (төрийн систем) бүгдийг зөв барьдаг байх. Алдааны кодууд-г үз.
Rate limit: API key тус бүрд 5/сек, 60/мин, 1000/цаг хязгаарт багтаж, 429 ирэхэд дахин оролдох (retry/backoff) логиктой байх.
Идемпотентность: POST /payments бүрд давтагдашгүй X-Idempotency-Key (хүсэлтийн UUID) дамжуулж, давхар төлбөрөөс хамгаалсан байх.
Webhook гарын үсэг: X-GovPay-Signature (HMAC-SHA256, таны secret)-г заавал шалгадаг, 5 секундын дотор хурдан 2xx буцаадаг, payment id-аар давхардлыг шүүдэг (idempotent) байх.
source талбар: PUBLIC хариунд source буцаагдахгүй тул түүнд найдсан логик байхгүй эсэх.

Production credential нь жинхэнэ төлбөрийн гүйлгээ үүсгэдэг. Бүх урсгалаа sandbox-д бүрэн туршаагүй бол production key хүсэхгүй байхыг зөвлөж байна.