First mobile top-up order

Mobile recharges differ from gaming top-ups in one important way: in many countries, the mobile number alone doesn't unambiguously identify the operator. +91 88... could be Airtel, Vi, Jio, or BSNL. Octopus Cards offers a lookup endpoint that resolves the MSISDN to a list of matching MOBILE products.

Three requests after authentication: lookup, order, poll.

1. Detect the operator

curl -X POST "$HOST/api/v1/topups/lookup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mobile_number": "+918879685100"}'

[
  {
    "product_id": 4219,
    "name": "Airtel India",
    "country_code": "IND",
    "identified": true
  },
  {
    "product_id": 4231,
    "name": "Vi (Vodafone Idea) India",
    "country_code": "IND",
    "identified": false
  }
]

Use the identified: true entry for confident customers. Render identified: false entries as "wrong operator? Pick another" disambiguation in the UI.

The number must be in E.164 format (+ followed by country code and digits — no spaces, no dashes).

2. Place the order

For mobile, input_data carries phone_number (same E.164 value used for lookup).

curl -X POST "$HOST/api/v1/topups/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 4219,
    "amount": 200,
    "category": "Airtime",
    "input_data": {
      "phone_number": "+918879685100"
    },
    "client_reference": "FIRST_RECHARGE_001"
  }'

The category field constrains variant selection (Airtime for open-range, Data for fixed plans, Bundle for combos). Airtime variants accept any amount within [min_amount, max_amount]; Data plans need an exact denomination.

3. Poll until terminal

Same poll loop as the gaming top-up.

ORDER_ID=9123450
while true; do
  status=$(curl -s "$HOST/api/v1/topups/orders/$ORDER_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  case "$status" in
    DELIVERED|FAILED|CANCELLED) echo "Terminal: $status"; break ;;
  esac
  sleep 5
done

Mobile recharges typically terminate in 5–15 seconds — faster than gaming top-ups because operator prepaid platforms process them directly.

What just happened

1. Resolved an MSISDN to the matching operator product (the identified: true entry).
2. Placed a recharge order with phone_number in input_data.
3. Polled until terminal — typically DELIVERED within a few seconds.

Next

After completing this flow, the others are short cousins of the same pattern. Then:

• Mobile recharge flow — the longer walkthrough including country-specific gotchas and disambiguation patterns.
• Sync vs async orders — how Octopus Cards decides between inline delivery and polling.
• Cross-currency orders — paying in a wallet whose currency differs from the variant.
• Before You Go Live — the production checklist.
• Topup endpoint reference — every topup endpoint with full request/response shapes.