Vi Smart-Connect retailer data API: activation, recharge and wallet endpoints

Vodafone Idea Ltd. · Telecom

Smart-Connect is Vodafone Idea's retailer app for India's Vi trade channel, used by neighbourhood mobile shops, point-of-sale agents and SBA partners who sell Vi prepaid connections and recharges across the operator's telecom circles. A shop signs in with its registered mobile number and MPIN or a fingerprint, then works from a shortcut-driven home screen: SIMEX for new-connection activation with Aadhaar-based eKYC, POI/POA capture, customer face match and liveness checks; MNP for port-ins from other operators; a CYN flow for searching and reserving choice numbers by pattern, price or special date; and recharge screens for main, add-on and chillar top-ups confirmed with an M-PIN. A WRR screen raises a reversal when the shop recharges the wrong number, the e-top-up wallet tracks balance, margin and earned commission, and an all-transactions view lists O2C, FRC and UPI entries with refund status. Retailers also collect gamified runs, badges and scratch-card coupons through the app's rewards programme. Vodafone Idea distributes these flows through its distributor and field-sales network across India, where Smart-Connect shares shop counters with Airtel Mitra, JioPOS Lite and multi-operator agent platforms such as Spice Money and PayNearby.

SIMEX submissions link the customer's msisdn, poiNumber and poaNumber with simSerialNo, upcCode, circleId and the kycRefId returned by document verification. The eKYC result contains kycStatus, documentSanity, faceMatchScore, livenessScore and extracted ocrFields. Submission returns txnId, serviceRequestId, txnStatus and activationDateTime; a separate status lookup keyed by txnId supplies actStatus, accountSubStatus and failureReason for that order.

Around the activation sits the number and tariff record set: CYN inventory answers pattern, price-band and special-date searches with a per-number numberStatus and price, while the plan catalogue exposes planId, mrp, validityDays and dataBenefit per circle and connection type. Money records follow the sale: an e-top-up returns rechargeStatus, walletBalanceAfter and commissionAmount; a WRR record links back through originalTxnId and adds wrrStatus, reversedAmountWrr and adjustedWalletBalance. The wallet pairs etopupBalance with commissionMtd and lowBalanceThreshold, while the transaction feed itemises paymentStatus, refundStatus, creditTransactionId, debitTransactionId and frcTransactionId across recharge, O2C, FRC and UPI entries. Port-in checks contribute donorOperator, donorCircle, portInExpectedDate and upcExpiryDays.

Channel-operations teams can retain a submission's kycRefId alongside its returned txnId to connect the eKYC verdict with later activation status, and compare poiNumber/poaNumber reuse against the two-connections-per-document rule. Distributor finance teams can reconcile etopupBalance and commissionMtd against transaction debit/credit references and link a reversal's originalTxnId to the recharge before accounting for reversedAmountWrr. Portal developers can mirror the plan catalogue and CYN numberStatus, while port-in desks can screen eligibilityStatus before collecting documents. openData Studio turns these Vi retailer records into callable open data for those integrations.

Screenshots

API surface

Request/response examples are illustrative, reconstructed from the app's interface — not a live capture.

