Давталт (idempotency)

Сүлжээ тасарна, timeout болно, хариу алдагдана. Gerege-ийн мөнгөний дуудлага бүрийг аюулгүй давтаж болно — давталт нэг л үр дүн өгнө, хэзээ ч хоёр дахь төлбөр биш.

1. Idempotency-Key хаана

Дуудлага	Толгой	Ижил key + ижил body	Ижил key + өөр body
POST /payment-intents	заавал (1–128 тэмдэгт)	200 — тэр intent (claimless бол ижил pay_url)	409 idempotency_conflict
POST /payment-intents/{id}/refunds	заавал	200 — тэр буцаалт	409 idempotency_conflict
POST /payments/{id}/confirm (хүн, Gerege App)	заавал	тэр оролдлогын үр дүн	409 idempotency_conflict (өөр данс)
POST /payment-intents/{id}/capture · /cancel · /unclaim	—	төлөвөөрөө idempotent: аль хэдийн succeeded / canceled бол тэрийгээ буцаана	—
POST /payments/claim (хүн)	—	(token, хүн)-ээр idempotent	—
POST /terminals, /sub-merchants	—	reference / code-оор: дахин → 200 тэр мөр	—

Key нь апп × орчинд үүрд өвөрмөц — хугацаа нь дуусдаггүй. «Ижил body» гэдэг нь normalise хийсэн body-ийн хэв (талбарын дараалал, хоосон зай хамаарахгүй).

2. Нэг захиалга = нэг intent

Key-ээ захиалгынхаа дугаараас гаргана — санамсаргүй UUID-аас биш:

Idempotency-Key: order-8812          reference: order-8812

Тэгвэл захиалгын товчийг хоёр дарсан, backend хоёр удаа ажилласан, retry давхацсан — бүгд нэг intent, нэг pay_url. Санамсаргүй key бол давталт бүр шинэ intent болж, хүн хоёр QR харна. Шинэ оролдлого (жишээ нь хугацаа дууссаны дараа) хэрэгтэй бол шинэ key: order-8812-2.

Test ба live орчинд key тусдаа.

3. Retry стратеги

Хариу	Давтах уу	Яаж
Сүлжээний алдаа, timeout	тийм	ижил key, ижил body
429	тийм	Retry-After-ийн дараа, ижил key
5xx	тийм	exponential backoff (1 с, 2 с, 4 с …), ижил key
202 (processing)	шинэ дуудлага биш	GET /payment-intents/{id} эсвэл webhook-ийг хүлээ
409 idempotency_conflict	үгүй	key-ээ өөр хүсэлтэд дахин ашигласан — кодоо засна
бусад 4xx	үгүй	хүсэлтээ засна (Алдааны код)

4. Webhook-ийн давхардал

Webhook at-least-once: нэг event хоёр удаа ирж болно, дараалал баталгаагүй. Event-ийн id (Gerege-Event-Id толгой)-оор давхардлыг арилгаж, эцсийн шийдвэрийг объектын status-аар гаргана — «хамгийн сүүлд ирсэн event» биш.