Transaction Flow
The sequence below shows the standard integration flow — from fetching the catalog through to confirming a transaction outcome, including the timeout recovery path.
Key rule
A transaction is only successful when HTTP status is 200 AND responseCode = "000". Always check both.
Sequence Diagram
Your System
ValueTopup API
Carrier
PHASE 1 — CATALOG (refresh daily / weekly)
GET /api/v2/catalog/skus
responseCode: "000" + SKU list
Cache SKU IDs locally
PHASE 2 — SEND TRANSACTION
POST /transaction/topup
{ skuId, mobile, amount, transactionCurrencyCode, corelationId }
{ skuId, mobile, amount, transactionCurrencyCode, corelationId }
Forward to carrier network
Carrier processes top-up
PHASE 3 — RESPONSE (normal path | alt: timeout path)
Normal
HTTP 200 + responseCode in body
Alt: Timeout
responseCode
= "000"
= "000"
responseCode
≠ "000"
≠ "000"
✓ Mark SUCCESS
✗ Mark FAILED
Process payLoad,
update your recordsLog responseMessage,
notify user
update your recordsLog responseMessage,
notify user
⚠ Request timed out
Do NOT assume failure.
Account may be charged.
GET /transaction/status/{corelationId}
responseCode "852" → still in progressretry
Final responseCode returned
000 → SUCCESS
other → FAILED
PHASE 4 — PERIODIC CATALOG REFRESH (daily or weekly)
Refresh /catalog/skus regularly — pricing & availability change.
Never hardcode SKU IDs. Cache for max 24 hrs for daily cadence.
re-fetch catalog → cache updated SKU IDs
Request
Response
Timeout / Retry path
852Still in progress — keep polling
Step-by-Step Summary
Fetch the catalog (daily / weekly)Call
GET /api/v2/catalog/skus to retrieve the current list of products and their SKU IDs. Cache locally and refresh at least every 24 hours. Never hardcode SKU IDs — pricing and availability change in real time.Send the transactionCall
POST /api/v2/transaction/topup with skuId, mobile, amount, and a unique corelationId generated by your system. Store the correlation ID — you will need it if the request times out.Alt: if no response in time — call Check StatusIf your system times out before receiving a response, do not assume the transaction failed — your account may already be charged. Call
GET /api/v2/transaction/status/corelationId and keep polling until you receive a definitive result. A responseCode of 852 means the transaction is still in progress — retry until you get a final code.responseCode "000" → Mark as successfulWhen both the HTTP status is 200 and responseCode = "000", the transaction is confirmed successful. Process the payLoad and update your records accordingly.
Any other responseCode → Mark as failedIf responseCode is anything other than 000, the transaction has failed. Log the responseCode and responseMessage, and surface an appropriate message to the user. Use
GET /api/v2/catalog/errors for the full list of error codes and descriptions.