Posts tagged: idempotency

Short answer. An airtime top-up timeout happens when an eTopup platform sends a recharge request to the operator’s charging system and receives no definite reply inside the response window. Because the subscriber may already have been credited, may not have been credited, or may still be sitting in an upstream queue, the platform records the sale under a separate pending-unknown status instead of guessing.

During that window, the ledger keeps the dealer’s float held in reservation, the POS terminal warns the retailer not to resubmit the sale, and any automated retry reuses the original client transaction reference and correlation ID. The charging adapter then settles the transaction through an intraday status query, an account-state check, or the T+1 charging CDR batch before it commits the debit or releases the hold. MoboGage EVD System implements this state machine across its charging adapter and day-close exception queue, with the exact IN or OCS interface scoped per project.

A retailer at a phone shop enters a subscriber’s MSISDN into an Android POS terminal, selects a 20-unit airtime bundle (an illustrative amount), and presses sell. The spinner runs on the screen. After ten seconds without a response from the network, the terminal displays “transaction timed out” while the customer is still standing at the counter waiting for a confirmation SMS that has not arrived. Unless the terminal blocks a repeat sale, most retailers do the obvious thing and press sell a second time.

If the first request actually reached the operator’s charging system, that second press credits the subscriber twice and debits the dealer twice. Conversely, if the first request dropped before reaching charging and the platform marks a timeout as a completed sale, the subscriber walks away with no airtime while the dealer absorbs an unrecovered debit. Either failure mode turns into a support ticket and a day-close reconciliation break. This guide walks through how an electronic top-up system handles that boundary from the initial packet on the wire to the exception line in the next morning’s finance pack.

Why an airtime top-up timeout is not a failed recharge

A socket timeout only reports that the waiting timer expired. Between the moment the request left the adapter and the moment the timer fired, several different things could have occurred inside the operator’s core network.

On the charging side, the node may have applied the balance credit and transmitted an acknowledgement that dropped on the return path. In other cases, the request is still queued inside an overloaded charging cluster because an evening promotion launched at 18:00 (illustrative time) and nationwide recharge traffic spiked simultaneously, or an intermediate load balancer reset the connection before the payload ever reached the charging interface. To the waiting POS terminal, all three network conditions produce the exact same silence.

Treating silence as a clean failure invites an immediate duplicate sale, whereas treating it as a success short-changes the subscriber whenever the packet died upstream. In the EVMS architecture we deploy, the charging adapter owns this state transition and isolates every unanswered recharge in pending-unknown until hard evidence arrives from the charging layer.

Four outcomes a recharge request can end in

That fourth row causes the hardest disputes. Teams building their first charging integration frequently overlook late responses, even though they are routine whenever an IN or OCS cluster drains a queue after a traffic burst. If the charging adapter discards a late response because the local timer already expired, the subscriber keeps free airtime that the platform recorded as failed, and an automated refund hands the dealer money back on a delivered top-up.

What has to be on the wire before a timeout happens

Safe timeout recovery is decided at protocol design time rather than inside a support queue.

One client reference and correlation ID per sale. When the retailer confirms the recharge, the POS app or partner API mints a unique idempotency reference. That identifier stays attached to every retry or subsequent status query and reversal for the life of the transaction. When talking to an Ericsson-style IN over UCIP, the charging adapter maps that client reference to its upstream correlation fields (originTransactionID paired with originHostName and an ISO 8601 originTimeStamp), whether the call uses Refill for voucherless recharge profiles or UpdateBalanceAndDate for direct balance adjustments. Subscriber numbers are normalised to E.164 format (country code without leading zero or plus sign) at intake so downstream lookups and CDR joins never miss on formatting.

A composite uniqueness constraint at the channel gateway. The gateway indexes every incoming sale on terminal_id (or partner_id) plus client_reference. When a panicked double press or a network retry submits the same pair a second time, the gateway returns the current state of the first transaction instead of opening a new charging session.

Strict payload matching on retries. Every retry must carry the identical request body. If a second request reuses an existing client_reference but alters the target MSISDN, denomination, or product code, the gateway rejects it immediately with a validation error so a single reference can never straddle two different refills.

