Handling Failed Transactions and Wallet Refunds

Sooner or later a customer will message you: "I paid, but I did not get my data." How you handle that moment decides whether they trust you or leave. This guide explains exactly what the platform does when a purchase fails, where to see it, and the few checks that stop you from refunding someone twice or missing a purchase that actually went through.

What happens when a purchase is made

Every purchase follows the same order, whether it comes from your website, the customer's API key or a bot:

• The platform creates a transaction record with the status Pending.
• It takes the amount from the customer's wallet.
• It asks your vending provider to deliver the airtime or data.
• If the provider confirms success, the transaction becomes Success.
• If the provider clearly says no, reports an error, or cannot be reached at all, the transaction becomes Failed and the money goes straight back to the customer's wallet.
• If the provider receives the order but never answers in time, the purchase is held while you check. See "When the provider does not answer" below.

That last step is automatic. The wallet history shows a credit with a description like "Auto-refund: MTN Data failed", the customer gets a notification, and the message they see says their wallet was refunded. You do not have to do anything.

Two cases where nothing is taken at all

If you have not connected a vending route for the service yet, the purchase is marked failed before any money moves, and the customer sees "Service not available yet. Please contact support." Nothing needs refunding. If you use a SIM Host route and no SIM slot is free, the purchase also fails and is refunded straight away.

Where to look

Open VTU Admin, then Insights, then Transactions. Each row shows the reference, customer, service, details, amount, the wallet balance before and after, the status and the date. You can search by reference, phone number or customer name, and filter by status or service. Click a row to expand it. You will see the provider's message, the request that was sent, the response that came back and any error. That expanded view is the first place to look whenever something goes wrong.

A failed transaction has already been refunded

This is the most important point in this guide. After an automatic refund, the transaction stays marked Failed. It does not change to Refunded. Meanwhile, the Refund to wallet button is available on both Success and Failed rows. If you press it on a failed transaction, the platform credits the customer again, because the only thing it checks is whether you have already refunded that transaction manually.

So before you refund a failed transaction, open the customer and read their wallet history. If you can see the "Auto-refund" credit, they have been refunded and you should not do it again. Use the manual refund for situations where a transaction succeeded on paper but you decide to give the money back, for example because you discovered a pricing mistake.

When the customer says they did not get their data

Work through it in this order:

• Status says Success. The provider told us it delivered. Check the delivery on the provider's own dashboard and ask the customer to confirm the number and network. Some data bundles take a little time to show on the phone. Do not refund until you have checked.
• Status says Failed. The customer should already have their money back. Confirm the auto-refund in their wallet history and tell them the reference.
• Status says Pending, with a "needs confirmation" label. The provider never answered, so nobody knows yet. Check the provider's own records first, as described in the next section.
• Status says Failed, but the customer says the data arrived. This is now rare. It can still happen if an on-hold purchase ran out its wait and was refunded automatically, and the provider delivered after all. Before you refund or resend anything, look at the provider's own transaction history for that phone number.

One provider is handled slightly differently. For ArewaBundle, a slow or empty reply is treated as a success and flagged in the transaction message, so read the message on those rows.

When the provider does not answer

Sometimes the provider receives the order and then goes quiet: the reply is slow, or it comes back empty. The order may well have been delivered, so refunding the customer at once could mean paying twice. Instead, the platform holds the purchase:

• The transaction stays Pending and is labelled needs confirmation in Insights, then Transactions.
• The customer's wallet stays charged. They see a message that the purchase is still being confirmed, and they are asked not to buy again.
• Open the row. You can press Confirm delivered if the provider's own records show it went through (the customer stays charged), or Refund to wallet if it did not.
• If you do neither, the platform refunds the customer automatically after a wait. The default is 60 minutes. You can change it in Settings, then Unconfirmed Purchases. Enter 0 to never refund automatically and always decide yourself.

Always check the provider's own history for that phone number and reference before you choose. Do it before the wait runs out, because an automatic refund cannot know whether the provider delivered. A provider that clearly says no, or cannot be reached at all, is still refunded straight away, because in those cases nothing was delivered.

The platform does not ask the provider again

The platform decides when the provider answers, and does not ask for the status again later or retry. That is why the hold-and-confirm step exists: you are the check. SIM Host works differently, because the transaction stays Pending until the SIM job reports back, then becomes Success or Failed with an automatic refund.

A short routine is still worth building: once a day, compare your provider's statement with your Transactions list. Any difference is easiest to fix the same day, while the customer still remembers what happened.

Habits that keep disputes small

• Keep your provider balance funded. An empty provider balance is one of the most common reasons a purchase fails.
• Always reply with the transaction reference, so you and the customer are talking about the same record.
• Check the wallet ledger before any manual refund or deduction.
• Test each network with a small purchase after you change a plan ID or provider.

What to read next

See how transactions and provider responses are recorded for what each status means, managing customers and wallets for the wallet ledger and adjustments, and connecting a vending provider to choose and test your routes. If you are starting out, you can build your site on our VTU solution.