Authenticate retailer and issue session
POST /v1/vi-smart-connect/session/login osint
Confirms the retailer's mobile number and MPIN, locks the session to the registered handset and returns the retailer identity, Vi circle and partner type used by the rest of the app.
Auth: No prior session. Body carries the retailer MSISDN and MPIN plus the device identifier already bound to the shop handset; the returned token is sent as a bearer token on every later call.
- msisdn
- mpin
- deviceId
- appVersion
- os
- retailerId
- retailerName
- userType
- circleId
- token
- tokenExpiry
- deviceBound
```
POST /v1/vi-smart-connect/session/login HTTP/1.1
Content-Type: application/json

{
  "msisdn": "9876543210",
  "mpin": "4821",
  "deviceId": "a1b2c3d4e5f6",
  "appVersion": "9.3.5",
  "os": "android"
}
```
```
{
  "retailerId": "VI-RET-884210",
  "retailerName": "Ramesh Mobile Store",
  "userType": "SBA",
  "circleId": "MH",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenExpiry": "2026-10-26T09:15:00+05:30",
  "deviceBound": true
}
```
Verify customer KYC document with face match
POST /v1/vi-smart-connect/activation/ekyc/verify osint
Runs OCR and authenticity checks on an Aadhaar, PAN, voter or passport image, compares the document photo with the customer's live selfie and returns the KYC reference that the activation submission consumes.
Auth: Bearer retailer session token from the login call, plus the registered deviceId. The upload carries document front/back images and the customer's live face image; the POS device binding must already be active.
- docType
- docNumber
- customerName
- dob
- frontImage
- backImage
- faceImage
- deviceId
- kycRefId
- kycStatus
- documentSanity
- faceMatchScore
- livenessScore
- ocrFields
- rejectionReason
```
POST /v1/vi-smart-connect/activation/ekyc/verify HTTP/1.1
Content-Type: application/json
Authorization: Bearer <retailer_token>

{
  "docType": "in.aadhaar",
  "docNumber": "123456789012",
  "customerName": "Sunita Sharma",
  "dob": "14-08-1991",
  "frontImage": "base64-front",
  "backImage": "base64-back",
  "faceImage": "base64-live-face",
  "deviceId": "a1b2c3d4e5f6"
}
```
```
{
  "kycRefId": "KYC-7f21ab",
  "kycStatus": "VERIFIED",
  "documentSanity": "OK",
  "faceMatchScore": 0.94,
  "livenessScore": 0.91,
  "ocrFields": {
    "name": "Sunita Sharma",
    "dob": "14-08-1991",
    "gender": "F"
  },
  "rejectionReason": ""
}
```

Submit SIMEX activation with customer POI/POA

POST /v1/vi-smart-connect/activation/simex openfinance

Creates a new Vi prepaid connection from a reserved number, SIM serial and UPC, attaching the customer's proof-of-identity and proof-of-address plus the eKYC reference, and returns the SIMEX transaction and service-request ids.

Auth: Bearer retailer session token plus the retailer MPIN for the activation attestation. The body references the reserved CYN number, the SIM serial/UPC and the kycRefId returned by document verification.

msisdn
simSerialNo
upcCode
circleId
connectionType
customerType
customerName
poiType
poiNumber
poaType
poaNumber
kycRefId
agentMsisdn
planId
mpin
txnId
txnStatus
activationDateTime
serviceRequestId
mrp
validityDays
dayLimitRemaining

POST /v1/vi-smart-connect/activation/simex HTTP/1.1
Content-Type: application/json
Authorization: Bearer <retailer_token>

{
  "msisdn": "9000012345",
  "simSerialNo": "8991000123456789012",
  "upcCode": "UPC-884210",
  "circleId": "MH",
  "connectionType": "PREPAID",
  "customerType": "INDIVIDUAL",
  "customerName": "Sunita Sharma",
  "poiType": "AADHAAR",
  "poiNumber": "123456789012",
  "poaType": "AADHAAR",
  "poaNumber": "123456789012",
  "kycRefId": "KYC-7f21ab",
  "agentMsisdn": "9876543210",
  "planId": "VI-PRE-299",
  "mpin": "4821"
}

{
  "txnId": "SIMEX-20261025-004821",
  "txnStatus": "SUBMITTED",
  "activationDateTime": "2026-10-25T11:42:16+05:30",
  "serviceRequestId": "SR-771902",
  "planId": "VI-PRE-299",
  "mrp": 299,
  "validityDays": 28,
  "dayLimitRemaining": 1
}

