Understanding Transactions and Provider Responses

Every airtime or data sale on your site leaves a record, and learning to read that record saves you hours of guessing. This guide explains the four transaction statuses, how the platform decides whether a provider's reply means success, which failures are refunded at once and which are held, how to read an expanded row, and what you and your customers can see.

The four statuses

• Pending. The purchase has started. For most providers this lasts only a moment, between creating the record and hearing back from the provider. If the provider received the order but never answered, the purchase stays pending and is labelled needs confirmation, with the customer still charged, until you confirm it, refund it, or it is refunded automatically after a wait.
• Success. The provider confirmed the order.
• Failed. The provider did not confirm success. The customer's wallet has already been refunded automatically.
• Refunded. You refunded the transaction manually from the admin dashboard.

Notice that a failed purchase stays Failed even after the automatic refund. Only a manual refund changes the status to Refunded. We explain why that matters in our guide on failed transactions and wallet refunds. The same four statuses apply however the purchase was made: on your website, through a customer's API key, or from the WhatsApp or Telegram bot.

The reference number

Each transaction gets a unique reference that looks like XVTU-20261004-AB12CD, which is the platform name, the date and six random letters or digits. If the provider sends back its own reference when the purchase succeeds, the platform replaces the reference with the provider's. That makes it easier to match a record with the provider's statement. When you talk to a customer, always quote the reference.

How the platform decides what a provider's reply means

Every provider answers in its own format. For each connection, the platform knows which field in the reply tells it the result, and which value means success. It compares the two, ignoring upper and lower case. If they match, the transaction is a success. Any other answer, such as an error message or an unexpected reply, is a failure. A timeout or an empty reply is handled separately, as explained next.

Which failures are refunded and which are held

The platform treats failures differently, because the right response depends on whether the order may have been delivered.

• A clear "no", an error message, or a server error from the provider: nothing was delivered. The purchase is marked Failed and the wallet is refunded at once.
• The provider could not be reached at all (the connection never opened): the order was never sent, so it is Failed and refunded at once.
• The provider received the order and then went quiet (a slow reply, or an empty one): the order may have been delivered, so refunding immediately could mean paying twice. The purchase is held as Pending with a "needs confirmation" label. You can press Confirm delivered if the provider's records show it went through, or Refund to wallet if it did not. If you do neither, it is refunded automatically after the wait set in Settings (60 minutes by default; 0 means never refund automatically).
• ArewaBundle is handled separately: a slow or empty answer is counted as a success and flagged in the transaction message, because that provider is known to complete orders without replying in time.

What the customer sees

After a purchase, the customer gets a receipt with a status badge. While the transaction is not yet final, the receipt shows a processing state with a clock. On success, they see a standard confirmation such as "Your MTN Data purchase of ₦500 was successful." On failure they see the reason, and a line telling them their wallet was refunded. For a held purchase they are told it is still being confirmed and asked not to buy again, and a second identical purchase is blocked until the first is resolved. Their history can be filtered by pending, success, failed and refunded.

What you see

Go to VTU Admin, then Insights, then Transactions. The columns are reference, customer, service, details, amount, balance before, balance after, status and date. The two balance columns come from the wallet ledger, so you can see exactly what the customer's wallet did around that purchase. You can search by reference, phone number or customer name, and filter by status or service. Purchases that need confirmation are labelled in the status column, and their expanded row has the Confirm delivered and Refund to wallet buttons.

Reading an expanded row

Click any row to expand it. You get the provider's message, the request your site sent, the response that came back and any error. When a purchase fails, the provider message and the error are usually the quickest way to learn why. Illustrative examples: the wording below is made up to show the idea; real providers use their own phrases.

• A message like "insufficient balance" or "wallet too low" means your balance with the provider is empty. Top it up.
• "Invalid plan" or "invalid network" usually means the plan ID or network code on your plan does not match the provider's. Compare it with the provider's list.
• "Invalid number" or a number-format message means the phone number was rejected. Check the format and the network.
• An empty response or a timeout points to a slow or struggling provider. This is the held case above.
• A long error page in the response means the provider itself had a problem. Check their status and try a small purchase.

What to do for each status

• Success, but the customer says they did not receive it. 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. Do not refund until you have checked.
• Failed. The customer should already have their money back. Confirm the refund appears in their wallet, using the balance columns, and give them the reference. The Refund button will not credit a second time if an automatic refund is already on the ledger.
• Pending with "needs confirmation". Check the provider's records for that phone number and reference, then confirm or refund before the wait runs out.
• Pending without that label. It is usually a moment's wait, or a SIM Host job still running. Give it a few minutes, then look again.
• Refunded. You did this by hand. Nothing more to do.

SIM Host purchases behave differently

If a network is routed through SIM Host, the platform sends the job to your SIM and the transaction stays Pending while it waits. When the SIM job reports back, the transaction becomes Success, or Failed with an automatic refund. A duplicate report for the same job is ignored, and a purchase you have already refunded is never turned back into a success.

Good habits

• Search by reference first when a customer complains. It is the fastest route to the right record.
• Expand the row before you decide anything. The provider message often tells you the whole story.
• Compare your Transactions list with your provider's statement regularly. The platform records what it was told, not what happened on the provider's side after that.
• Check your vending routes if the same service keeps failing.

Where to go next

Read handling failed transactions and wallet refunds for the step-by-step checks, and managing customers and wallets to understand the ledger. For a plain explanation of how vending providers work in general, see what a vending API is.