A practical top-up integration should answer three separate questions: what exactly is the customer buying, has the operator delivered it, and where is the money now? Design airtime and mobile top-up API orchestration around those questions—not simply around forwarding recharge requests. For founders, product leaders and operations teams, the implementation priority should be a controlled transaction lifecycle with explicit product semantics, recoverable uncertainty and traceable financial movements.
1. Define the Recharge Product Before Selecting a Route
Start with a canonical offer record: destination country, operator, recharge type, recipient requirements, denomination or permitted range, currency, bundle allowance and validity where applicable. Keep supplier identifiers in separate mappings. Ding explicitly requires SkuCode values returned by GetProducts and warns that products can be discontinued. Treat catalog refresh as an operating process, not a one-time import during development. ([dingconnect.com](https://www.dingconnect.com/Api?utm_source=openai))
Make the amount basis explicit. Reloadly distinguishes standard amounts from destination-currency amounts through useLocalAmount and supportsLocalAmounts, with separate local limits and discounts. Its support documentation also distinguishes Portal restrictions from API behavior: local-value entry through the Portal requires a matching account currency, while the API supports local-value requests regardless of account currency. Do not turn a Portal limitation into a backend validation rule. ([support.reloadly.com](https://support.reloadly.com/how-do-i-know-which-operators-support-local-values-how-do-i-send-local-topups?utm_source=openai))
For orchestration, define equivalence before comparing price. A cash recharge, a data bundle and a PIN product should not share a route merely because they target the same operator. Require matching delivery characteristics, then snapshot the selected supplier product, amount basis, quoted cost and catalog retrieval time against the order. If refresh reveals a changed offer, revalidate rather than silently substituting it; DT One explicitly treats product and price updates as changes possible within a major API version. ([developers.dtone.com](https://developers.dtone.com/reference/versioning?utm_source=openai))
2. Model Delivery, Payment and Supplier Settlement Separately
Use separate state dimensions instead of a single paid-or-failed flag. A suggested delivery model is prepared, submitted, pending, delivered, failed and reversed, with an additional unresolved-submission condition for missing responses. Preserve the raw supplier status alongside your normalized state. DT One documents CONFIRMED and SUBMITTED as non-final, and notes that even COMPLETED can rarely become REVERSED. Your model must accommodate that correction without deleting history. ([developers.dtone.com](https://developers.dtone.com/reference/transactions-1?utm_source=openai))
Implement vendor-specific financial transitions. DT One documents available funds moving into holding when a transaction is created, capture on completion, release on cancellation or failure, and restoration after reversal. Reloadly’s current auto-refund guidance instead describes PROCESSING, SUCCESSFUL and REFUNDED outcomes, with failed top-up funds returned to the Reloadly wallet. Neither supplier-wallet event, by itself, establishes that you have refunded the customer’s original payment. ([developers.dtone.com](https://developers.dtone.com/reference/transactions-1))
A synchronous response also needs interpretation. DT One’s synchronous mode can wait up to 180 seconds, configurable on request, yet still return SUBMITTED rather than a final result. Its asynchronous mode returns earlier and uses callbacks or queries for the outcome. Build the customer experience around confirmed delivery state: show pending while confirmation is outstanding, and maintain a separate customer-refund workflow when delivery ultimately fails. ([developers.dtone.com](https://developers.dtone.com/reference/modes?utm_source=openai))
Let's map the integration before complexity grows.
Tell us which platforms need to connect. We'll help turn the workflow into a clear, reliable implementation plan.
Talk to iMingos ↗3. Recover Uncertain Submissions Without Creating Another Recharge
At your own API boundary, require a tenant-scoped order key and persist an immutable request fingerprint before submission. Reject reuse with a different recipient, product or amount. Create a durable supplier-attempt record before network I/O, then attach returned references. This is an architectural recommendation, not a claim that every vendor provides idempotent creation: Reloadly documents customIdentifier for transaction lookup, while DT One documents external_id for retrieval when a response is missing. ([docs.reloadly.com](https://docs.reloadly.com/airtime/Top-ups?utm_source=openai))
Distinguish a lost connection from a documented supplier rejection. After an ambiguous timeout, query the existing attempt using the references supported by that API; do not immediately submit another recharge through a second supplier. Conversely, Ding documents a specific ProviderTimedOut result after its 90-second processing limit as a failed transaction with no balance deduction. That explicit application result is different from your HTTP client losing its connection without receiving a result. ([dingconnect.com](https://www.dingconnect.com/Api?utm_source=openai))
Make failover an eligibility decision. An alternative route should require an equivalent product, adequate funding and evidence that the previous attempt cannot still deliver. If lookup remains inconclusive, move the order into an operations queue with an owner and next-check time. Do not interpret a customer-facing deadline as proof of failure: DT One documents that submitted transactions can remain unresolved for up to 24 hours before reaching COMPLETED or DECLINED. ([developers.dtone.com](https://developers.dtone.com/reference/transactions-1))
4. Combine Callbacks With Wallet and Transaction Reconciliation
Persist incoming callbacks durably, acknowledge quickly and apply transitions asynchronously. Reloadly documents at-least-once delivery, so duplicate callbacks are expected. Its guidance also states that callbacks held open longer than three seconds can be treated as consumed, and unsuccessful acknowledgments have a bounded retry policy. Design deduplication around the supplier transaction and event details, and prevent a delayed pending notification from overwriting a newer confirmed outcome. ([support.reloadly.com](https://support.reloadly.com/reloadly-webhook?utm_source=openai))
Keep a scheduled query path even when callbacks work. DT One explicitly recommends API queries after callback retries are exhausted. Reconciliation should compare internal attempts with supplier records, recover missed terminal states and identify supplier transactions missing internally. Use explicit time windows and pagination: DT One’s transaction-list endpoint defaults to the last 24 hours without date or external-ID filters and limits a specified date window to 24 hours. ([developers.dtone.com](https://developers.dtone.com/reference/callbacks?utm_source=openai))
Track supplier liquidity separately from customer balances. Poll available balance, forecast funding needs and set low-balance alerts; Reloadly exposes a balance endpoint for this purpose. In your own records, reserve expected supplier spend before dispatch so concurrent workers cannot all rely on the same cached balance. Treat that reservation as internal risk control, not a guarantee of supplier acceptance. Reconcile expected debits, actual costs and returned funds instead of relying only on successful-order counts. ([support.reloadly.com](https://support.reloadly.com/checking-your-balance?utm_source=openai))
5. Pin the API Contract and Test Operational Exceptions
Document each adapter’s API version, environment, authentication, amount semantics, submission mode, lookup options and callback behavior. Ding’s documented SendTransfer path uses V1; DT One likewise uses version-prefixed endpoints and distinguishes Standard API, UI SDK and DT Shop handling. Do not assume a hosted interface’s behavior applies to a direct integration. DT One also permits additive response and callback fields within a major version, so parsers should tolerate unfamiliar fields. ([dingconnect.com](https://www.dingconnect.com/Api?utm_source=openai))
Build an acceptance suite around lost responses, duplicate callbacks, callback-before-response ordering, insufficient supplier funds, expired offers, late completion and reversal. Use fault injection for cases the sandbox cannot generate. Treat validation as advisory rather than a delivery guarantee: Ding says ValidateOnly does not deduct funds, returns estimated pricing, and cannot always validate the recipient because some providers lack that facility. Record exactly what each test environment proves—and what still requires controlled production verification. ([dingconnect.com](https://www.dingconnect.com/Api?utm_source=openai))
For an iMingos implementation brief, define acceptance in operational terms: every submitted attempt is traceable, unresolved orders have owners, financial differences are explainable, and supplier changes cannot silently alter the purchased offer. Start with one supplier and a deliberately narrow catalog. Add routing alternatives only after the same recovery and reconciliation tests pass. The objective is not the largest connector list; it is a recharge service the product, engineering and operations teams can explain and control.
Frequently asked questions
Does a customer reference field guarantee idempotency?
No. Treat a reference as correlation unless the applicable API contract explicitly guarantees duplicate-request behavior. Reloadly documents customIdentifier for tagging and querying transactions; that alone does not establish safe replay semantics. Enforce order uniqueness in your own service. ([docs.reloadly.com](https://docs.reloadly.com/airtime/Top-ups?utm_source=openai))
Can the customer receive airtime in a different currency from the supplier wallet?
The amount basis depends on the supplier and operator. Reloadly supports destination-currency requests for operators with supportsLocalAmounts enabled, using useLocalAmount. Keep the requested local denomination separate from supplier cost and account currency. ([support.reloadly.com](https://support.reloadly.com/how-do-i-know-which-operators-support-local-values-how-do-i-send-local-topups?utm_source=openai))
Are webhooks enough to close every order?
Use them as the primary notification path, not the sole recovery mechanism. DT One documents bounded callback retries followed by API status queries. Keep a reconciliation job for missed notifications and unresolved attempts. ([developers.dtone.com](https://developers.dtone.com/reference/callbacks?utm_source=openai))
What should operations monitor first?
Prioritize unresolved-submission age, pending-order age, callback processing failures, low supplier balance and financial mismatches. Set thresholds by supplier and product rather than applying one universal completion deadline; documented processing behavior differs between synchronous and asynchronous flows. ([developers.dtone.com](https://developers.dtone.com/reference/modes?utm_source=openai))