DEV Community: MobileTopUP

MobileTopUP: Designing a Reliable Recharge Transaction Workflow

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

Distributed transactions become interesting exactly when the happy path stops being reliable.

A basic recharge implementation might look like this:

charge card
    ↓
call recharge provider
    ↓
return success

In a local test environment, that can appear perfectly adequate.

Production introduces:

duplicate requests;
timeouts;
delayed provider responses;
asynchronous status updates;
partial failures;
process crashes;
payment success followed by fulfilment uncertainty;
users refreshing the page;
workers retrying jobs.

The underlying prepaid mobile top-up use case is a useful example because a single user action can involve payment, external fulfilment, asynchronous confirmation and an operation that should never be executed twice accidentally.

The solution is not to add more try/catch blocks.

The transaction needs an explicit lifecycle.

Start with a transaction record before external execution

Do not wait until the provider responds successfully before creating a database record.

Create the transaction first.

For example:

{
  "id": "txn_123",
  "status": "created",
  "recipient": "+447700900123",
  "quote_id": "q_456",
  "idempotency_key": "abc-123",
  "created_at": "..."
}

Now every later operation has an internal identity.

That identity can be used in:

logs;
payment metadata;
provider metadata;
support tools;
reconciliation jobs.

A transaction that fails midway still exists.

That is valuable.

Use a state machine instead of a success flag

A boolean cannot represent asynchronous processing well.

This:

success = null

quickly becomes ambiguous.

A state model is clearer.

For example:

created
payment_pending
payment_authorized
submitted
processing
succeeded
failed

Depending on the architecture, you might also need:

payment_failed
cancelled
refunded
manual_review

The exact state names matter less than defining what each one means.

For every state, ask:

What must already have happened?
Which transitions are allowed?
Is the state terminal?
Can a worker safely retry from here?

Idempotency belongs at the transaction boundary

Imagine this request:

POST /api/recharges

The user double-clicks.

Or the frontend retries because the first response takes too long.

Without protection:

Request 1 → recharge
Request 2 → recharge

The customer may pay twice or the recipient may receive duplicate value.

Instead, require an idempotency key:

Idempotency-Key: 70356c3a-...

Store it with a unique database constraint.

Pseudo-code:

existing = find_transaction(idempotency_key)

if existing:
    return existing

transaction = create_transaction(idempotency_key)
process(transaction)

The unique constraint matters because two concurrent application workers can otherwise both pass an application-level “does this exist?” check.

Correctness should survive concurrency.

Do not blindly retry an ambiguous provider request

Suppose you send:

POST /provider/recharge

The provider completes the recharge.

Your connection drops before the HTTP response arrives.

From your application's perspective:

request timeout

From the provider's perspective:

recharge succeeded

If your retry policy says:

timeout → retry immediately

you may create a duplicate.

A timeout means:

We do not know the outcome.

That is different from:

The operation failed.

If the provider supports idempotency, use it.

If it provides transaction lookup, query the original request.

If it sends asynchronous callbacks, wait for the callback within a reasonable reconciliation window.

Retries need business context.

Give every provider operation a correlation identifier

A useful integration keeps both sides traceable.

For example:

internal transaction:
txn_123

provider request reference:
mobiletopup-txn_123

provider transaction:
ext_987

Store the provider transaction ID as soon as you receive it.

Then support and reconciliation processes can move between:

your system ↔ provider system

without searching by amount and timestamp.

Correlation IDs are cheap.

Debugging without them is not.

Separate payment state from recharge state

One of the most important modeling decisions is not to treat payment success as transaction success.

Consider:

Payment: authorized
Recharge: processing

That is a perfectly valid intermediate state.

Likewise:

Payment: failed
Recharge: not submitted

is very different from:

Payment: captured
Recharge: provider rejected

A transaction may therefore contain separate dimensions:

{
  "payment_status": "captured",
  "fulfilment_status": "processing"
}

The overall user-facing status can be derived from those states.

Do not destroy useful information by compressing both into one column too early.

Make asynchronous completion normal

External fulfilment often works better as an asynchronous workflow.

A simplified architecture:

API request
   ↓
create transaction
   ↓
authorize/capture payment
   ↓
enqueue recharge job
   ↓
provider submission
   ↓
processing
   ↓
webhook or polling
   ↓
final state

The API does not need to keep an HTTP connection open for the entire provider lifecycle.

The frontend can poll:

GET /api/recharges/txn_123

or receive updates through another mechanism.

This also makes temporary provider slowness easier to absorb.

Webhooks need the same defensive engineering

A webhook can arrive:

once;
twice;
out of order;
much later than expected.

Treat webhook processing as idempotent.

For example:

provider event ID
+
unique constraint

If the same event arrives twice, processing it twice should not produce duplicate side effects.

Also validate the webhook's authenticity using the provider's supported verification mechanism.

Do not trust an arbitrary public POST request simply because it contains a transaction ID.

Add reconciliation even if webhooks exist

Webhooks are useful.

They are not magic.

Events can be delayed or lost because of:

endpoint downtime;
configuration mistakes;
provider incidents;
networking problems;
internal processing bugs.

A reconciliation worker can periodically find transactions such as:

status = processing
AND updated_at < now - threshold

and query the provider.

This gives the system a recovery path that does not depend on every asynchronous event arriving perfectly.

Store events, not only the latest state

A row that currently says:

status = succeeded

does not explain how it got there.

An event history might say:

12:00:01 transaction_created
12:00:05 payment_authorized
12:00:06 provider_submitted
12:00:07 provider_acknowledged
12:00:24 provider_processing
12:00:32 recharge_succeeded

That timeline is enormously useful.

You can implement it with:

a dedicated transaction-events table;
structured application events;
or an appropriate event-sourcing approach where warranted.

You do not need full event sourcing merely to maintain an audit trail.

Retries should be state-aware

A retry policy such as:

retry every exception three times

is dangerous for financial or fulfilment operations.

Instead, decide by operation type.

A read-only provider lookup?

Usually safe to retry.

Submitting a recharge with provider idempotency?

Potentially safe to retry using the same key.

Submitting without provider idempotency after an ambiguous timeout?

Reconcile first.

Retry logic belongs to the business workflow, not just the HTTP client.

Design for support from day one

Operational support will eventually need answers to questions such as:

Did the payment complete?
Was the recharge submitted?
What external ID did the provider return?
When was the last provider status check?
Did a webhook arrive?
Was the transaction retried?
Which product snapshot was used?

If answering those questions requires reading raw production logs manually, the system is harder to operate than it needs to be.

Build an internal transaction timeline.

Even a simple one pays for itself quickly.

Reliability comes from reducing ambiguity

The final architecture might resemble:

Client
  ↓
Create transaction + idempotency key
  ↓
Payment
  ↓
Queue
  ↓
Provider submission
  ↓
Processing state
  ↓
Webhook / reconciliation
  ↓
Terminal status
  ↓
Audit history

The goal is not to eliminate every failure.

Distributed systems do not offer that luxury.

The goal is to make every failure land in a state the system understands and can safely recover from.

That is a much stronger guarantee than hoping the external API always returns 200 OK.

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

MobileTopUP: International Mobile Numbers — What Developers Should Validate and What They Shouldn’t Guess

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

Phone-number validation looks easy until an application becomes international.

At first, the form may accept something like:

5551234567

Then international users arrive.

Suddenly the system needs to understand:

07700 900123
+44 7700 900123
0044 7700 900123
(07700) 900 123

The problem becomes even more interesting when the number is not just a contact field but the destination of a transaction.

A mobile recharge system is a good example because a syntactically valid number is not enough. The system may also need to determine whether the number is supported, which operator serves it, and which products can be delivered.

The key engineering lesson is to avoid collapsing all of those checks into a single boolean called valid.

There is more than one kind of validity

Consider these questions:

Can the input be parsed?
Does it match a plausible numbering pattern?
Is it possible within the selected country?
Is it currently assigned?
Which network currently serves it?
Does the recharge provider support it?
Which products are eligible?

Those are seven different questions.

A typical frontend library may help answer the first few.

It cannot necessarily answer the last four.

This is why:

{
  "valid": true
}

is often a poor API model.

A richer response is easier to reason about:

{
  "parseable": true,
  "plausible": true,
  "normalized": "+447700900123",
  "eligibility": "supported",
  "operator": {
    "id": "op_123",
    "name": "Example Mobile"
  }
}

Normalize once, format many times

Internally, choose one canonical representation.

For international mobile numbers, an E.164-style form is commonly useful:

+447700900123

E.164 numbers contain the country calling code and national significant number and are limited to 15 digits.

The normalized form is useful for:

