Skip to content
English
Customer portal
Go to reloadly.com
  • There are no suggestions because the search field is empty.

How the auto refund feature works

Failed top-ups used to mean waiting on delayed manual refunds sometimes for days. The auto refund feature eliminates that wait entirely. When a top-up fails on the operator's end, your wallet balance is restored automatically. No ticket needed, no waiting.

The three top-up statuses

Every top-up made via the Reloadly API will resolve to one of three statuses. Understanding what each one means is key to handling outcomes correctly in your integration.




PROCESSING — The top-up has been submitted but the final confirmation from the airtime operator hasn't come back yet. This is expected for some operators that have asynchronous delivery pipelines.

SUCCESSFUL — The operator confirmed delivery. The recipient's phone has been credited.

REFUNDED — The operator was unable to process the top-up. The auto refund feature has automatically returned the deducted amount to your Reloadly wallet balance.

Making a top-up and tracking its status

The recommended pattern for production integrations is to use the async top-up endpoint, which returns a transaction ID immediately — then poll the status endpoint to check the outcome.


Integration recommendations

  1. Always use the async top-up endpoint (/topups-async) in production. It returns a transaction ID immediately without blocking your flow while waiting on operator confirmation.
  2. Store the transactionId from every top-up response. You'll need it to poll the status endpoint and reconcile outcomes in your records.
  3. Implement exponential backoff when polling — start at a few seconds and increase the interval. Most operators confirm within minutes, but some may take longer.
  4. Handle REFUNDED status in your UI explicitly — let end users know the top-up didn't go through and their balance has been restored, rather than leaving them in the dark.
  5. Use the customIdentifier field to tag each top-up with your own internal reference. This makes reconciliation much easier when querying transactions later.