DEV Community: MobileTopUP

MobileTopUP: Modeling Airtime, Data, and Bundles Without a Messy Product Schema

MobileTopUP — Mon, 14 Sep 2026 21:00:00 +0000

One of the easiest mistakes in a recharge platform is assuming that every product can be represented as:

amount = 10
currency = GBP

That works beautifully until the catalogue contains:

£10 general airtime;
5 GB valid for 7 days;
20 GB valid for 30 days;
100 local minutes;
500 SMS;
10 GB + 100 minutes;
unlimited social data for 3 days;
operator-specific promotional bundles.

At that point, amount is no longer a product model.

It is one attribute among many.

This article looks at a practical way to model operator-provided prepaid products without creating either an enormous table full of nullable columns or an unstructured JSON blob that becomes impossible to query.

Start by separating commercial value from included allowance

Consider these two products:

Product A
Price: 10 EUR
Recipient receives: 10 EUR airtime

Product B
Price: 10 EUR
Recipient receives: 8 GB data for 14 days

The purchase price is the same.

The product value is not.

A schema should therefore avoid assuming that:

purchase_amount == recipient_amount

A useful base model might begin with:

products
--------
id
provider_id
external_product_id
operator_id
country_code
product_type
display_name
purchase_amount
purchase_currency
recipient_value
recipient_currency
active

For general airtime:

{
  "product_type": "airtime",
  "purchase_amount": "10.49",
  "purchase_currency": "EUR",
  "recipient_value": "10.00",
  "recipient_currency": "EUR"
}

For a data bundle:

{
  "product_type": "data_bundle",
  "purchase_amount": "10.49",
  "purchase_currency": "EUR",
  "recipient_value": null,
  "recipient_currency": null
}

The bundle needs a different representation.

Use an explicit product type

Do not infer product behaviour from its name.

Bad:

if product.name contains "GB":
    product is data

Better:

product_type:
- airtime
- data_bundle
- voice_bundle
- sms_bundle
- combo_bundle

Your exact taxonomy may differ, but it should be explicit.

This improves:

filtering;
validation;
analytics;
UI rendering;
reporting;
tests.

The product name remains presentation data.

The type becomes application data.

Model allowances separately

A combined bundle may contain more than one allowance. A practical example of why this distinction matters can be seen in mobile data bundles, where data allowance, validity and operator-specific conditions need to be represented separately from general airtime.

For example:

10 GB data
200 voice minutes
100 SMS
valid for 30 days

Trying to fit that into the products table quickly becomes ugly:

data_amount
data_unit
voice_minutes
sms_count
social_data_amount
...

A normalized allowance model is more flexible.

product_allowances
------------------
id
product_id
allowance_type
amount
unit

Example:

product_id | allowance_type | amount | unit
------------------------------------------------
123        | data           | 10     | GB
123        | voice          | 200    | minute
123        | sms            | 100    | message

Now the application can render:

10 GB data
200 minutes
100 SMS

without adding a new database column for every future bundle type.

Validity deserves its own fields

Validity is core product behaviour.

It should not be buried only inside description text such as:

"Awesome 10GB package valid for 30 days!"

Store it structurally.

For example:

validity_value = 30
validity_unit = day

or:

{
  "validity": {
    "value": 30,
    "unit": "day"
  }
}

This enables:

sorting bundles by duration;
warning users about short validity;
consistent formatting;
analytics;
comparison logic.

Some products may not provide a meaningful validity period.

Make that state explicit rather than pretending every product has one.

Keep provider identity separate from internal identity

External providers often have their own IDs:

ABC-UK-10
prod_847261
sku_2291

Do not make those your primary application key.

Your application should own its identity:

products.id = internal UUID
products.external_product_id = provider identifier

Why?

Because providers can:

rename SKUs;
migrate APIs;
reuse external conventions;
return duplicates across environments;
be replaced.

Internal IDs should remain stable even if the integration changes.

The operator is part of the product context

A data package is usually not globally valid simply because it says “5 GB.”

It belongs to an operator and market context.

A basic relationship might look like:

countries
    ↓
operators
    ↓
products

The operator itself should also have an external mapping.

operators
---------
id
country_code
name
provider_id
external_operator_id
active

This lets you distinguish internal operator identity from provider-specific representation.

If two providers support the same operator, you can later model multiple provider mappings without duplicating your entire conceptual catalogue.

Avoid using JSON for everything

JSON columns are tempting.

You can store:

{
  "anything": "the provider returns"
}

and ship the feature quickly.

The problem appears later when you need queries such as:

Find all active data bundles
with at least 5 GB
valid for at least 14 days
for operator X.

Structured fields are much easier to work with.

A good compromise is:

structured columns/tables for business-critical attributes;
JSON for sparse provider-specific metadata.

For example:

products.metadata

might safely contain:

{
  "provider_label": "Promo Summer 10GB",
  "campaign_code": "SUMMER26"
}

