Sync vs. async orders

Each create-order endpoint has its own sync/async character. The shape of the response depends on whether fulfilment completed inside the request:

• Vouchers — a threshold rule. Small orders complete inline; large orders return PENDING and finish in the background.

• Topups — typically asynchronous. The order returns quickly; status flips from PENDING to terminal over seconds to minutes.

• eSIM — a 60-second hybrid. The handler waits up to 60s for fulfilment, then either returns the activation code inline or returns PENDING and continues in the background.

What's identical across every vertical: the wallet is debited synchronously. A PENDING order is already paid for; only fulfilment is pending. Failed terminal orders auto-refund — the debit and refund are two separate wallet transactions, both visible in the wallet log.

Vouchers — the threshold model

POST /api/v1/orders

The threshold is fixed at 5. There is no way to force async for small orders, or sync for large ones — quantity is the only knob.

Sync response (qty ≤ 5):

{
  "id": 1234,
  "status": "DELIVERED",
  "amount": 100.00,
  "discount": 3.50,
  "client_reference": "order-abc",
  "vouchers": [
    { "card_number": "STEAM-XXXX-XXXX", "pin_code": "1234", "expires_at": "2027-06-01T00:00:00Z" },
    { "card_number": "STEAM-YYYY-YYYY", "pin_code": "5678", "expires_at": "2027-06-01T00:00:00Z" }
  ]
}

Async response (qty > 5):

{
  "id": 1235,
  "status": "PENDING",
  "amount": 5000.00,
  "discount": 175.00,
  "client_reference": "campaign-q1-0001",
  "vouchers": []
}

Async voucher orders complete in 10–60 seconds typically; merchant-side slowdowns can push that to minutes.

Topups — typically asynchronous

POST /api/v1/topups/orders

There is no quantity threshold — topup orders are 1-at-a-time. The endpoint returns quickly with one of three immediate outcomes:

Most gaming top-ups and mobile recharges resolve from PENDING to terminal in 5–30 seconds. Slow paths can push that to minutes — the retry cron keeps trying server-side, so even a long-running order eventually reaches terminal status.

eSIM — the 60-second hybrid

POST /api/v1/esim/orders

The handler waits up to 60 seconds for fulfilment before returning. Every response is 200 OK — branch on the body status field:

After a status: PENDING response, a server-side dispatch goroutine keeps trying; polling GET /esim/orders/:id returns the latest known state on each call.

eSIM has a second async stage that's customer-driven, not server-driven: installation. After status: DELIVERED, the customer still has to download the LPA profile onto their device. The order's is_installed boolean flips to true once that happens — minutes later, hours later, sometimes never. Treat install as user-paced; never block on it.

Order placed                                           Customer installs
     │            ←   server-async   →                       │
     ▼                                                       ▼
  PENDING ─────────→ DELIVERED ──────────────────────→ is_installed: true
                    (LPA code issued)                  (device downloaded profile)

See eSIM lifecycle for the install-side state machine.

Side-by-side

All create-order endpoints return 200 OK — branch on the body status field (DELIVERED / PENDING / FAILED), not on the HTTP status code.

Handling a PENDING order

The same polling shape works across verticals — only the URL changes:

The polling endpoints refresh status against fulfilment on each call for in-flight orders — so a single fetch returns the freshest state.

# Exponential backoff: 5s, 10s, 20s, 30s, 30s...
ORDER_ID=9123456
URL_BASE=$HOST/api/v1/topups/orders  # or /orders, /esim/orders

delay=5
deadline=$((SECONDS + 600))   # 10 min cap
while [ $SECONDS -lt $deadline ]; do
  status=$(curl -s "$URL_BASE/$ORDER_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  case "$status" in
    DELIVERED|FAILED|CANCELLED|PARTIAL) echo "Terminal: $status"; break ;;
  esac
  sleep "$delay"
  [ "$delay" -lt 30 ] && delay=$((delay * 2))
done

Polling guidelines:

• Start at 5s, back off to 30s. Most orders finish well inside the first minute.
• Cap foreground polling at ~10 minutes. After that, the retry cron is still working; switch to a notification-based wait or surface "processing — we'll email you" UX.
• Never poll faster than every 2 seconds. That's rate-limit territory.

Notification email (server-driven)

Every vertical supports attaching an email address to an order after the fact:

Once attached, the customer receives a templated receipt at every terminal transition (DELIVERED, FAILED, CANCELLED). This is the no-polling, no-webhook option for end-user-facing flows where the customer's email is the natural delivery target.

Webhooks

Outbound webhooks are live for vouchers today:

• order.delivered
• order.partially_delivered
• order.failed
• order.cancelled
• wallet.credited / wallet.debited

Topup and eSIM webhooks are planned and will follow the same envelope shape. The expected events are documented under Topup webhooks and eSIM webhooks. Until they ship, polling (or the notification email) is the way to learn about terminal transitions.

Webhook + polling fallback is the highest-reliability pattern: webhook is primary, polling kicks in after a few minutes of silence as a belt-and-braces backstop.

Which mode for which use case

Statuses across verticals

Per-vertical detail: Voucher orders · Topup orders · eSIM orders.

Summary

• Vouchers are sync for quantity ≤ 5, async beyond that. Codes return inline in sync mode.

• Topups are usually async — the order endpoint returns quickly; status flips to terminal in seconds to minutes.

• eSIM is a 60-second hybrid — status: DELIVERED with activation code if fulfilled in time, status: PENDING otherwise. Either way the HTTP response is 200 OK.

• The wallet is debited synchronously in every case. PENDING refers only to fulfilment, not payment. FAILED auto-refunds.
• Polling works the same way across every vertical — the same loop, only the URL changes.

• Webhooks are live for vouchers today; planned for the other verticals.

• The notification-email patch endpoint exists on every vertical as a server-driven alternative to webhooks/polling for customer-facing flows.