Poll activation order status
GET /v1/vi-smart-connect/activation/status/{txnId} openfinance
Returns the current state of a submitted activation — activated, pending or rejected — with the MSISDN, SIM serial, sub-status and failure reason used by the MSISDN Status screen.
Auth: Bearer retailer session token; the transaction must belong to the signed-in retailer's circle, and the deviceId is sent as a query parameter for audit.
- txnId
- msisdn
- actStatus
- accountSubStatus
- activationDateTime
- simSerialNo
- serviceRequestId
- failureReason
```
GET /v1/vi-smart-connect/activation/status/SIMEX-20261025-004821?circleId=MH&deviceId=a1b2c3d4e5f6 HTTP/1.1
Authorization: Bearer <retailer_token>
```
```
{
  "txnId": "SIMEX-20261025-004821",
  "msisdn": "9000012345",
  "actStatus": "ACTIVATED",
  "accountSubStatus": "ACTIVE",
  "activationDateTime": "2026-10-25T12:05:44+05:30",
  "simSerialNo": "8991000123456789012",
  "serviceRequestId": "SR-771902",
  "failureReason": ""
}
```
Search and reserve CYN numbers
GET /v1/vi-smart-connect/activation/numbers opendata
Searches Vi's choice-number pool by pattern, price band, special date or number type and returns availability with the per-number price and reservation window.
Auth: Bearer retailer session token. Search parameters select the circle and matching mode; reserve permission is checked against the retailer's authorisation before a number is locked.
- circleId
- searchType
- pattern
- priceBand
- limit
- totalAvailable
- reserveExpiryMinutes
- numbers
- msisdn
- numberStatus
- price
- category
```
GET /v1/vi-smart-connect/activation/numbers?circleId=MH&searchType=pattern&pattern=98765&priceBand=1500-2500&limit=20 HTTP/1.1
Authorization: Bearer <retailer_token>
```
```
{
  "totalAvailable": 42,
  "reserveExpiryMinutes": 30,
  "numbers": [
    {
      "msisdn": "9000098765",
      "numberStatus": "AVAILABLE",
      "price": 1800,
      "category": "SILVER"
    }
  ]
}
```

Fetch recharge plan catalogue

GET /v1/vi-smart-connect/recharge/plans opendata

Lists the Vi tariff plans available in a circle — main, add-on, chillar and data packs — with MRP, validity and bundled benefits for the recharge picker.

Auth: Bearer retailer session token; plan visibility is filtered by the retailer's circle and the customer connection type.

circleId
connectionType
planCategory
totalCount
plans
planId
mrp
talktime
validityDays
dataBenefit
smsBenefit
description

GET /v1/vi-smart-connect/recharge/plans?circleId=MH&connectionType=PREPAID&planCategory=ADDON HTTP/1.1
Authorization: Bearer <retailer_token>

{
  "totalCount": 2,
  "plans": [
    {
      "planId": "VI-PRE-299",
      "mrp": 299,
      "talktime": 0,
      "validityDays": 28,
      "dataBenefit": "1.5GB/day",
      "smsBenefit": "100 SMS/day",
      "planCategory": "MAIN",
      "description": "Unlimited calls + 1.5GB/day"
    },
    {
      "planId": "VI-ADD-49",
      "mrp": 49,
      "validityDays": 0,
      "dataBenefit": "3GB",
      "planCategory": "ADDON",
      "description": "Data add-on"
    }
  ]
}