Wallet reservation in integer minor units. The dealer wallet and credit ledger places a hold on the dealer’s float when the request leaves the gateway and only converts that hold into a final debit after charging confirms the credit. Storing and reserving balances in ISO 4217 integer minor units, including three-decimal Gulf currencies such as the Kuwaiti dinar (KWD), Bahraini dinar (BHD), and Omani rial (OMR) tracked to 1,000 fils or baisa, prevents rounding drift when reservations are held and later released.

Because some operator IN configurations reject a repeated originTransactionID inside a duplicate-detection window while others treat it as a fresh debit, engineers should verify the exact behaviour on the operator’s lab test bed using a forced timeout before go-live.

Inside the pending window, step by step

The timeline below shows how one unanswered recharge moves through the platform, using illustrative timings and unit amounts rather than figures from a live operator deployment.

When intraday queries still cannot get an answer before the retail wait window expires, the terminal does not leave the cashier staring at a spinning wheel indefinitely. After the configured cut-off, the POS transitions to a clear hold notice (“Unconfirmed: check exception queue before reselling to this number”), while the transaction moves into the back-office exception queue for overnight tracking. The dealer’s float reservation remains locked across the T+0 close so the balance cannot be spent twice, and the T+1 morning charging CDR or EDR file settles the record definitively by converting a matched recharge into a debit or releasing an unmatched hold.

Screen wording on the POS terminal is an operational control in its own right, because a generic “failed” banner invites an immediate repeat sale whereas a “waiting for confirmation” lock prevents duplicate credits.

When the charging platform cannot confirm a transaction by reference

Direct status polling works only when the upstream charging interface exposes a transaction lookup by correlation ID.

Indirect reads are the practical fallback. On UCIP-based IN platforms, verification relies on account queries when a Refill or UpdateBalanceAndDate call times out without a transaction-status RPC. The adapter issues a GetBalanceAndDate or GetAccountDetails request to inspect the subscriber’s current balance and service-fee expiry date, or queries refill history where the AIR software release exposes it. Indirect reads require care because a subscriber who places a voice call or receives a second recharge from another channel during the gap will shift the balance independently. Our UCIP and IN integration notes examine how those read calls behave under peak traffic.

Third-party aggregator and switch APIs are simpler to poll. Most expose a dedicated status endpoint indexed on the original request ID alongside a store-and-forward reversal queue, allowing the adapter to enqueue a reversal after its polling ceiling expires and wait for the switch’s asynchronous acknowledgement before releasing the dealer’s reserved float.

Whenever live queries cannot settle an ambiguous transaction during T+0, the operator’s charging CDR or EDR file serves as the final arbiter at T+1, which is why we treat the charging export as one of the three independent ledgers reconciled during day-close reconciliation.

Reversal, refund or no action

Operations teams sometimes mix up reversals and refunds during incident calls, even though the two actions follow completely different rules in a prepaid ledger.

A reversal is an automated protocol instruction generated by the platform to back out a recharge leg that never completed cleanly inside the allowed window. It travels with the original correlation ID (originTransactionID or switch reference) and, if the upstream charging platform supports reversals and has not yet allowed the credit to be spent, claws back the balance before releasing the dealer’s reservation.

A refund is a separate financial adjustment created after a transaction has already settled as successful. In prepaid airtime distribution, reversing subscriber credit hours later is rarely possible because the customer may already have consumed the balance on data, calls, or bundle renewals. Any dealer or customer refund therefore requires an explicit commercial policy, a cutoff window, and maker-checker approval from a second operator administrator.

No action (confirming the original sale as good) is the right resolution whenever the status query or the T+1 CDR file proves that the subscriber received the credit, regardless of the timeout message shown on the POS screen at the moment of sale.

How unknown top-ups show up at T+0 and T+1 day-close

Every timed-out recharge should enter the morning reconciliation pack with its age in hours, its assigned owner, and a specific resolution code rather than sitting inside a flat list of failed transactions.

Five explicit exception codes give operations teams a clear action queue. We separate pending-unknown, resolved-success-from-CDR (T+1 match converts hold to debit) from pending-unknown, resolved-no-credit-from-CDR (T+1 absence releases hold), alongside late-success, dealer-already-refunded (manual refund issued before late confirmation arrived), duplicate-attempt-blocked-by-reference (idempotency guard caught a repeat press), and reversal-sent, unacknowledged (awaiting upstream switch confirmation). Tracking the count of late-success, dealer-already-refunded incidents week over week reveals immediately whether support staff are refunding dealers before the T+1 CDR file has been checked.