while product type, allowance, currency and validity stay queryable.

Preserve the raw provider payload

Structured data and raw data solve different problems.

When ingesting a provider catalogue, it can be useful to retain the original payload separately:

provider_product_snapshots
--------------------------
id
provider_id
external_product_id
payload_json
received_at

This is valuable when debugging:

Why did this product suddenly become inactive?

or:

Did the provider actually send a different validity period yesterday?

The raw snapshot is evidence.

Your normalized tables are application state.

Do not confuse the two.

Catalogue ingestion should be idempotent too

Provider catalogues are often refreshed repeatedly.

An importer should not create a new product every time it sees the same external SKU.

A typical upsert key might be:

(provider_id, external_product_id)

Then:

if exists:
    update normalized fields
else:
    create product

You also need a strategy for products that disappear.

Options include:

mark inactive after a successful full catalogue sync;
use provider-specific deletion signals;
expire products not seen for a defined period.

Do not simply delete records immediately.

Historical transactions may still reference them.

Transactions should snapshot the purchased product

This is critical.

Imagine a customer buys:

5 GB
valid for 30 days

Tomorrow, the provider changes the same SKU to:

4 GB
valid for 30 days

If your transaction history dynamically joins the current product table, yesterday's receipt may appear to change.

Instead, snapshot the relevant product attributes at purchase time.

For example:

{
  "transaction_product": {
    "name": "5 GB Data",
    "type": "data_bundle",
    "allowances": [
      {
        "type": "data",
        "amount": 5,
        "unit": "GB"
      }
    ],
    "validity": {
      "value": 30,
      "unit": "day"
    }
  }
}

Historical transactions should describe what was purchased then.

Not what the catalogue says now.

A practical model

The result can stay relatively small:

providers
countries
operators
products
product_allowances
provider_product_snapshots
transactions
transaction_product_snapshots

You do not need fifty tables.

You also do not need to store the entire business model inside one products.json.

The core idea is to separate:

identity

from

commercial price

from

recipient value

from

allowances

from

validity

from

provider-specific metadata.

Once those concepts are separate, airtime and complex bundles can live in the same catalogue without pretending they are the same product.

AI disclosure: This article was prepared with AI assistance. The publishing editor should review the schema examples and factual accuracy before publication.

MobileTopUP: Designing a Safer Mobile Recharge Flow

MobileTopUP — Tue, 08 Sep 2026 16:29:03 +0000

A mobile recharge form looks deceptively simple:

choose a country;
enter a phone number;
choose an amount;
pay.

From an engineering perspective, however, the interesting part is everything that has to happen between steps two and four.

A reliable recharge flow needs to answer several different questions:

Is the phone number structurally valid?
Which country context applies?
Is the number eligible for recharge?
Which products are available right now?
Is the price still valid?
What happens if the user clicks Pay twice?
What happens if a provider times out after accepting the request?
How do we show a useful status without pretending that an asynchronous operation is instantaneous?

This article uses a generic prepaid recharge system as the example. The same design principles apply to many transaction flows where the user selects a destination, receives a quote, confirms it, and triggers an external operation. For additional product context, this is how the user-facing mobile recharge flow is structured.

1. Treat phone-number input as data normalization, not a text field

A common first implementation stores whatever the user typed:

07700 900123
+44 7700 900123
0044 7700 900123

Those may represent the same logical number.

The application should therefore distinguish between:

the user's display input;
normalized number data used internally.

A reasonable internal representation might be:

{
  "country": "GB",
  "calling_code": "44",
  "national_number": "7700900123",
  "normalized": "+447700900123"
}

Normalization should happen before downstream eligibility checks.

Do not make a giant custom regex your only validation mechanism. Phone numbering plans are more complicated than a handful of prefixes, and they change over time.

A phone-number library can help with parsing and structural validation, but even a valid-looking number is not necessarily rechargeable.

That is a separate question.

2. Separate syntax validation from recharge eligibility

These are different checks.

A number can be:

syntactically valid;
plausible for a country;
assigned to a real subscriber;
connected to a supported network;
eligible for a specific recharge product.

A frontend validator can answer only some of those questions.

For example:

"Does this look like a valid UK mobile number?"

is not equivalent to:

"Can our current recharge provider deliver this £10 product to this number?"

Eligibility belongs closer to the product/provider layer.

A useful flow is:

User input
   ↓
Normalize number
   ↓
Structural validation
   ↓
Eligibility lookup
   ↓
Available products

Each stage should have its own failure message.

Invalid phone number is useful when parsing fails.

It is misleading when the number is perfectly valid but the operator is unsupported.

3. Do not rely on prefixes as your source of truth for the current operator

It is tempting to map number prefixes directly to carriers.

That can work as a hint.

It should not be treated as authoritative.

Mobile number portability means a number may move between networks while keeping the same number.

This matters because recharge products are normally operator-specific.

If your provider offers a lookup or eligibility endpoint, prefer that over hard-coded prefix assumptions.