Execute e-top-up recharge
POST /v1/vi-smart-connect/recharge/etopup openfinance
Debits a plan's MRP from the retailer's e-top-up wallet, tops up the customer's prepaid number and returns the transaction id, post-recharge wallet balance, GST component and commission earned.
Auth: Bearer retailer session token plus the retailer MPIN entered on the confirmation dialog; the wallet balance must cover the MRP and the request carries device and location context.
- retailerMsisdn
- customerMsisdn
- planId
- rechargeAmount
- mrp
- connectionType
- mpin
- latitude
- longitude
- txnId
- rechargeStatus
- validityDays
- walletBalanceAfter
- commissionAmount
- gstAmount
- rechargeDateTime
```
POST /v1/vi-smart-connect/recharge/etopup HTTP/1.1
Content-Type: application/json
Authorization: Bearer <retailer_token>

{
  "retailerMsisdn": "9876543210",
  "customerMsisdn": "9810012345",
  "planId": "VI-PRE-299",
  "rechargeAmount": 299,
  "mrp": 299,
  "connectionType": "PREPAID",
  "mpin": "4821",
  "latitude": "19.0760",
  "longitude": "72.8777"
}
```
```
{
  "txnId": "RCH-20261025-118842",
  "rechargeStatus": "SUCCESS",
  "mrp": 299,
  "validityDays": 28,
  "walletBalanceAfter": 18151.75,
  "commissionAmount": 9.57,
  "gstAmount": 45.61,
  "rechargeDateTime": "2026-10-25T12:31:08+05:30"
}
```
Raise a wrong-recharge reversal (WRR)
POST /v1/vi-smart-connect/recharge/wrr openfinance
Requests reversal of a recharge made to a wrong number, returning the WRR reference, the reversed amount and the adjusted wallet balance, subject to the daily count and value caps.
Auth: Bearer retailer session token plus the retailer MPIN. The original recharge must belong to the same retailer and fall inside the app's one-WRR-per-day and value limits.
- originalTxnId
- msisdn
- rechargeAmount
- wrrReason
- mpin
- wrrId
- wrrStatus
- reversedAmountWrr
- adjustedWalletBalance
- requestDate
- rejectionReason
```
POST /v1/vi-smart-connect/recharge/wrr HTTP/1.1
Content-Type: application/json
Authorization: Bearer <retailer_token>

{
  "originalTxnId": "RCH-20261025-118842",
  "msisdn": "9810012345",
  "rechargeAmount": 299,
  "wrrReason": "WRONG_NUMBER",
  "mpin": "4821"
}
```
```
{
  "wrrId": "WRR-20261025-7712",
  "wrrStatus": "REVERSED",
  "reversedAmountWrr": 299,
  "adjustedWalletBalance": 18450.75,
  "requestDate": "2026-10-25T12:40:11+05:30",
  "rejectionReason": ""
}
```
Fetch retailer e-top-up wallet balance
GET /v1/vi-smart-connect/wallet/balance openbanking
Returns the retailer's live e-top-up float, usable balance, month-to-date commission, margin percentage and the low-balance threshold shown on the wallet card.
Auth: Bearer retailer session token; the query is scoped to the signed-in retailer MSISDN and its registered device.
- retailerMsisdn
- etopupBalance
- availableBalance
- commissionMtd
- margin
- lowBalanceThreshold
- currency
- walletUpdatedAt
```
GET /v1/vi-smart-connect/wallet/balance?retailerMsisdn=9876543210 HTTP/1.1
Authorization: Bearer <retailer_token>
```
```
{
  "retailerMsisdn": "9876543210",
  "etopupBalance": 18450.75,
  "availableBalance": 18151.75,
  "commissionMtd": 12840.5,
  "margin": 3.2,
  "lowBalanceThreshold": 500.0,
  "currency": "INR",
  "walletUpdatedAt": "2026-10-25T12:31:08+05:30"
}
```

List retailer transactions and refunds

GET /v1/vi-smart-connect/transactions openbanking

Pages the retailer's combined transaction history — app recharges, O2C, FRC and UPI entries — with amount, payment status, failure reason, refund state and the debit/credit reference ids.

Auth: Bearer retailer session token; the filter is scoped to the retailer and accepts a transaction type plus a date window and page cursor.

txnType
fromDate
toDate
page
size
totalCount
transactions
txnId
amount
paymentStatus
paymentDate
customerMsisdn
failureReason
refundStatus
refundAmount
creditTransactionId
debitTransactionId
otcTransactionId
frcTransactionId

GET /v1/vi-smart-connect/transactions?txnType=ALL&fromDate=2026-10-01&toDate=2026-10-25&page=1&size=20 HTTP/1.1
Authorization: Bearer <retailer_token>

{
  "totalCount": 1,
  "page": 1,
  "size": 20,
  "transactions": [
    {
      "txnId": "RCH-20261025-118842",
      "txnType": "RECHARGE",
      "amount": 299,
      "paymentStatus": "SUCCESS",
      "paymentDate": "2026-10-25T12:31:08+05:30",
      "customerMsisdn": "9810012345",
      "failureReason": "",
      "refundStatus": "NOT_APPLICABLE",
      "refundAmount": 0,
      "creditTransactionId": "CR-77102",
      "debitTransactionId": "DR-77103",
      "otcTransactionId": "",
      "frcTransactionId": "FRC-4411"
    }
  ]
}