If you are replacing an older platform, our EVMS migration playbook details how to drain in-flight pending-unknown transactions before cutover so they do not arrive in the new ledger as unlinked orphans.

Questions worth asking a vendor during a live test

Standard vendor demos run against a local simulator that answers in fifty milliseconds. During technical due diligence, ask the vendor to inject a ten-second network blackhole on the charging link and keep the retailer’s POS screen, the dealer wallet ledger, and the exception queue open while answering five questions:

• Which composite fields form the idempotency constraint for a recharge, and which component enforces it when a POS retries?
• What exact text appears on the retailer’s terminal during the pending-unknown window, and is repeat selling to the same MSISDN locked?
• How does the charging adapter reconcile a positive response packet that arrives after the local timeout timer has already fired?
• What fallback verification sequence runs when the operator’s IN or OCS does not support transaction status queries by reference?
• Which role can authorise a post-settlement dealer adjustment, within what time window, and how is maker-checker approval logged?

Our buyer’s checklist for an electronic voucher management system covers the wider RFP evaluation criteria across voucher vault custody, dealer hierarchy controls, and day-close reconciliation.

Where MoboGage EVD System fits

MoboGage EVD System is an electronic voucher management system and PINless eTopup platform engineered by MoboGage for mobile network operators and VAS distribution partners. Founded in 2007 (company-reported), MoboGage operates from its sole office and headquarters in Jaipur, India. As company-reported figures, its platforms support more than 1 million retailers across 17 countries delivered through regional channel partners. The platform runs serialised PIN vouchers and direct eTopup through one multi-tier dealer ledger, with the pending-unknown hold state, idempotent retry guards, and T+0 / T+1 CDR reconciliation workflows built into its charging adapter and day-close engine. Each charging interface (Ericsson-style UCIP, another IN or OCS protocol, or a third-party aggregator API) is scoped and tested per project on the operator’s test bed. Core terminology is indexed in our EVMS glossary, and anonymised deployment summaries are available on the case studies page.

If your operations team is troubleshooting reconciliation breaks from recharge timeouts or writing the technical specification for an upcoming platform tender, talk to the MoboGage team.

FAQ

What does “unknown status” mean for an airtime top-up?

An unknown status means the eTopup platform sent a recharge request to the operator’s charging system and received no definite success or reject before the response timer expired. Because the subscriber may or may not have been credited on the network side, the platform holds the transaction in pending-unknown with the dealer’s float reserved until a status query or the next charging CDR batch settles the outcome.

Should a timed-out top-up be retried?

A timed-out top-up should only be retried when the request carries the original client transaction reference and the exact same payload so the channel gateway and charging adapter recognise it as the same sale. Minting a new reference for a repeat attempt is the primary cause of double credits to the subscriber and double debits to the dealer wallet.

What is idempotency in an eTopup system?

Idempotency means submitting the same recharge request more than once produces the same result as submitting it once. In practice, the channel gateway enforces a composite uniqueness constraint on the terminal or partner ID plus the client-generated idempotency reference, returning the stored state of the first request whenever a duplicate arrives.

What is the difference between a reversal and a refund for airtime?

A reversal is an automated protocol message sent with the original reference to cancel an incomplete or timed-out transaction before the credit is treated as settled. A refund is a separate financial transaction raised after a completed sale, which is rarely practical for prepaid airtime once the subscriber has spent the balance on calls or data.

How long should a top-up stay pending?

A transaction should stay pending on the wire long enough for automated status queries to run, while the retailer’s POS screen closes into an unconfirmed hold message within the time a customer will reasonably wait at a counter. Any item still unresolved after the intraday polling window keeps its wallet reservation overnight and settles against the T+1 charging CDR file.

How do unknown top-ups affect dealer float?

An unknown top-up holds the dealer’s float in reservation rather than leaving it available or posting a final debit immediately. The reserved amount converts into a confirmed debit only when a late response, status query, or CDR match proves the recharge landed, and releases back to available float if charging confirms no credit occurred.