Plan Versions
How the -v1-, -v2-, and -v3- segments in plan IDs select between independent provider routes, and the per-service advantages of each.
What are Plan Versions?
KDA provisions multiple independent provider routes for its services. Every plan ID contains a -v1-, -v2-, or -v3- segment that dictates which underlying provider infrastructure the transaction is routed through. You choose the route dynamically by selecting the corresponding plan ID.
| Version | Infrastructure |
|---|---|
-v1- | Primary |
-v2- | Secondary |
-v3- | Aggregator |
For example, kds-data-mtn-sme-v1-003 routes through the primary infrastructure, kds-data-mtn-sme-v2-001 routes through the secondary infrastructure, and kds-elec-ekedc-pre-v3 routes through the aggregator infrastructure.
Version ≠ API version. The -v1- / -v2- / -v3- segment has nothing to do with the KDA API versioning — it only selects the provider route for a purchase. The same endpoints and payloads are used regardless of route.
The v3 Route (Aggregator)
A third route — backed by aggregator infrastructure — is rolling out across services. Its plan IDs carry a -v3- segment:
- Airtime, TV, and Electricity have v3 products. Data, Exam PINs, Recharge Cards, and Data Cards do not have a v3 route.
- Electricity v3 IDs split by meter type — e.g.
kds-elec-ekedc-pre-v3/kds-elec-ekedc-post-v3; Benin uses a singlekds-elec-bedc-v3. - Availability is per product: v3 plans appear in
plansresponses only once enabled — always fetch live plans; never assume a v3 variant exists for every product. - v3 pricing is independent, so treat it as an availability route and compare it alongside v1/v2 when choosing.
Route Advantages by Service
Pricing, fees, and catalog coverage differ per route. The tables below summarize the advantages of each version based on the current plan catalog. Always fetch live plans from the plans endpoint — prices and availability can change without notice.
Airtime
| Network | Advantage |
|---|---|
| MTN | v2 offers higher discounts |
| AIRTEL | Discounts are equal on both routes |
| GLO | v2 offers significantly higher discounts |
| T2MOBILE | v2 offers higher discounts |
| VITEL | v1 only (VTU, no v2 route) |
Top-up limits per version:
| Limit | v1 (Primary) | v2 (Secondary) |
|---|---|---|
| Minimum top-up | ₦50 | ₦100 |
| Maximum top-up | ₦500 | ₦10,000 |
- Attempting an airtime purchase below the minimum of the selected route is rejected by the provider. The transaction is automatically refunded and a clear error message is returned — no amount is lost.
- Purchases above the maximum are rejected by the API provider before any wallet debit is attempted.
- v2 additionally provisions Share and Sell channels (currently disabled by default) — this airtime type does not exist on v1.
- If your priority is discount margins, v2 is the better route for MTN, GLO, and T2MOBILE.
Data
| Aspect | v1 (Primary) | v2 (Secondary) |
|---|---|---|
| Pricing | Higher for most equivalent bundles | Cheaper for most equivalents |
| Plan types | SME, GIFTING, PROMO, CORPORATE | SME, GIFTING, CORPORATE (no PROMO) |
| Social plans | Not available | Available |
| Special bundles | Not available | Available (e.g. bundles with free video-hour bonuses) |
| Validity options | Fixed validity | Flexible validity windows plus short-duration options |
| AIRTEL GIFTING | Available | Not seeded |
| T2MOBILE | CORPORATE only | CORPORATE only |
| VITEL | Available (SME plans) | Not available |
- v2 generally offers lower data prices and unique Social/Special bundle types.
- v1 keeps PROMO bundles which v2 lacks — compare catalogs per network before routing.
TV (Cable)
Base DStv/GOtv/StarTimes bundles are priced identically on both routes.
| Aspect | v1 (Primary) | v2 (Secondary) |
|---|---|---|
| DStv combos | Widest coverage (+French Touch/Plus, +Asia, +ExtraView, Add-ons, HDPVR) | Core combos only |
| GOtv Supa | Pricier | Cheaper |
| StarTimes Smart (DTH) 1 month | Cheaper | Pricier |
| StarTimes 1-day passes | Available | Not available |
| StarTimes Special (DTH) | Available | Not available |
- Use v1 for DStv bundle combinations, StarTimes 1-day passes, and cheaper StarTimes Smart.
- Use v2 for the cheaper GOtv Supa plan.
Electricity
All 11 DISCOs are available on both routes.
| Aspect | v1 (Primary) | v2 (Secondary) |
|---|---|---|
| Service fee | None | Fixed per-transaction fee |
- v1 is cheaper — it carries no fixed service fee on electricity purchases.
Exam Pins
| Exam | v1 (Primary) | v2 (Secondary) |
|---|---|---|
| WAEC | Available | Available |
| NECO | Cheaper | Pricier |
| NABTEB | Available | Not available |
- v1 covers all three exams and is cheaper for NECO.
Recharge Cards (PINs)
| Aspect | v1 (Primary) | v2 (Secondary) |
|---|---|---|
| Catalog | 5 SKUs (MTN, GLO, AIRTEL — limited values) | 14 SKUs — all networks incl. T2MOBILE, plus high-value denominations |
| Pricing | Slightly cheaper on some values | Slightly cheaper on others |
- v2 wins on catalog size — it is the only route with T2MOBILE PINs and high-value denominations.
Data Cards
Data cards are currently seeded on v1 only (kds-data-card-mtn-v1, e.g. kds-data-card-mtn-750mb-v1).
Which Route Should You Use?
There is no single best route — the right choice is per-service:
- Cheapest pricing: v2 for Data and most Airtime, v1 for Electricity, NECO exam pins, and StarTimes Smart.
- Catalog coverage: v1 for DStv combos, PROMO data, NABTEB, and StarTimes 1-day/Special options; v2 for Share & Sell airtime, Social data plans, and the full recharge-card range.
- Resilience: the routes are independent infrastructure. For high-availability setups, fetch plans from all available versions and fall back to an alternate route if the selected provider is unavailable or returns an error.
Route pricing and availability are managed internally and can be updated per version at any time — always re-fetch plans before purchases instead of caching prices long-term.