Collect wallet top-up over UPI
POST /v1/vi-smart-connect/upi/collect openbanking
Initiates a UPI collect against the retailer's VPA to top up the e-top-up wallet, returning a pending transaction id that is later settled with an approval reference.
Auth: Bearer retailer session token plus the retailer MPIN. The response is asynchronous: the shop must approve the collect request in its UPI app before the wallet is credited.
- retailerMsisdn
- upiAddress
- amount
- remarks
- mpin
- deviceId
- txnId
- paymentStatus
- vpa
- approvalRefNo
- initiatedAt
```
POST /v1/vi-smart-connect/upi/collect HTTP/1.1
Content-Type: application/json
Authorization: Bearer <retailer_token>

{
  "retailerMsisdn": "9876543210",
  "upiAddress": "ramesh.store@okhdfcbank",
  "amount": 5000,
  "remarks": "E-topup float",
  "mpin": "4821",
  "deviceId": "a1b2c3d4e5f6"
}
```
```
{
  "txnId": "UPI-20261025-55210",
  "paymentStatus": "IN_PROGRESS",
  "vpa": "ramesh.store@okhdfcbank",
  "amount": 5000,
  "approvalRefNo": "",
  "initiatedAt": "2026-10-25T12:52:39+05:30"
}
```
Check MNP eligibility before port-in
GET /v1/vi-smart-connect/mnp/eligibility osint
Checks whether a number can port into Vi, returning the donor operator and circle, corporate-customer caveat, expected port-in date and the UPC validity window before a port-in is submitted.
Auth: Bearer retailer session token; the number is queried with its donor circle and the result reflects the live portability rules for that circle.
- msisdn
- donorCircle
- donorOperator
- eligibilityStatus
- corporateCustomer
- portInExpectedDate
- upcRequired
- upcExpiryDays
- rejectionReason
```
GET /v1/vi-smart-connect/mnp/eligibility?msisdn=9810012345&donorCircle=DL HTTP/1.1
Authorization: Bearer <retailer_token>
```
```
{
  "msisdn": "9810012345",
  "donorOperator": "AIRTEL",
  "donorCircle": "DL",
  "eligibilityStatus": "ELIGIBLE",
  "corporateCustomer": false,
  "portInExpectedDate": "2026-10-29",
  "upcRequired": true,
  "upcExpiryDays": 4,
  "rejectionReason": ""
}
```

Where teams use this data

Activation compliance audit
Join a SIMEX submission's txnId and kycRefId to the eKYC result and the activation status feed, then reconcile poiNumber/poaNumber reuse against the two-connections-per-document rule before a circle audit.
Distributor float and commission reconciliation
Match wallet etopupBalance and commissionMtd against the transaction feed's debitTransactionId, creditTransactionId and reversedAmountWrr rows to close each retailer's daily float.
Shop-floor plan and number feed
Mirror the circle plan catalogue and CYN availability — planId, mrp, validityDays, numberStatus and price — into a distributor portal so outlets quote current Vi tariffs and choice numbers.
Port-in pre-check workflow
Run an MNP eligibility lookup on donorOperator, donorCircle and portInExpectedDate, then queue the UPC and customer documents only for eligible numbers, cutting rejected port-ins.

Frequently asked questions

Which identifiers join a Vi activation to its KYC and recharge records?

Document verification returns kycRefId, which the SIMEX submission includes with msisdn, upcCode and simSerialNo. Retain that request-to-response mapping: SIMEX returns txnId and serviceRequestId, and the status lookup uses txnId. Recharge results have their own txnId; transaction-history entries provide creditTransactionId and debitTransactionId for wallet reconciliation. The documented fields do not include a direct activation-to-recharge foreign key.

What does the retailer wallet expose?

The wallet response pairs etopupBalance with availableBalance, commissionMtd, margin and a lowBalanceThreshold in INR, the same figures the app shows on its e-top-up balance card.

How is a wrong recharge tracked?

