700+
Operators in the catalog
150+
Coverage countries
5–20 sec
Top-up time
99.7%
Successful transactions
Three Top-Up Types
The type field in GET /telecom/products lets you filter the catalog by the required top-up type.
Balance Top-Up
Service Bundle
Plan Change
Automatic Operator Detection by Number
POST /telecom/lookup
Pass the phone number — the API returns the operator, country, type (prepaid/postpaid), and available products. Call this before displaying the catalog to show only relevant offers.
How Top-Up Works
Detect the Operator
POST /telecom/lookup by phone number — get the operator, subscriber type, and list of available products.
Show the Catalog
GET /telecom/products?operator_id=… — only relevant packages and plans for this operator and subscriber type.
Create a Transaction
POST /telecom/topup — funds or a package are credited to the number. Status and webhook updates are provided in real time.
Regions and Operator Examples
CIS and Russia
MTS, Beeline, Megafon, Tele2, Kyivstar, Lifecell, Kcell, Ucell, and 50+ operators in the region.
Asia and the Middle East
Airtel, Jio, Turkcell, Etisalat, STC, Ooredoo, and 200+ operators.
Africa and Latin America
MTN, Airtel Africa, Claro, Movistar, Tigo, Digicel, and 300+ operators.
Europe
Orange, Vodafone, T-Mobile, O2, WindTre, and operators across 40+ EU and CIS countries.
Main Endpoints
Documentation
/telecom/lookup
Detect operator by phone number
/telecom/products
Product catalog with filters
/telecom/products/{id}
Product details, terms, and package contents
/telecom/topup
Create a top-up transaction
/esim/orders
Create an order and receive a QR code
/telecom/topup/{tx_id}
Transaction status
/webhooks
Register a webhook URL
{
"phone": "79161234567"
}{
"phone": "79161234567",
"product_id": "mts_ru_bundle_10gb_30d",
"external_tx_id": "your-tx-901"
}{
"tx_id": "tel_6jn3q...",
"status": "completed",
"operator_tx_id": "MTS-20240315-88123",
"credited": "{ "data_gb": 10, "validity_days": 30 }",
"completed_at": "2024-03-15T16:41:03Z"
}Technical Advantages
Lookup Before Payment
Automatic operator detection reduces errors and shows only available products — with no extra steps for the buyer.
Idempotency
external_tx_id protects against duplicate credits when requests are retried after a network error.
operator_tx_id in the Response
The operator-side transaction ID lets you verify the credit directly in case of disputes.
Webhook Events
topup.completed, topup.failed, and topup.pending — real-time monitoring for every transaction.
Frequently Asked Questions
Why should I call lookup before topping up?
The same number may belong to different operators depending on number portability. Lookup detects the current operator and subscriber type (prepaid/postpaid), so you can show only compatible products and prevent failed transactions.
Are postpaid numbers supported?
It depends on the operator. The supports field in the /lookup response contains the list of available operation types for a specific number. For postpaid numbers, usually only bundle and plan_change are available, while direct balance top-up is typically available only for prepaid numbers.
What if a transaction gets stuck in pending status?
Some operators process transactions asynchronously for up to 5 minutes. The status is updated via the topup.completed or topup.failed webhook. GET /telecom/topup/{tx_id} returns the current status at any time.
Can I top up a number in another country?
Yes — international top-up is one of the main use cases. Pass the number in international E.164 format (+country code), and the API will automatically detect the country and operator.