Every API transaction ends in one of a few states. Handling them correctly protects your money and your customers. This article explains each state and the most common error answers.
The statuses
- Success. The service was delivered: the number was recharged, the bill was paid, the document was verified.
- Failed. Nothing was delivered. For a live call, the amount went back to your wallet automatically.
- Pending. The request was accepted and is still being processed by the operator or bank. The result is not known yet.
- Refunded. A transaction that first looked successful or pending was reversed later, and the amount was returned.
Pending is not failed
A pending recharge will, in most cases, turn into a success within seconds or a few minutes. If your software treats pending as failed and sends the recharge again, the customer gets two recharges and you pay twice.
What to do with a pending transaction:
- Show your customer "in process", not "failed".
- Wait for the webhook with the final status.
- As a safety net, ask for the status with the status call after a minute, and then at growing intervals.
- Do nothing else. We resolve pending transactions automatically with the operator; if the final answer is a failure, the money is returned without you asking.
Some operators take longer at busy times or during their maintenance. If a transaction is still pending after several hours, open a ticket with its reference.
Use client_ref for every transaction
client_ref is your own unique reference for a transaction, for example your order number. It makes retries safe:
- If you send the same
client_refagain, we do not create a second transaction. You get the result of the first one. - So when your request times out and you do not know whether it reached us, send it again with the same client_ref. A new reference would create a second transaction.
Create the reference in your system before the call, store it, and reuse it for every retry of that order.
Common reasons for "failed"
- Wrong number or operator. The number does not belong to the chosen operator or circle, or the customer ID for a bill is wrong.
- Amount not allowed. The operator has no plan for that amount, or the amount is outside the limits of the service.
- Operator not available. The operator's system is down for a moment. Try again later with a new order.
- Bill already paid or no bill due.
- Details do not match for a verification, for example a PAN that does not exist.
The answer carries a message that explains the reason in words you can show to your customer.
Requests that are refused before they start
These are errors of the request, not transactions. Nothing is charged.
- Not enough balance. Top up the wallet.
- Service not in your package or switched off for your account.
- Invalid key, address not whitelisted, missing signature. See the article on API keys and the IP whitelist.
- Validation errors. A field is missing or has the wrong form. The answer names the field.
- Too many requests. You passed the calls-per-minute limit. Slow down and try again after the pause given in the answer.
Timeouts on your side
If your server stops waiting before our answer arrives, the transaction may still have been created. Never assume it failed. Ask for the status by client_ref, or resend with the same client_ref.
Set the timeout of your HTTP client generously, for example 60 seconds, and do the call in a background job when your user should not wait.
The customer says the recharge did not arrive, but the status is success
Give us the transaction reference in a ticket. We check it with the operator. The operator reference shown on the transaction is the proof the operator accepts; the customer can quote it to the operator's helpline.
Refunds that arrive later
Occasionally an operator reverses a transaction after reporting success. The transaction then changes to *refunded*, your wallet is credited and your webhook is called with the new status. Make sure your system can handle a status change after a success.
A checklist for a solid integration
- Every order has its own stored
client_ref. - Pending is shown as "in process" and never resent with a new reference.
- Webhooks are verified, and repeats are ignored.
- A timer re-checks pending transactions.
- Failed transactions show the message from our answer.
- Your wallet has an alert for low balance.