This guide is designed to stand on its own as an educational reference. It separates technical concepts, commercial outcomes and policy considerations so readers can reason about the system rather than memorize terminology.
Airtime is a fulfilment problem
From a user's perspective, an airtime reward looks simple: receive credit on a mobile number. Behind the scenes, the platform must identify the destination network, choose a supported product, submit a provider transaction, receive a provider reference and determine whether the top-up actually succeeded.
Resolve before you send
Mobile numbers can be portable between networks, product catalogues vary by country, and denominations can differ by provider. A robust system validates the destination and eligible product before creating a fulfilment request. Static assumptions can create failed or misrouted transactions.
Use idempotency
If a request times out, the platform may not know whether the provider received it. Retrying blindly can create duplicate value. Idempotency keys let the platform and provider recognize repeated attempts for the same logical reward.
Callbacks need verification
Providers may send asynchronous callbacks to report success, failure or cancellation. Those callbacks should be authenticated according to provider documentation and reconciled against the original request. Unknown or malformed callback states should not silently become success.
Reconciliation closes the loop
Local application state, provider response and financial or inventory records should agree. Scheduled reconciliation can detect transactions that remained pending, callbacks that were missed or provider statuses that changed later.
Support needs evidence
When a user reports a missing top-up, support should be able to see the reward decision, destination details in appropriately protected form, provider request identifier, provider response and final reconciled state. Observability is part of the product.