A better model is:

{
  "number": "+447700900123",
  "operator": {
    "id": "provider-operator-id",
    "name": "Example Mobile"
  },
  "lookup_source": "provider",
  "checked_at": "2026-09-08T16:00:00Z"
}

The timestamp matters because catalogue information is not permanent.

4. Generate a quote, not just a product selection

Once the user chooses a recharge product, create a quote snapshot.

Do not assume that the product record currently stored in your database will still describe the transaction later.

A quote should capture the commercial state the user is about to accept.

For example:

{
  "quote_id": "q_123",
  "recipient": "+447700900123",
  "product_id": "prod_456",
  "product_name": "10 GBP Airtime",
  "recipient_value": "10.00",
  "recipient_currency": "GBP",
  "fee": "0.49",
  "charge_total": "10.49",
  "charge_currency": "GBP",
  "expires_at": "2026-09-08T16:05:00Z"
}

The confirmation screen should render from the quote.

Not from several unrelated API responses.

Not from frontend state assembled during the previous five minutes.

The quote is the contract between product selection and payment.

5. Put a real confirmation boundary before execution

A good confirmation screen answers:

Which phone number will receive the recharge?
Which operator was identified?
What exactly will the recipient receive?
How much will the sender pay?
Which currency is used?
What fee is included?

This is particularly important for irreversible or difficult-to-reverse operations.

The final button should mean:

Execute this exact quoted transaction.

It should not mean:

Recalculate everything and then do whatever the newest API response suggests.

If a quote has expired, request a new quote and ask the user to confirm again.

That is slightly less convenient.

It is much safer.

6. Protect the execution endpoint with idempotency

Double-clicks happen.

Mobile browsers retry requests.

Reverse proxies retry requests.

Users refresh pages when they think something is stuck.

A transactional endpoint should assume that the same logical request can arrive more than once.

For example:

POST /recharges
Idempotency-Key: 7fc14a8c-...

On the server:

if idempotency_key already completed:
    return previous result

if idempotency_key currently processing:
    return current transaction state

otherwise:
    create transaction
    begin processing

The database should enforce the uniqueness rule, not just application code.

Without that protection, an impatient double-click can become two real top-ups.

7. Model processing as a state machine

Avoid representing the whole transaction with a single boolean such as:

success = true / false

External transaction systems have intermediate and ambiguous states.

A more useful model is:

created
quoted
payment_authorized
submitted
processing
succeeded
failed

You may need additional states depending on the payment and provider architecture.

The important property is that transitions are deliberate.

For example:

submitted → processing
processing → succeeded
processing → failed

but perhaps not:

succeeded → processing

without an explicit reconciliation operation.

State transitions should be logged.

8. Treat timeout as “unknown,” not automatically “failed”

This is one of the most important external-API lessons.

Suppose your application submits a recharge.

The provider processes it successfully.

The response is lost because the request times out.

Your server sees:

TimeoutException

What happened?

You do not know.

Retrying immediately may submit the same recharge twice unless the provider also supports idempotency.

The correct flow is usually:

request timed out
      ↓
mark transaction as uncertain/processing
      ↓
query provider status or reconcile
      ↓
retry only when safe

A network failure describes the communication channel.

It does not necessarily describe the business transaction.

9. Design the UI around honest states

Users do not need every internal state.

They do need truthful ones.

For example:

Processing
We have submitted the recharge and are waiting for final confirmation.

Completed
The provider confirmed successful delivery.

Failed
The recharge was not completed.

Avoid showing “Failed” simply because one HTTP request timed out.

Likewise, avoid showing “Completed” because payment succeeded if the recharge itself is still processing.

Payment status and fulfilment status are separate dimensions.

10. Keep an audit trail

For a transaction system, debugging from the current database row is not enough.

Useful events include:

quote_created
payment_authorized
recharge_submitted
provider_response_received
status_reconciled
recharge_completed

Store timestamps and relevant external identifiers.

This helps with:

customer support;
reconciliation;
debugging;
duplicate detection;
provider disputes;
operational monitoring.

Sensitive payment data should obviously not be dumped into logs.

Log identifiers and state changes, not secrets.

A safer recharge flow in one diagram

Conceptually:

Phone input
    ↓
Normalize
    ↓
Validate structure
    ↓
Check eligibility/operator
    ↓
Load supported products
    ↓
Create expiring quote
    ↓
User confirms
    ↓
Authorize payment
    ↓
Submit once with idempotency
    ↓
Processing / reconciliation
    ↓
Final status

None of these ideas is unique to mobile recharge.

The same pattern works for many transactional applications.

The broader lesson is that a safe flow separates:

input validation, eligibility, quoting, confirmation, execution, and final settlement.

When those responsibilities get compressed into one “Submit” handler, edge cases become expensive very quickly.

AI disclosure: This article was prepared with AI assistance. The publishing editor should review the technical examples and factual accuracy before publication.