A WRR request references originalTxnId. Its result provides wrrId, wrrStatus, reversedAmountWrr and adjustedWalletBalance, with rejectionReason explaining a refusal. Check wrrStatus rather than assuming every request succeeds. The daily rule allows one WRR transaction per correct number, and count and value limits also apply.

Which fields describe a port-in before submission?

The eligibility lookup returns donorOperator, donorCircle, eligibilityStatus, portInExpectedDate, upcRequired and upcExpiryDays. It also includes corporateCustomer to identify a corporate customer and rejectionReason to explain an unsuccessful eligibility check; the flag alone does not specify a separate port-in procedure.

Apps similar to Smart-Connect

Mitra — Mitra is Bharti Airtel's retailer app for India's prepaid trade, where distributors and neighbourhood shops top up customers from a LAPU e-recharge wallet, sell R-offers confirmed by an mPIN and activate new connections.
Spice Money — Spice Money is an assisted-banking platform for India's neighbourhood agents, offering Aadhaar-enabled AePS cash withdrawal, deposit and balance enquiry, domestic money transfer, and mobile recharge and bill payments from one app.
PayNearby — PayNearby is Nearby Technologies' app for Indian business-correspondent retailers, who run Aadhaar-enabled AePS cash-out and deposits, domestic money transfers, BBPS bill payments and prepaid mobile recharges from a kirana counter.
Mobirec — Mobirec is an independent multi-operator recharge app for India's kirana counters, where retailers sell Jio, Airtel and Vi top-ups by telecom circle plus DTH packs and BBPS bills from a wallet refilled over UPI.
Airtel Thanks — Airtel Thanks is Bharti Airtel's consumer app, where subscribers recharge prepaid numbers, pay postpaid, broadband and DTH bills, and use Airtel Payments Bank, UPI and rewards in one login.
MyJio — MyJio is Reliance Jio's self-care app for prepaid subscribers, used to browse unlimited 4G and 5G data plans and buy a prepaid recharge pack online.
Vi App — Vi App is Vodafone Idea's own consumer app, where prepaid subscribers recharge, browse unlimited and data packs, order a new SIM and port a number to Vi without changing it.

More Telecom apps

Topics

Vi Smart-Connect API
Vodafone Idea retailer API
SIMEX activation API
Vi eKYC data
CYN number inventory
Vi recharge API
retailer wallet balance
MNP eligibility API

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Vi Smart-Connect retailer data API: activation, recharge and wallet endpoints

Screenshots

API surface

Authenticate retailer and issue session

Verify customer KYC document with face match

Submit SIMEX activation with customer POI/POA

Poll activation order status

Search and reserve CYN numbers

Fetch recharge plan catalogue

Execute e-top-up recharge

Raise a wrong-recharge reversal (WRR)

Fetch retailer e-top-up wallet balance

List retailer transactions and refunds

Collect wallet top-up over UPI

Check MNP eligibility before port-in

Data categories

Where teams use this data

Activation compliance audit

Distributor float and commission reconciliation

Shop-floor plan and number feed

Port-in pre-check workflow

Frequently asked questions

Apps similar to Smart-Connect

More Telecom apps

Azercell

FreeByte

hambi (Beeline Uzbekistan)

Hathway Broadband

Topics

Need this app's data API integrated?

Vi Smart-Connect retailer data API: activation, recharge and wallet endpoints

Screenshots

API surface

Authenticate retailer and issue session

Verify customer KYC document with face match

Submit SIMEX activation with customer POI/POA

Poll activation order status

Search and reserve CYN numbers

Fetch recharge plan catalogue

Execute e-top-up recharge

Raise a wrong-recharge reversal (WRR)

Fetch retailer e-top-up wallet balance

List retailer transactions and refunds

Collect wallet top-up over UPI

Check MNP eligibility before port-in

Data categories

Where teams use this data

Activation compliance audit

Distributor float and commission reconciliation

Shop-floor plan and number feed

Port-in pre-check workflow

Frequently asked questions

Related apps

Apps similar to Smart-Connect

More Telecom apps

Azercell

FreeByte

hambi (Beeline Uzbekistan)

Hathway Broadband

Topics

Need this app's data API integrated?