VTU App Architecture: Credits, Retries and Reconciliation

Most people building a VTU platform start with the app. That is understandable. The app is the part customers see, and it is the part that feels like the product.

But the app is the shopfront. The business lives underneath it, in how you handle balances, failures and reconciliation. Get those wrong and no amount of polish on the app will save you.

This is a practical architecture guide for anyone building an airtime, data and bill payments platform. It is drawn from what we learned building CIP TopUp, and it focuses on the parts that decide whether you lose money quietly.

What you are really building

A VTU platform is a financial system that happens to sell airtime. It holds balances, moves money, depends on third parties that fail, and must be able to explain, after the fact, exactly what happened to every transaction.

That last part is the one beginners underestimate. It is not enough to send a request and read the response. You need a system of record you can reconcile against, and a way to resolve transactions that end in an unknown state.

Once you accept that, the architecture becomes clearer.

The core components

A production VTU platform is not a single app. It is usually a set of services, each with a clear job. The names differ between teams, but the responsibilities are consistent.

• API and orchestration layer. What your app, website and agents talk to.
• Transaction services. They handle top-ups, bill payments and credit movements.
• A credits and balance system. It records every balance change. This is the source of truth.
• Provider adapters. The integrations with the networks, billers and gateways you depend on.
• A fraud detection service. It watches for anomalous transaction patterns.
• A problem detection service. It watches the system itself, so you find issues before customers report them.
• A reconciliation worker. It compares what you believe happened against what providers actually say happened, and corrects the difference.

You can build a simpler version at the start, but keep these responsibilities separate in your head. They fail differently and need to be reasoned about separately.

Credits and balance, done properly

The balance is the part of the system that other people's money depends on. Treat it accordingly.

Never update a balance as a loose number. Every change should be a recorded entry. If a customer's balance moves, there should be a record that explains why, tied to a specific transaction. When a dispute happens, that record is what protects you.

Make balance changes atomic. A check of a balance and a change to it must not be separable. If two requests can both check the balance before either changes it, you have a race condition, and race conditions let people overdraw or double-spend.

Make the balance transactional. Either the whole operation succeeds or none of it does. Partial updates are how balances drift away from reality.

Give the balance one owner. Do not let multiple services write to it independently. One service owns balance changes, and everything else asks it.

If you get this layer right, most of the rest of the system becomes easier to reason about.

Idempotency and retries

Networks are unreliable. You will retry requests, and so will your clients. Without care, retries create duplicate transactions.

The fix is an idempotency key. Every transaction gets a unique key, and the system guarantees that the same key never results in two top-ups or two balance changes. A retry with the same key either returns the original result or is safely ignored.

A few rules that save a lot of pain.

• Generate the idempotency key once, at the start of the transaction, and reuse it across retries.
• Store the key with the transaction so you can detect duplicates later.
• Make retries safe by design, not by hoping they do not happen.
• Never let a retry create a second debit.

Idempotency is not optional in a payments system. It is the difference between a retry that recovers and a retry that duplicates.

The timeout trap

This is the most expensive mistake in a VTU platform, and it hides in your logs.

When you send a top-up to a provider, three things can happen. The provider clearly succeeds, the provider clearly fails, or you get no clean answer at all. That last case is a timeout.

The trap is treating a timeout as a failure. When a request times out, the customer may already have been credited. If you refund them, you have given their money back and they still got the airtime, and the provider still charges you. Do that at scale and you quietly lose your entire margin.

The rule is simple to state and hard to build correctly.

Never treat no answer as failed. Treat it as unknown, and resolve it.

In practice that means the transaction enters an ambiguous state, a resolver checks the true outcome with the provider, and only genuinely failed transactions are reversed automatically. Ambiguous transactions that cannot be resolved are surfaced to support with full context, not silently refunded.

We wrote the full story of how this plays out in production in the CIP case study.

The reconciliation loop

A single successful API response is not the truth. The truth is what you and your providers agree on after the fact.

Reconciliation is the loop that compares your records against your providers and your gateway, and corrects any difference. It catches the transactions that ended in an unknown state, the ones that were credited late, and the discrepancies that would otherwise grow silently.

Build reconciliation early, not after your first incident. It is much harder to retrofit than to design in.

A useful mental model: your system should always be able to answer, for any transaction, what you believe happened, what the provider says happened, and why the two differ if they do.

Circuit breakers

Provider downtime is not an edge case. It is a normal Tuesday. The question is whether your platform degrades gracefully or collapses with the provider.

The classic solution is the circuit breaker, described well by Microsoft's Azure Architecture Center. A circuit breaker has three states.

• Closed: normal operation, calls pass through, and you count failures.
• Open: too many recent failures, so calls fail fast instead of piling up and exhausting your resources.
• Half-open: after a cool-down, a few trial requests are allowed through. If they succeed, you close the circuit. If they fail, you re-open it.

Two details matter in a VTU platform. Run a breaker per provider, so one bad network does not stop you selling another network's data. And alert on state changes, so your problem detection service and your team know when a breaker opens, rather than learning about it from angry customers.

Security basics

A platform that moves money is a target. A few fundamentals go a long way.

• Validate everything on the server. Client-side validation is a convenience for honest users, not a security control.
• Reject non-positive and malformed amounts. Something as simple as a negative amount can invert your arithmetic and credit a customer instead of debiting them.
• Make money movement atomic and idempotent. This is what protects you from race conditions and double-spends.
• Log and audit. When something anomalous happens, you need to reconstruct what was sent, when, and what the system did.
• Watch behaviour, not just requests. A fraud detection service whose job is to notice when activity stops looking human is worth more than any single validation rule.

You cannot imagine every attack. Build the system to assume the worst.

Build vs buy

You can build all of this yourself, and there are good reasons to. You can also skip most of it.

If you use a white-label or merchant platform, someone else owns the credits system, the reversal logic, the reconciliation and the circuit breakers. That is a legitimate shortcut, especially if your strength is selling rather than engineering. CIP Topup for merchants is exactly that offering from us. If you would rather build on top of an existing integration, the CIP API documentation shows how the pieces fit together.

The important thing is to know which you are choosing, and to make sure whoever runs the infrastructure has actually solved the timeout trap and reconciliation. Ask them how. The answer tells you whether your money is safe.

FAQ

What is the most important part of a VTU platform? The credits and balance system, plus reconciliation. The app is the shopfront. The balance and the reconciliation loop are the business.

Why is idempotency important? Because networks are unreliable and retries are unavoidable. Idempotency keys make retries safe and prevent duplicate top-ups or double debits.

What should happen when a transaction times out? It should be marked unknown, not failed, then resolved with the provider. Only genuinely failed transactions should be reversed.

Do I need a separate fraud detection service? At small scale you can start with strong validation and logging. As you grow, a dedicated service that watches for anomalous patterns becomes important.

Can I skip reconciliation if my provider is reliable? No. Even reliable providers produce unknown states and late credits. Reconciliation is how you find them.

Should I build or buy? Build if your advantage is engineering and you want full control. Buy if your advantage is selling and you would rather not maintain a financial system. Either can work. Understand the trade.

Related reading

• How to start a VTU business in Nigeria.
• How to choose a VTU API provider.
• Team Darphiz, How we built CIP TopUp.

Get the hard parts handled for you

Credits, retries, the timeout trap and reconciliation are not optional, and they are not quick to get right. CIP Topup for merchants gives you a website, an app and an agent network on infrastructure where we have already solved them.

We built this and we know the risks. Build with us.

Request your own VTU platform →