database uniqueness;
provider APIs;
logging identifiers;
transaction records;
comparisons.

The user-facing representation can be formatted differently:

+44 7700 900123

That is presentation.

Do not store presentation formatting as identity.

A good rule is:

Normalize for machines. Format for humans.

Country context matters when parsing local input

The input:

07700900123

does not carry an explicit international country code.

Your parser needs context.

If the user selected United Kingdom, the application can interpret the local format in that context.

If no country is known, guessing becomes dangerous.

This is why many international phone forms work best with:

Country selector
+
Phone number input

instead of trying to infer everything from one text field.

The selected country is parsing context. It should not automatically be treated as the user's physical location. This distinction becomes particularly important in international mobile top-up, where the sender may be in one country while the prepaid number being recharged belongs to another market.

Do not validate phone numbers with one homemade regex

A regex can enforce simple syntax.

For example:

^\+[1-9]\d{7,14}$

can help check a normalized international representation.

It cannot tell you whether a number is plausible for a specific country's numbering plan.

It certainly cannot tell you whether the number currently belongs to a supported operator.

A dedicated phone-number library is usually safer for parsing and country-specific structural checks.

Regex still has a role.

It just should not pretend to be a numbering-plan database.

Do not guess the current operator from the prefix

Historically, number ranges often indicated the original operator.

That makes prefix tables tempting.

For example:

if number starts with X:
    operator = Carrier A

The problem is mobile number portability.

A subscriber may move to another network while keeping the same number.

A prefix can therefore be useful metadata without being authoritative current-routing information.

If your business process needs the actual operator, use an authoritative lookup available through your provider or another appropriate source.

This distinction matters in recharge systems because available products are commonly tied to the current receiving network.

Parsing success does not prove ownership

A perfectly formatted number can belong to someone else.

Phone-number validation and phone-number verification are different processes.

Validation asks:

Does this number look structurally valid?

Verification asks:

Can this user prove control of this number?

Verification commonly requires a separate mechanism such as an OTP.

Not every product flow requires ownership verification.

For example, a user may legitimately be sending a recharge to a family member.

The application should therefore decide intentionally whether it needs:

number validation;
ownership verification;
recipient eligibility.

Do not implement one and assume you have all three.

A number can be valid but unsupported

Suppose this number parses correctly:

+XXXXXXXXXXXX

The recharge provider may still respond:

{
  "supported": false
}

Possible reasons include:

unsupported country;
unsupported operator;
unsupported number type;
provider coverage limitations;
temporary catalogue availability.

The user message should reflect the actual problem.

Bad:

Invalid phone number.

Better:

This number appears valid, but recharge is not currently available for this network.

Error semantics matter.

Store both normalized and relevant resolved data

A recharge transaction might snapshot:

{
  "recipient": {
    "input": "07700 900123",
    "normalized": "+447700900123",
    "country": "GB",
    "operator_id": "op_123",
    "operator_name": "Example Mobile"
  }
}

Do you need to store the original user input?

Maybe.

It can help with support and debugging.

But downstream transaction logic should generally use the normalized form.

Also consider whether the operator should be stored as a transaction snapshot.

If operator metadata changes later, historical transactions should still describe what the application believed at execution time.

Separate validation errors by layer

A clean API can expose different failure classes.

For example:

NUMBER_PARSE_ERROR
NUMBER_NOT_PLAUSIBLE
COUNTRY_NOT_SUPPORTED
OPERATOR_NOT_SUPPORTED
NUMBER_NOT_ELIGIBLE
PROVIDER_LOOKUP_FAILED

That makes frontend messages clearer and observability much better.

If every problem becomes:

400 Invalid number

you lose information.

Support teams lose information too.

Never use client-side validation as the execution guard

Frontend validation exists for user experience.

Server-side validation exists for correctness.

A malicious or simply outdated client can bypass browser checks.

The execution path should validate the normalized number and current eligibility again before creating the final transaction.

Especially when the number is the destination of something with monetary value.

Think in layers

A useful mental model is:

Raw input
   ↓
Parsing
   ↓
Normalization
   ↓
Structural plausibility
   ↓
Provider/operator lookup
   ↓
Recharge eligibility
   ↓
Product eligibility

Each layer answers a different question.

Keeping those questions separate avoids both false confidence and confusing error messages.

International phone numbers are not unusually difficult.

They simply expose a broader software-design principle:

Do not use one validation flag to represent several independent business facts.

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

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.