Gaming top-up flow

A customer is waiting on the other side of a form. They've tapped their game, picked a pack, and entered their player ID. From here it's six requests — three to figure out what to charge, one to take their money, and a couple to make sure it landed.

This guide is the full path. Sandbox-safe, copy-pastable, and honest about where the rough edges still are.

What this guide builds

The map

┌──────────────────┐
│ 1. Find product  │  GET   /api/v1/topups/products?type=GAMING
└─────────┬────────┘
          ▼
┌──────────────────┐
│ 2. Read inputs   │  GET   /api/v1/topups/products/:id
└─────────┬────────┘
          ▼
┌──────────────────┐  (optional)
│ 3. Show variants │  GET   /api/v1/topups/products/:id/variants
└─────────┬────────┘
          ▼
┌──────────────────┐
│ 4. Quote price   │  POST  /api/v1/topups/charges
└─────────┬────────┘
          ▼
┌──────────────────┐
│ 5. Place order   │  POST  /api/v1/topups/orders
└─────────┬────────┘
          ▼
┌──────────────────┐
│ 6. Watch status  │  GET   /api/v1/topups/orders/:id  (loop)
└──────────────────┘

Steps 3 and 4 are independent — fetch variants if the UI shows packs, or skip straight to charges if it accepts a raw amount.

Step 1 — Find the product

Start by asking the catalogue for the game the customer wants. type=GAMING filters out mobile recharges and utility products.

curl "$HOST/api/v1/topups/products?type=GAMING&search=pubg" \
  -H "Authorization: Bearer $TOKEN"

Each entry comes with an id — that's the handle threaded through every other request.

Step 2 — Read the required inputs

Different games ask for different things. PUBG Mobile wants a player ID and a server. Free Fire wants a player ID. Genshin wants UID plus region. Don't hardcode these — the product tells you.

curl "$HOST/api/v1/topups/products/4218" \
  -H "Authorization: Bearer $TOKEN"

The detail response includes input_fields[]. Render those as form inputs and respect the metadata:

Three rules for input_data

The order request will carry input_data — a map keyed by the field_name from the input field. Three rules keep the integration out of trouble:

1. Send only declared keys. Extras get rejected — fulfilment paths sometimes fold them into request signing and an unrecognised key would surface later as a confusing "Invalid Signature" error, so Octopus Cards stops it at the door.
2. Always send required keys. Validation runs server-side; missing keys come back as a 400 with the human-readable label.
3. Echo select values exactly. No fuzzy matching. "asia" is not "Asia".

Step 3 — Show variants (optional)

If the UI shows packs ("60 UC for $0.99", "325 UC for $4.99"), this is where to fetch them.

curl "$HOST/api/v1/topups/products/4218/variants" \
  -H "Authorization: Bearer $TOKEN"

Each variant has fixed_amounts[] (the available denominations as decimal strings) and a fields[] array with par_value, delivery_time, etc. for display.

Skip this step entirely when the UI just asks the customer for an amount and the business model is "any amount, any time".

Step 4 — Quote the price

Before debiting, get the real number. The charges endpoint resolves the variant, applies the client discount, and returns exactly what will leave the wallet.

curl -X POST "$HOST/api/v1/topups/charges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 4218,
    "amount": 4.99
  }'

The response has total_payable — that's what gets debited. For bulk flows, pre-check the wallet against it:

c, _ := quote(host, token, 4218, 4.99)
w, _ := getWallet(host, token, walletID)
if w.Amount < c.TotalPayable {
    return errors.New("insufficient funds")
}

When to call it

• Right before an order, every time. The result is server-cached for 5 minutes per (product, amount, quantity, client) tuple, so this isn't a wasted call.
• When the customer changes the amount in the UI. Re-quote so the displayed price stays accurate.
• Not on every keystroke. Debounce.

Step 5 — Place the order

Here's where the wallet gets debited and the order leaves the building.

curl -X POST "$HOST/api/v1/topups/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 4218,
    "amount": 4.99,
    "input_data": {
      "player_id": "5123456789",
      "server": "asia"
    },
    "client_reference": "CAMPAIGN_DEC_24"
  }'

Three immediate outcomes

The order endpoint always responds quickly — but the meaning of that response depends on how fulfilment resolved.

Step 6 — Watch the status

For PENDING orders, loop the detail endpoint until it terminates — or until enough time has passed to switch from foreground polling to a notification-based wait.

func waitForTerminal(host, token string, orderID uint64) (*orderResp, error) {
    deadline := time.Now().Add(5 * time.Minute)
    delay := 5 * time.Second

    for time.Now().Before(deadline) {
        url := fmt.Sprintf("%s/api/v1/topups/orders/%d", host, orderID)
        req, _ := http.NewRequest("GET", url, nil)
        req.Header.Set("Authorization", "Bearer "+token)

        resp, _ := http.DefaultClient.Do(req)
        var out orderResp
        _ = json.NewDecoder(resp.Body).Decode(&out)
        _ = resp.Body.Close()

        switch out.Status {
        case "DELIVERED", "FAILED", "CANCELLED":
            return &out, nil
        }
        time.Sleep(delay)
        if delay < 30*time.Second {
            delay *= 2
        }
    }
    return nil, errors.New("order did not reach terminal within window")
}

GET /topups/orders/:id refreshes the status against fulfilment on every call while the order is still PENDING — so a single hit returns the freshest known state. An order still PENDING after several minutes is Octopus Cards automatically retrying transient conditions, not a stuck order.

Recommended cadence

Handling failure

Failed orders aren't all the same. The is_user_fixable flag tells whether to invite the customer to retry.

A note on idempotency

The client_reference field on POST /topups/orders is the idempotency key. Pass a client-supplied value (printable ASCII, ≤ 255 chars) and a duplicate submission returns 400 "Duplicate client_reference" — retries can't accidentally create a second order. Omit it and you lose dedup protection — retries without a client_reference will create duplicates.

To stay safe on network retries:

• Always send a client-supplied client_reference for any operation that might be retried. Generate it before the first attempt and reuse the same value on subsequent retries.
• A 2xx response is final. A 200 means the order was placed and the wallet was debited. Never retry a 2xx.
• For 5xx and network errors, retry with the same client_reference — duplicates are rejected, so a second 2xx create is impossible.

Putting it together

A full reference implementation that handles the immediate-terminal and async-pending paths in one function:

package main

import (
    "bytes"
    "encoding/json"
    "errors"
    "fmt"
    "net/http"
    "time"
)

func purchase(host, token string, productID uint64, amount float64, playerID, server, clientRef string) (*orderResp, error) {
    order, err := placeOrder(host, token, productID, amount, playerID, server, clientRef)
    if err != nil {
        return nil, err
    }

    // Already terminal? Done.
    switch order.Status {
    case "DELIVERED", "FAILED", "CANCELLED":
        return order, nil
    }

    // Otherwise poll until it terminates.
    return waitForTerminal(host, token, order.ID)
}

What to read next

Recap

• One product → one or many variants. The order request passes product_id + amount; Octopus Cards picks the variant.
• input_data keys must match the product's declared input_fields exactly — no extras, no guesses.
• The wallet is debited synchronously; fulfilment is async.
• Poll GET /topups/orders/:id for live status — it refreshes the latest state on each call.
• Failed orders auto-refund. is_user_fixable is the signal for whether to invite the customer to retry.