References and retries
Send every top-up exactly once, even when the network fails.
Networks fail. A request can time out after the top-up was accepted, and a naive retry would send it twice. The ref field prevents that.
Always send a ref
Give every top-up a unique ref, usually your order id. It can be 1 to 64 characters: letters, digits, _, ., : and -. Refs are unique per account, separately for mobile and internet top-ups.
If you leave ref out, one is generated and returned as topupRef. Store it: it is the only way to find the top-up again if you lose the response.
What happens on a repeat
| You send the same ref and… | You get |
|---|---|
| the first top-up was accepted | 403 DUPLICATED_REF. Nothing new is sent. Read the existing top-up with check-ref. |
| the first request was refused (validation, balance, stock, service down) | The ref was never used, so the new request is processed normally. |
So the safe pattern is: on any doubt, send again with the same ref, and treat DUPLICATED_REF as "already sent, go read it".
When the outcome is unknown
| Answer | Meaning | Do |
|---|---|---|
| Network error or timeout on your side | You don't know if we received it. | GET …/check-ref/{ref}. On 404 NOT_FOUND, it never arrived: send again with the same ref. |
503 SERVICE_UNAVAILABLE | We did not hear back from the platform in time. | Same as above: check the ref before sending again. |
500 INTERNAL_ERROR on a send | Unexpected error. | Check the ref before sending again. |
A ref whose request was cut off shows as PENDING or HANDLING for up to five minutes while we confirm it. If no top-up was created, it then turns REFUNDED with "The top-up was not accepted".
Polling
- Poll
check-reforcheck-idevery 5 seconds for internet and 5 to 10 seconds for mobile. - Stop at a final status:
COMPLETED,REFUNDED,MANUAL_REDEEMorUNKNOWN_ERROR. - On
DEBT_PENDING, stop and answer withPOST /v3/mobile/resolve-debtbefore polling again. - After 5 minutes, slow down to once a minute from a background job instead of keeping the customer waiting.
- Re-check
UNKNOWN_ERRORtop-ups every hour until they settle. - Use
GET /v3/mobile/listandGET /v3/internet/listto reconcile at the end of the day.
Refunds
Your balance is only charged for COMPLETED and MANUAL_REDEEM, and possibly for UNKNOWN_ERROR until it is settled. A REFUNDED top-up never took money, so there is nothing to give back from our side; refund your own customer at once.