State Machines

Every state machine in the platform, with the exact (status, sub_status) pairs that are actually written and which enum values are dead. Each resource has its own machine; they don't share code.

Detailed operational traces live in Order Lifecycle, Top-up & eSIM Flows, Payouts, and Admin Order Actions. This page is the formal state reference.

Voucher orders

Three nested machines: the order, its items (3-checkpoint), and — for link orders — voucher_links.

Order-level

OrderStatus (enum.go:13) × OrderSubStatus (enum.go:58). The only pairs written at runtime:

The order status is recomputed, not transitioned — getOrderDeliveryStatus (create_voucher_order.go:272) is a pure count-based function returning only PENDING / DELIVERED / PARTIALLY_DELIVERED:

• count != Quantity → PENDING (partial item creation).
• delivered==0 → PENDING; delivered>0 with any pending OR failed → PENDING (failed items keep the order retryable).
• delivered>0 AND cancelled>0 AND no pending/failed → PARTIALLY_DELIVERED — the only path to partial.
• all delivered → DELIVERED.

Item checkpoints

Items progress INITIAL → VENDOR_ORDER_PENDING → VENDOR_ORDER_CREATED → COMPLETED (or → VENDOR_ORDER_FAILED) through 3 idempotent checkpoints (bulk_vendor_order_checkpoints.go / individual_vendor_order_checkpoints.go). Dispatch groups items by vendor, then vendor.IsBulk picks bulk (whole group per call) vs individual (per item, parallelism PLimit).

• CP1 (auth + availability) → VENDOR_ORDER_PENDING. Skip-if-done: skips items already pending/created.
• CP2 (create vendor order) → VENDOR_ORDER_CREATED with vendor_order_id. Skip-if-done keys on the vendor-assigned vendor_order_id (not the ref code) so a lost response never duplicates. Ref-support vendors (e.g. Wupex) pre-persist the reference code before CreateOrder so a retry recovers via checkExistingVendorOrder instead of creating a dupe. Inline-voucher vendors jump straight to DELIVERED, skipping CP3.
• CP3 (assign vouchers) → DELIVERED/COMPLETED (note: jumps CREATED→COMPLETED — VENDOR_VOUCHER_FETCHED is skipped). ErrShouldReCreate clears vendor_order_id+ref (magic "NULL"), bounded by recreateBudget = 5; on exhaustion the order parks at PENDING for admin (never auto-FAILED). ErrVendorOrderTerminal → items FAILED.

Voucher links (GV-Link)

Link orders skip items/vendors entirely — createVoucherLinks writes one voucher_links row per unit, UNCLAIMED, expires_at = now+1yr, encrypted token + (non-PUBLIC) a 6-digit PIN. Order status derives from links: all UNCLAIMED/CLAIMED and count==Quantity → DELIVERED; else PENDING. Links never produce PARTIALLY_DELIVERED, and async is disabled for links.

VoucherLinkStatus (voucher_link.go:10): only UNCLAIMED is written by this repo — CLAIMED happens in the external claim frontend (Grasshopper); REFUNDED/NOT_REFUNDED are read to hide refunded links; PROCESSING/ERROR are unused here.

Recharge (mobile & gaming top-up)

RechargeStatus (enum.go:319). There is no sub_status column — the admin "refunded" flag rides on a [REFUNDED] prefix in status_text.

Create inserts PENDING, then the inline vendor call classifies (nil/transport error → stays PENDING for the cron). The cron path applyTopupVendorStatus is row-locked with a terminal short-circuit and auto-refunds on FAILED inside the lock. The "PROCESSING" literal guard at topup.go:711 is dead — no mapper ever yields it.

eSIM

Three independent axes on esim_orders: status, sub_status, activation_status.

Status (esim_order.go:14): PENDING / DELIVERED / FAILED / CANCELLED (last three terminal). Sub-status (esim_order.go:39): INITIAL, VENDOR_ORDER_PENDING, VENDOR_ORDER_CREATED, VENDOR_CODE_FETCHED, VENDOR_ORDER_FAILED, REFUNDED — all live; NOT_REFUNDED and COMPLETED are dead (never assigned).

Dispatch is a two-phase poll-before-recreate (DispatchEsimOrder): poll by vendor_order_id, then by merchant_ref (definitive not-found), then recreate with EsimRecreateBudget = 5 (parks 6h on exhaustion). persistDispatchOutcome is row-locked with a terminal short-circuit — the load-bearing double-refund guard — and auto-refunds on FAILED inside the lock. The delivered webhook maps to PROCESSING (not terminal) — a nudge, since it can't carry the activation code.

Activation (esim_order.go:89), the post-delivery axis:

Driven by the esim-installation-poll (5-min) and esim-expiry (daily) crons — see Cron Catalog.

Payouts

PayoutStatus (payout.go:17): created, queued, processing, settling, action_required, completed, failed, cancelled, expired. IsCancellable = created/queued/processing/action_required (not settling).

Only two PayoutEvents ever hit the DB: payout.created and payout.cancelled. Provider status maps (Merit/Ledig → internal) exist but are only reachable through the dead sync cron.

Scheduled payouts are, by contrast, fully live (driven by the registered scheduled-payout-processor):

ScheduledPayoutStatus: active / paused / completed / cancelled / exhausted.

Each fire calls CreatePayout — so every successful scheduled execution produces another stuck created payout. Execution rows record success/failed/skipped.

Dead-state catalog

Everything declared but never written at runtime, in one place — safe to prune once confirmed:

Key files

• Enums: database/models/{enum,esim_order,payout,scheduled_payout,voucher_link}.go
• Voucher: http/handler/{create_voucher_order,bulk_vendor_order_checkpoints,individual_vendor_order_checkpoints,order_state_machine,order}.go
• Recharge/eSIM: services/{topup_order,esim_order}.go, http/handler/{topup,esim}.go, services/vendor_webhook_service.go
• Payout: services/{payout_service,scheduled_payout_service}.go