Алдааны код¶
Энэ хуудсаар: татгалзсан хариуг хэрхэн уншиж, аль кодонд юу хийх, аль хүсэлтийг дахин илгээж болохыг шийднэ.
Лавлах хуудас — эхнээс нь уншихгүй, кодоор нь хайна (Ctrl+F). Хэрэгтэй зүйл: таны backend-ийн HTTP client.
Код бүр модулийн бодит кодоос (refuse, oauthError, intent/refund/тооцооны failure_code) авсан. Шинэ код зөвхөн
нэмэгдэнэ — мэдэхгүй кодыг HTTP статусаар нь (4xx — хүсэлтээ засах, 5xx — дахин оролдох) шийд.
Хариуны хэлбэр¶
Платформ хоёр хэлбэрээр татгалзана; SDK-ууд (Node GeregeError, Go *miniapp.APIError) хоёуланг нь уншина.
| Хэлбэр | Хаана | Жишээ |
|---|---|---|
| OAuth (RFC 6749 / 6750) | client болон token-ы нэвтрэлт (invalid_client, invalid_token, insufficient_scope) ба POST /oauth/token-ийн бүх татгалзал |
{"error": "invalid_grant", "error_description": "…"} |
| Модулийн | бусад бүх татгалзал | {"error": "<Монгол мессеж>", "code": "<код>", …нэмэлт} |
| Энгийн | 404 (олдсонгүй, өөр апп эсвэл өөр орчных), 429 (rate limit), хүлээгээгүй 500 |
{"error": "not found"} — code байхгүй |
{
"error": "Терминалд өөр нээлттэй төлбөр байна",
"code": "terminal_busy",
"payment_intent": "pi_T3rm1nalVend0000000000Ab"
}
- Програмаар
code-оор шийд.errorнь хүнд харуулж болох Монгол мессеж — түүгээр хэзээ ч салаалахгүй (текст өөрчлөгдөж болно). - Нэмэлт талбарууд:
details(validation_error-ийн[{path, message}]),payment_intent(тухайн үеийн intent, эсвэлterminal_busy-д нээлттэй intent-ийн id),status(not_cancelable,not_claimable),retry_after(already_claimed),scopes,app(consent_required). code-гүй хариуг SDKhttp_<status>кодтой болгоно (http_404,http_429,http_500).- OAuth хэлбэрийн
401-дWWW-Authenticateтолгой ирнэ (Bearer error="invalid_token",Bearer error="insufficient_scope", scope="payments").
Дахин оролдох уу. Сүлжээний алдаа, 429, 5xx ба 202 (явагдаж байна — дахин унш) — ижил
Idempotency-Key-ээр дахин илгээх нь аюулгүй (SDK-д err.retryable, apiErr.Retryable()). 4xx-ийг өөрчлөлтгүй
давтахад үр дүн өөрчлөгдөхгүй — эхлээд шалтгааныг нь засна. Доорх хүснэгтийн «Давтах» багана үүнийг код бүрт хэлнэ.
Нэвтрэлт (OAuth)¶
| HTTP | code | Хэзээ | Юу хийх | Давтах |
|---|---|---|---|---|
| 401 | invalid_client |
client id/secret буруу; түлхүүр хүчингүй болсон, хугацаа нь дууссан, солигдоод давхцал нь өнгөрсөн (ялгагдахгүй); Basic шаардсан route-д Basic алга (терминал, дэд худалдагч, тайлан, endpoint, event); апп suspended/disabled; батлагдаагүй апп-ын live түлхүүр |
credential, орчноо шалгах; түлхүүр ба апп-ын төлвийг консолоос | үгүй |
| 401 | invalid_token |
хүний access token алга, буруу, хугацаа дууссан, хүчингүй | refresh, эсвэл апп-ыг дахин нээлгэх | refresh-ийн дараа |
| 403 | insufficient_scope |
хүний token эсвэл апп-д payments consent scope алга (WWW-Authenticate: Bearer …); эсвэл API түлхүүрт route-ийн scope алга — required_scope нэрлэнэ (WWW-Authenticate: Basic …). 1.13.0-ээс OAuth-ын талбаруудын хажууд модулийн code: "insufficient_scope" бас ирнэ |
consent: manifest-д payments нэмж review-д; түлхүүр: тэр scope-той шинэ түлхүүр |
үгүй |
| 403 | ip_not_allowed |
түлхүүрийн IP allowlist-д энэ хаяг алга (ip) — OAuth хэлбэртэй |
allowlist-ээ засах | үгүй |
| 400 | invalid_request |
token: body уншигдсангүй, grant_type алга, Basic ба body-ийн credential давхар |
хүсэлтээ засах | үгүй |
| 400 | unsupported_grant_type |
grant_type нь authorization_code (launch_code) эсвэл refresh_token биш |
үгүй | |
| 400 | invalid_grant |
launch code / refresh token буруу, хугацаа дууссан, ашиглагдсан, өөр апп-ынх. Ашиглагдсан refresh token-ыг дахин илгээвэл бүх гинж хүчингүй | шинэ нээлт | үгүй |
| 500 | server_error |
платформын алдаа (token endpoint, token шалгах үед) | хүлээгээд дахин | тийм |
Дэлгэрэнгүй: Mini app-ын нээлт ба token; түлхүүрийн консолын кодууд — доорх «Түлхүүр ба scope».
Хүсэлт ба idempotency¶
| HTTP | code | Хэзээ | Юу хийх | Давтах |
|---|---|---|---|---|
| 400 | invalid_request |
body уншигдсангүй — JSON биш, хэт том, route-ийн авдаггүй талбартай | хүсэлтээ засах | үгүй |
| 400 | validation_error |
талбар буруу; details[].path нь аль талбар (amount, description, expires_in, return_url, terminal_id, min_age, capture_within, account …). Апп-ын операторын max_amount-аас их дүн ч энд (path: "amount") |
details-ийг уншаад засах |
үгүй |
| 400 | idempotency_key_required |
Idempotency-Key алга, эсвэл 1–128 хэвлэгдэх ASCII (зайгүй) биш |
key нэмэх | үгүй |
| 409 | idempotency_conflict |
key өмнө нь өөр body-той (хүний хувьд өөр данстай) ашиглагдсан | шинэ үйлдэлд шинэ key; давталт бол яг ижил body | үгүй |
| 400 | invalid_status · invalid_cursor · invalid_limit |
жагсаалтын status, after/cursor, limit (1–100) буруу |
параметрээ засах | үгүй |
| 404 | — (http_404) |
объект алга, эсвэл өөр апп-ын / өөр орчных (test түлхүүрээр live intent) | id ба түлхүүрийн орчноо шалгах | үгүй |
| 429 | — (http_429) |
rate limit (Хязгаар) | backoff (жишээ нь 1, 2, 4 … секунд) | тийм |
| 500 | — (http_500) |
платформын хүлээгээгүй алдаа | ижил Idempotency-Key-ээр |
тийм |
Idempotency-ийн дүрэм: API-ийн нийтлэг дүрэм.
Payment intent¶
POST /payment-intents, GET …, …/capture, …/cancel, …/unclaim. Intent-ийн төлөв ба шилжилт:
Payment intent.
| HTTP | code | Хэзээ | Юу хийх | Давтах |
|---|---|---|---|---|
| 400 | presentment_required |
client credential (Basic)-аар presentment-гүй эсвэл app intent үүсгэх гэсэн |
qr · redirect · terminal; app intent-ийг хүний token-оор |
үгүй |
| 400 | description_not_allowed |
description-д вэб хаяг, имэйл хаяг эсвэл утасны дугаар (details аль нь болохыг нэрлэнэ) — хүн үүнийг төлөх цонхонд Face ID-ийн өмнө уншина (1.13.0) |
захиалгын товчийг бич; өөрийн дугаараа reference-д |
үгүй |
| 400 | validation_error (path: "presentment") |
хүний token-оор qr/redirect/terminal үүсгэх гэсэн |
claimless intent-ийг client credential-аар | үгүй |
| 503 | payments_unavailable |
live: энэ суулгацад core banking идэвхгүй | дараа | тийм |
| 409 | payouts_not_configured |
live: апп-ын payout данс тохируулагдаагүй, эсвэл дэд худалдагчийн payout-ыг эзэмшигч нь батлаагүй | оператортой холбогдох / payout холболт | үгүй |
| 503 | pay_url_unavailable |
суулгац төлбөрийн холбоос, терминал үүсгэх боломжгүй (нийтийн хаяг тохируулаагүй) | оператор | тийм (хожим) |
| 409 | terminal_busy |
терминалд энэ орчинд claim хийгдээгүй нээлттэй intent байна — payment_intent нь түүний id. Unclaim-д: терминал хооронд нь шинэ сагс нээсэн |
тэр intent-ийг cancel хийгээд дахин |
цуцалсны дараа |
| 409 | terminal_disabled · sub_merchant_disabled |
идэвхгүй терминал / дэд худалдагч | PATCH … {status: "active"} |
үгүй |
| 409 | agreement_required |
live, go-live-ийн дүрэм асаалттай (1.14.0): байгууллага хүчин төгөлдөр худалдагчийн гэрээнд eID-ээр гарын үсэг зураагүй | консол → Гэрээ | гарын үсэг зурсны дараа |
| 409 | business_profile_required · business_profile_rejected · business_profile_changed |
live, дүрэм асаалттай: бизнесийн профайл батлагдаагүй, татгалзсан, эсвэл хуулийн нэр/регистр батлагдснаас өөр болсон | консол → Бизнесийн профайл | батлагдсаны дараа |
| 409 | business_restricted |
live: оператор байгууллагын шинэ live төлбөрийг түр зогсоосон (буцаалт, capture, тооцоо явсаар) | оператортой холбогдох | сэргээсний дараа |
| 409 | business_limit_exceeded |
live: tier-ийн хязгаар — limit нь per_payment (нэг intent) эсвэл daily (Улаанбаатарын өдөрт үүсгэсэн live intent, нээлттэй нь ч), max, used |
бага дүн / маргааш / консолоос хязгаар нэмэх хүсэлт | хязгаар нэмэгдсэний дараа |
| 409 | not_capturable |
зөвхөн manual + requires_capture intent-ийг capture хийнэ (payment_intent хавсарна) |
payment_intent.status-ыг уншаад шийд |
үгүй |
| 409 | expired |
capture хийх хугацаа (capture_before) өнгөрсөн — мөнгө хүнд буцсан (payment_intent хавсарна) |
захиалгаа хаах | үгүй |
| 422 | payment_failed |
ledger capture-ийг татгалзсан; барьцаа суллагдана (payment_intent.failure_code = capture_failed) |
захиалгаа хаах | үгүй |
| 409 | in_progress |
энэ intent-ийн ledger дуудлага явагдаж байна | түр хүлээгээд GET |
тийм |
| 409 | not_cancelable |
цуцлах боломжгүй төлөв (status хавсарна) |
төлөгдсөн бол буцаалт | үгүй |
| 409 | not_unclaimable |
зөвхөн claim хийгдсэн, баталгаажаагүй claimless intent-ийг суллана (payment_intent хавсарна) |
хүлээх эсвэл cancel |
үгүй |
| 500 | server_error |
терминал/дэд худалдагчийг уншиж чадсангүй | дахин | тийм |
202 Accepted нь алдаа биш: capture-ийн ledger-ийн хариу хараахан тодорхойгүй (status: "processing"). Хэсэг хугацааны
дараа GET-ээр унш эсвэл webhook-ийг хүлээ — дахин capture хийх хэрэггүй (хийвэл мөн л аюулгүй).
Буцаалт¶
POST /payment-intents/{id}/refunds (Буцаалт).
| HTTP | code | Хэзээ | Юу хийх | Давтах |
|---|---|---|---|---|
| 409 | not_refundable |
зөвхөн succeeded эсвэл partially_refunded intent-ийг буцаана |
үгүй | |
| 409 | refund_window_expired |
төлбөрөөс хойш 90 хоног өнгөрсөн | хүнтэй өөрөө тооцоо хийх | үгүй |
| 400 | validation_error |
amount < 1, эсвэл буцаалтын нийлбэр төлсөн дүнгээс хэтэрнэ; reason > 255 |
үгүй | |
| 400 · 409 | idempotency_key_required · idempotency_conflict |
дээрхтэй адил; key нь intent бүрт давтагдашгүй | үгүй | |
| 503 | payments_unavailable |
live, core banking идэвхгүй | тийм |
Ledger буцаалтыг татгалзвал энэ нь HTTP алдаа биш: хариу 201 бөгөөд буцаалтын status: "failed", failure_code
доорх хүснэгтийнх, refund.failed webhook илгээгдэнэ. Хариу тодорхойгүй бол 202 + status: "pending" — платформ
өөрөө дуусгаж webhook илгээнэ. Ижил key-ээр давтахад 200 + тэр буцаалт.
Худалдагчийн бүртгэл — терминал, дэд худалдагч, payout холболт¶
/terminals…, /sub-merchants… — зөвхөн client credential (Basic). Batch, sticker-ийн PDF-ийн кодууд — доорх
«Терминалын хэрэгсэл».
| HTTP | code | Хэзээ | Юу хийх | Давтах |
|---|---|---|---|---|
| 403 | live_only |
test түлхүүрээр терминал / дэд худалдагч үүсгэх, засах, payout-link хүсэх (test нь зөвхөн уншина — бүртгэл хоёр орчинд нэг) | live түлхүүр эсвэл консол | үгүй |
| 409 | reference_taken |
апп-ын өөр терминал энэ reference-тэй |
өөр reference |
үгүй |
| 400 | invalid_sub_merchant |
sub_merchant_id энэ апп-ынх биш |
үгүй | |
| 400 | code_immutable |
дэд худалдагчийн code-ыг өөрчлөх гэсэн |
шинэ дэд худалдагч бүртгэх | үгүй |
| 409 | sub_merchant_disabled |
идэвхгүй дэд худалдагчид payout-link хүсэх | эхлээд идэвхжүүлэх | үгүй |
| 400 | validation_error (path: "account") |
payout данс олдсонгүй, идэвхгүй эсвэл MNT биш | үгүй | |
| 422 | account_unsupported |
дансны эзэмшигч нь Gerege App-ын хүн ч, байгууллага ч биш | өөр данс | үгүй |
| 422 | no_admin |
байгууллагын данс, гэхдээ батлах админ алга | байгууллага админ томилох | үгүй |
| 503 | directory_unavailable |
байгууллагын админуудыг түр уншиж чадсангүй — «мэдэхгүй», хэзээ ч «үгүй» биш | дахин | тийм |
| 502 | core_unavailable |
core banking хариу өгсөнгүй | дахин | тийм |
| 503 | payments_unavailable · pay_url_unavailable |
суулгацад core banking / худалдагчийн бүртгэл идэвхгүй | тийм (хожим) |
Дэлгэрэнгүй: Gerege App-аар төлөх, Payout данс.
Тооцоо¶
GET /settlements, GET /settlements/{id} (Тооцоо).
| HTTP | code | Хэзээ | Юу хийх | Давтах |
|---|---|---|---|---|
| 503 | settlements_unavailable |
суулгацад тооцооны сан алга | тийм (хожим) | |
| 400 | invalid_status · invalid_cursor · invalid_limit |
status нь pending/paid/failed биш, cursor буруу, limit 1–100 биш |
үгүй | |
| 404 | — (http_404) |
тооцоо алга, эсвэл test түлхүүрээр (test-д тооцоо хэзээ ч байхгүй, жагсаалт хоосон) | live түлхүүр | үгүй |
failure_code¶
Татгалзсан хариу биш — объект дээрх талбар: юу болсныг тайлбарлана.
Intent (payment_intent.failure_code)¶
failure_code |
Утга | Intent |
|---|---|---|
insufficient_funds |
үлдэгдэл хүрэлцэхгүй | failed — хүн өөр данснаас дахин төлж болно |
limit_exceeded |
хүний дансны гүйлгээний хязгаар хэтэрсэн | failed, дахин төлж болно |
account_unavailable |
сонгосон данснаас төлөх боломжгүй (хаалттай, хүнийх биш) | requires_confirmation хэвээр, webhook-гүй |
authorization_expired |
manual барьцааны хугацаа (capture_before) дууссан |
expired |
expired |
баталгаажуулалтын явцад intent-ийн хугацаа дууссан | expired |
merchant_unavailable |
апп төлбөр авахаа больсон (түдгэлзсэн, payout алга) — барьцаа суллагдсан | failed |
capture_failed |
capture-ийг ledger татгалзсан — барьцаа суллагдсан | failed |
hold_mismatch |
ledger-ийн барьцаа intent-тэй таарсангүй, ашиглагдаагүй | failed |
captured_after_release |
суллах үед барьцаа аль хэдийн capture хийгдсэн байсан — платформ гараар тулгана | (төлөв хэвээр) |
test_declined |
test горим, дүн …01 (Тест дүн) |
failed |
payment_failed |
бусад татгалзал | failed |
failed intent нь OMAS-ын дагуу дахин төлөгдөж болно (шинэ оролдлого — шинэ барьцаа).
Буцаалт (refund.failure_code)¶
failure_code |
Утга | Юу хийх |
|---|---|---|
insufficient_funds |
payout данс төлбөрийн мөнгийг аль хэдийн зарцуулсан | дансаа цэнэглээд шинэ key-ээр дахин буцаах |
settlement_shortfall |
апп-ын клиринг энэ буцаалтыг даахгүй (төлбөр аль хэдийн тооцоогоор шилжсэн) | оператортой холбогдох |
refund_rejected |
бусад татгалзал | оператортой холбогдох |
Тооцоо (settlement.failure_code)¶
failure_code |
Утга |
|---|---|
idempotency_conflict |
ledger ижил key-г өөр мөртэй харсан — оператор шалгана |
insufficient_funds |
клирингийн үлдэгдэл бүртгэлтэй зөрсөн |
destination_unavailable |
payout данс хаалттай эсвэл хөлдсөн — оператор payout-ыг сольж дахин тооцно |
limit_exceeded |
ledger-ийн хязгаар |
rejected |
бусад татгалзал |
failed тооцоог оператор дахин илгээх эсвэл хүчингүй болгоно (мөрүүд нь дараагийн тооцоонд орно).
Хүний тал (мэдээлэл болгон)¶
Эдгээрийг Gerege App (iOS) хүлээн авна; таны backend хэзээ ч авахгүй, гэхдээ хүн юу харсныг ойлгоход хэрэгтэй.
| HTTP | code | Хэзээ |
|---|---|---|
| 404 | unknown_payment · unknown_terminal · nothing_pending |
pay_url-ийн token танигдсангүй (эсвэл хүнд харагдах ёсгүй test төлбөр) · терминал алга/идэвхгүй · терминалд одоо төлөх зүйл алга |
| 409 | already_claimed |
өөр хүн төлж байна (retry_after: 90 — баталгаажаагүй claim 90 секундэд дуусна) |
| 409 | not_claimable |
intent одоо төлөгдөх боломжгүй (status хавсарна) |
| 410 | expired |
claim хийх үед intent-ийн хугацаа дууссан |
| 429 | too_many_open_claims |
хүнд аль хэдийн 3 баталгаажаагүй claim байна |
| 409 | merchant_unavailable |
апп одоо төлбөр авахгүй (түдгэлзсэн, идэвхгүй, payout алга) |
| 403 | verification_required · age_restricted |
апп эсвэл intent-ийн min_age eID-аар баталгаажсан хүн шаардана · нас хүрэхгүй эсвэл уншигдахгүй |
| 409 | already_processed · in_progress · expired |
баталгаажуулалт: аль хэдийн шийдэгдсэн · явагдаж байна · хугацаа дууссан |
| 409 · 403 · 422 | insufficient_funds · limit_exceeded / account_unavailable · test_declined / payment_failed |
баталгаажуулалтын үр дүн (intent хавсарна) |
| 409 | not_pending · account_unavailable |
payout холболт: хүсэлт аль хэдийн хариулагдсан/хугацаа дууссан · данс тэр хүнийх (эсвэл түүний админ байгууллагынх) байхаа больсон |
| 428 | consent_required |
нээлт: хүн scope-уудыг зөвшөөрөөгүй (scopes, app хавсарна) |
| 409 · 403 · 400 | maintenance · channel_unavailable · invalid_path / invalid_channel / invalid_scope |
нээлт: апп засвартай · энэ сувагт санал болгоогүй · зам, суваг, scope буруу |
Bridge-ийн кодууд: Bridge.
Хөгжүүлэгчийн консол ба sandbox¶
Консол (/api/v1/miniapp/dev/…) ба операторын review-ийн кодууд — таны server integration хүлээн авахгүй, консолын
дэлгэц харуулна.
| HTTP | code | Хэзээ |
|---|---|---|
| 409 | slug_taken |
өөр апп энэ slug-тай |
| 409 | sandbox_only |
sandbox байгууллага (хуулийн этгээдгүй хүнийх): live түлхүүр, live secret, review-д илгээх, гэрээ, payout холболт, апп-ын payout хийхгүй — test бүхэлдээ ажиллана (Sandbox) |
| 400 | sandbox_slug |
sandbox-ын апп-ын slug sbx--ээр эхэлнэ (^sbx-[a-z0-9-]{3,27}$), бусад байгууллагад sbx- хориотой |
| 503 | sandbox_unknown |
байгууллага sandbox эсэхийг платформ хэлж чадсангүй — live үйлдэл хийгдсэнгүй, дахин оролдоно |
| 409 · 400 | version_conflict · version_required |
өөр хүн зэрэг зассан — дахин уншаад засна · засвар нь аль хувилбар дээр хийгдсэнийг заах ёстой |
| 409 | locked_for_review · needs_review · status_locked · suspended |
хянагдаж буй апп өөрчлөгдөхгүй · батлагдсан апп-ын эмзэг талбар (kind, return_hosts …) — зөвхөн ноорог/татгалзсан үед · төлөв ингэж солигдохгүй · апп түдгэлзсэн |
| 400 | unknown_field · invalid_field · invalid_environment · invalid_range · invalid_app_id |
PATCH-ийн мэдэгдэхгүй талбар · буруу төрөл · environment нь live/test биш · статистикийн огноо (≤ 366 хоног) · app_id UUID биш |
| 400 · 409 | not_ready · not_submittable |
submit: шаардлага дутуу (details) · илгээх боломжгүй төлөв |
| 409 | merchant_no_manifest |
худалдагчид manifest шалгах зүйл алга |
| 503 | no_secret_key |
суулгацад webhook secret битүүмжлэх түлхүүр алга — secret хэзээ ч ил хадгалагдахгүй |
| 409 | no_webhook |
webhook URL / endpoint тохируулаагүй (дахин илгээх, webhook.test) — endpoint-ийн бусад кодууд доорх «Webhook endpoint ба events API» |
| 404 · 409 · 503 | user_not_found · too_many_test_users · directory_unavailable |
тест хэрэглэгч таны байгууллагын идэвхтэй гишүүн биш · > 50 · гишүүдийн жагсаалт түр уншигдахгүй |
| 400 | idempotency_key_invalid |
sandbox-ын тест intent-ийн Idempotency-Key 1–128 тэмдэгт биш |
| 409 | merchant_unavailable · already_processed · expired |
тест intent баталгаажуулах үед |
| 503 | settlements_unavailable |
тооцооны сан алга |
| 422 · 422 | account_not_owned · account_unavailable |
апп-ын payout (PUT …/apps/{id}/payout): данс танай байгууллагынх биш — оператор тохируулна · данс олдсонгүй, идэвхгүй эсвэл MNT биш |
| 403 | admin_required · impersonated |
апп-ын payout-ыг байгууллагын админ л, өөрийн сессээр |
Операторын кодууд (зөвхөн операторын консолд): invalid_review_status, not_in_review, already_suspended,
note_required, not_draft, not_archived (layout), settlements_off, settlement_open, refund_pending,
not_failed, not_retryable, rule_clash, rule_in_effect, ledger_seg_taken, gl_unavailable.
Хэтэвчнээс банк руу мөнгө гаргах (/api/v1/bank/…)-ын кодууд: Банк руу гаргах.
SDK-ийн алдаа¶
Node (@gerege/miniapp-node) |
Go (sdk/go) |
|
|---|---|---|
| API-ийн татгалзал | GeregeError — status, code, message, requestId, details (нэмэлт талбарууд) |
*miniapp.APIError — StatusCode, Code, Message, RequestID, Details ([]Issue), Extra |
| Token endpoint | GeregeOAuthError (error, error_description) |
*APIError (Code = OAuth-ын error) |
| Сүлжээ / timeout | GeregeError status: 0, code: "network_error" |
wrap хийсэн error (APIError биш) |
| Давтах уу | err.retryable — 0, 429, 5xx |
apiErr.Retryable() — 429, 5xx |
| Хүсэлтээс өмнө | TypeError (key, id, credential дутуу) |
ErrIdempotencyKey, ErrPresentment, ErrMissingID, ErrMissingAccount, ErrNoCredentials |
| Webhook | GeregeWebhookError.reason |
ErrMissingHeader, ErrMalformedHeader, ErrTimestamp, ErrSignatureMismatch, ErrInvalidPayload, ErrNoSecret |
Доорх хэсгүүд нь хөгжүүлэгчийн платформын шинэ API-уудын (түлхүүр, endpoint ба events, самбар ба тайлан, терминалын хэрэгсэл, гэрээ) кодууд — API бүрийг нэмсэн өөрчлөлт өөрийн хэсгийг бичнэ.
Түлхүүр ба scope¶
API түлхүүр (1.8.0): client id gk_live_… / gk_test_…, secret gks_live_…_<checksum> (хуучин mapp_… +
gma_cs_… хос = «Анхдагч түлхүүр», тухайн орчны бүх scope). Server route бүр шаардах scope-оо OpenAPI-ийн
x-gerege-scope-д нэрлэнэ.
| HTTP | code | Хэзээ | Юу хийх |
|---|---|---|---|
| 401 | invalid_client |
secret буруу; түлхүүр хүчингүй болсон, хугацаа нь дууссан, солигдоод давхцал нь өнгөрсөн (ялгаагүй) | консолоос түлхүүрийн төлөвийг шалга |
| 403 | insufficient_scope |
түлхүүрт route-ийн scope алга — required_scope нэрлэнэ (WWW-Authenticate: Basic error="insufficient_scope", scope="…") |
тэр scope-той шинэ түлхүүр (scope өөрчлөгдөхгүй) |
| 403 | ip_not_allowed |
түлхүүрийн IP allowlist-д энэ хаяг (ip) алга |
allowlist-ээ зас |
| 403 | live_only |
test түлхүүрээр терминал / дэд худалдагч / payout-link бичих (scope-оос өмнө шалгагдана) | live түлхүүр эсвэл консол |
Консол (/dev/apps/{id}/keys…): 400 validation_error (details[].path: name, environment, scopes — үл
мэдэгдэх, давхардсан, test түлхүүрт live-only, preset, allowed_ips, expires_at, overlap_seconds, reason),
400 scopes_immutable (PATCH-аар scope өөрчлөх гэсэн), 403 permission_required (permission: miniapp.develop —
test, miniapp.keys.live — live), 403 fresh_sign_in_required (within_seconds), 409 name_taken,
409 too_many_keys (орчинд идэвхтэй 20), 409 key_not_active (status: revoked / expired / rolled), 409 suspended,
503 fresh_sign_in_unavailable (суулгац хэзээ нэвтэрснийг шалгаж чадсангүй — live түлхүүр үүсгэх, солих, IP өөрчлөх,
POST /dev/apps/{id}/credentials-ийн live secret хийгдэхгүй; дараа дахин), 409 sandbox_only (sandbox байгууллагад live
түлхүүр алга), 400 invalid_environment / invalid_cursor / invalid_limit (жагсаалт). 1.13.0-ээс live түлхүүр,
live secret нь miniapp.keys.live ба сүүлийн 10 минутын нэвтрэлт (403 fresh_sign_in_required) шаардана; IP allowlist
цөмийн тодорхойлсон хаягаар (итгэмжлэгдсэн proxy-ийн ард) ажиллана.
Webhook endpoint ба events API¶
/webhook-endpoints (client credentials, тухайн credential-ийн орчин) ба консолын /dev/apps/{id}/webhook-endpoints,
/dev/apps/{id}/webhook/…; /events (client credentials).
| HTTP | code | Хэзээ | Юу хийх |
|---|---|---|---|
| 409 | too_many_endpoints |
орчинд 5 endpoint (№1 орно) аль хэдийн бий | илүүдлийг устгах эсвэл нэгтгэх |
| 403 | live_only |
test түлхүүр /webhook-endpoints дуудав — webhooks:write зөвхөн live түлхүүрт |
test endpoint-ийг консолоос |
| 403 | insufficient_scope |
түлхүүрт webhooks:write / events:read алга (required_scope) |
scope-той түлхүүр |
| 403 | environment_mismatch |
түлхүүр өөр орчны endpoint үүсгэх / жагсаах гэв | тухайн орчны түлхүүрээр |
| 409 | environment_mismatch |
консол: live event-ийг test endpoint руу (эсвэл эсрэгээр) дахин илгээх гэв | ижил орчны endpoint сонгох |
| 400 | validation_error |
url (https, нийтийн хаяг), environment, description ≤ 200, event_types (танигдах, давхардалгүй, ≤ 20; webhook.test биш), status |
details[].path |
| 409 | suspended · locked_for_review |
апп түдгэлзсэн; хянагдаж буй апп-ын endpoint №1-ийн URL/secret | review дуусахыг хүлээх |
| 409 | no_webhook |
endpoint №1-ийн secret солих гэтэл апп-ын webhook арилсан; консолын тест/дахин илгээхэд endpoint алга | endpoint нэмэх |
| 503 | no_secret_key |
суулгацад secret битүүмжлэх түлхүүр алга | оператортой холбогдох |
| 400 | invalid_type |
type шүүлтүүр event төрөл биш |
|
| 400 | test_event_not_listed |
/events?type=webhook.test — консолын туршилтын илгээлт нэрлэсэн endpoint руу л явдаг, /events-д хэзээ ч орохгүй |
консолын хүргэлтийн логоос |
| 400 | invalid_endpoint |
консол: endpoint_id шүүлтүүр endpoint-ийн id биш |
|
| 400 | invalid_cursor · invalid_limit · invalid_environment |
жагсаалтын параметр буруу | |
| 400 | unknown_cursor |
/events?after= нь энэ апп, орчны event биш эсвэл 30 хоногоос хуучин (устсан) |
created_gte-ээр дахин эхлэх |
| 400 | invalid_created_gte |
created_gte RFC 3339 биш |
|
| 404 | — (http_404) |
endpoint/event алга, эсвэл өөр апп/орчных |
Endpoint 24 цаг бүх хүргэлтэд амжилтгүй бол байгууллагын админд мэдэгдэл (miniapp.webhook.failing), 5 хоног бол
status: auto_disabled (miniapp.webhook.disabled) — алдсан event-ийг /events-ээс татаад, PATCH {"status":"active"}.
Самбар, тайлан, симуляц¶
Консолын төлбөрийн самбар (/dev/payments…, /dev/refunds, /dev/statements, /dev/audit), худалдагчийн
backend-ийн GET /statements ба sandbox-ын симуляц (…/simulate, …/simulate-tap).
| HTTP | code |
Хэзээ |
|---|---|---|
| 400 | idempotency_key_required |
Самбарын үйлдэл (capture, cancel, unclaim, refunds) Idempotency-Key (1–100)-гүй |
| 400 | validation_error |
details[].path: reason (буцаалтад заавал, ≤ 255), amount, app_id, terminal_id, sub_merchant_id, created_gte/created_lt (RFC 3339), amount_gte/amount_lte, q (≤ 128), presentment, action, test_user_id |
| 400 | invalid_status · invalid_environment · invalid_cursor · invalid_limit · invalid_format · invalid_range |
Шүүлтүүр, хуудаслалт, format (json | csv), from/to (YYYY-MM-DD, ≤ 366 хоног) |
| 403 | permission_required |
permission: miniapp.payments (үйлдэл), miniapp.finance (CSV, тайлан) эсвэл miniapp.develop (симуляц) |
| 403 | fresh_sign_in_required |
Live ≥ 1 000 000₮ буцаалт самбараас — сүүлийн within_seconds (600) дотор дахин нэвтэрч давтана |
| 503 | fresh_sign_in_unavailable |
Суулгац дахин нэвтрэлтийг шалгаж чадсангүй — том буцаалт хийгдэхгүй |
| 409 | not_capturable · expired · not_cancelable · in_progress · not_refundable · refund_window_expired · idempotency_conflict · not_unclaimable · terminal_busy |
Апп-ын backend-ийн ижил замаас — утга нь дээрх «Mini app backend» ба «Худалдагч» хэсгийнхтэй ижил |
| 409 | live_intent |
Симуляц зөвхөн test intent-д |
| 409 | not_a_test_user |
test_user_id (эсвэл дуудагч) апп-ын тест хэрэглэгч, эзэн биш |
| 409 | not_claimless · not_claimed · not_expirable |
claim-ийг app intent-д; confirm/decline-ийг claim хийгээгүйд; expire-ийг дууссан intent-д |
| 409 | already_claimed (retry_after) · already_processed · merchant_unavailable · terminal_disabled |
Бодит claim, баталгаажуулалттай ижил |
| 404 | nothing_pending |
simulate-tap: терминалд нээлттэй test intent алга |
| 410 | expired |
Симуляцын claim — хугацаа дууссан |
| 429 | too_many_open_claims |
Тест хэрэглэгчид баталгаажаагүй 3 claim |
| 422 | statement_too_large |
Тайлан > 100 000 мөр (max_rows) — хугацааг богиносго |
| 503 | dashboard_unavailable · pay_url_unavailable · payments_unavailable |
Суулгацын тохиргоо / түр алдаа — дахин оролдоно |
Терминалын хэрэгсэл¶
POST /terminals/batch, POST /terminals/print-sheet (консолд мөн GET …/print-sheet, GET …/terminals/{tid}/stats):
| HTTP | code |
Хэзээ |
|---|---|---|
| 400 | too_many_terminals |
batch хоосон эсвэл 500-аас олон мөр (max); хэвлэхэд terminal_ids-гүй үед 500-аас олон идэвхтэй терминал |
| 400 | invalid_csv |
Content-Type: text/csv уншигдсангүй: толгой мөр алга, label багана алга, үл мэдэгдэх эсвэл давхар багана (columns), мөр таслагдсан (line) |
| 400 | validation_error |
details[].path = terminals[i].label … — нэг ч буруу мөр batch-ийг бүхэлд нь татгалзана, юу ч бичигдэхгүй; хэвлэх: layout, locale, crop_marks, terminal_ids[i] (буруу id, давхар, олдоогүй, идэвхгүй терминал) |
| 403 | live_only |
batch-ийг test түлхүүрээр — бүртгэлийг зөвхөн live түлхүүр эсвэл консол бичнэ (хэвлэх, статистик унших нь test-д ч болно) |
| 409 | no_terminals |
хэвлэх идэвхтэй терминал алга |
| 400 | invalid_range / invalid_environment |
статистикийн from/to (YYYY-MM-DD, ≤ 366 хоног), environment |
Batch-ийн хариу 200 — мөр бүрийн status: created, existing (тэр reference бүртгэлтэй), failed
(error.code: reference_taken, invalid_sub_merchant, …; бусад мөр явсан), skipped (серверийн алдаагаар
оролдоогүй — batch-аа дахин илгээнэ, reference-тэй мөр давтагдахгүй).
Гэрээ ба eID гарын үсэг¶
Консолын /dev/agreements… ба операторын /review/agreements… (server-to-server биш). Гарын үсэг эхлүүлэхэд gate-ийн
miniapp.manage ба цөмийн шалгадаг miniapp.agreements.sign (эсвэл админ) хэрэгтэй, мөн eID-д тухайн байгууллагын
төлөөлөгч байх ёстой.
| HTTP | code | Хэзээ | Юу хийх |
|---|---|---|---|
| 202 | — | POST …/{id}/sign: утсанд хүсэлт очсон — {signature_id, verification_code, org_name} |
кодыг утсан дээрхтэй тулгаад PIN2; GET …/signatures/{sid}?wait=20-ээр poll |
| 409 | signing_unavailable |
суулгацад eID гарын үсгийн зам алга (RP-д SIGNATURE эрхгүй, PDF гарын үсэг алга) | оператортой холбогдох |
| 503 | no_secret_key |
суулгацад нууц битүүмжлэх түлхүүр алга | оператор |
| 403 | not_representative |
eID-ийн бүртгэлд та энэ байгууллагын хүчинтэй төлөөлөгч биш | төлөөлөгч (захирал г.м.) өөрөө зурна; бүртгэлийг улсын бүртгэлд засна |
| 403 | permission_required |
miniapp.agreements.sign эрхгүй (permission) |
админ эрх олгоно |
| 403 | impersonated |
өөр хүний нэрээр нэвтэрсэн сесс | өөрийн сессээр |
| 409 | no_eid |
таны бүртгэлд eID холбогдоогүй | eID-ээр нэвтэрч холбоно |
| 409 | no_registration_number |
байгууллагын профайлд регистр алга (sandbox-д үргэлж) | профайлыг бөглөнө |
| 409 | already_signed |
энэ хувилбарт гарын үсэг бий (signature_id) |
— |
| 409 | signature_running |
нээлттэй ceremony бий (signature_id, verification_code) |
утсаа шалгах эсвэл дуусахыг хүлээх |
| 409 | agreement_superseded |
хуучин хувилбар — одоогийнх эсвэл удахгүй хүчин төгөлдөр болох л зурагдана | одоогийнхыг зурна |
| 409 | not_signed |
…/document: гарын үсэг хараахан дуусаагүй |
poll |
| 502 | signing_failed |
eID хүсэлтийг эхлүүлж чадсангүй | дахин оролдох |
| 503 | agreements_unavailable |
суулгацад гэрээний бүртгэл алга | — |
| 400 | invalid_wait |
wait нь 0–20 биш |
Ceremony-ийн төлөв (signature.status): running → completed | failed | expired | rejected (eID-ийнх).
failure: rejected, expired, failed, no_answer (eID 2 цагт хариулаагүй), session_lost, stamp_unavailable
(timestamp/OCSP 24 цаг алга), organisation_mismatch, not_a_pdf, no_certificate, file_store, signature_unreadable.
failed/expired/rejected-ийн дараа дахин эхлүүлж болно.
Оператор: 400 validation_error (details), 400 invalid_kind, 409 version_taken, 409 not_draft (нийтлэгдсэнийг
засах/устгах/дахин нийтлэх), 409 draft_text (production-д «ХУУЛЬЧИЙН ХЯНААГҮЙ ТӨСӨЛ» тэмдэгтэй загвар текст).
Sandbox байгууллагад гарын үсэг эхлэхгүй: 409 sandbox_only (1.13.0).