openData Studio
Mitra icon

Mitra retailer data API: wallet, recharge and ledger endpoints

Product Engg · Telecom

Open on Google Play

Mitra is Airtel's shop-floor app for Indian retailers who sell prepaid recharges and LAPU stock. After OTP login the client wraps each call in a session envelope — retailer MSISDN, session token and device id — and posts it to Airtel's retailer platform as JSON.

The illustrative surface below generalizes those private calls into path form: OTP sign-in via POST /v1/auth/otp/verify, the wallet balance via POST /v1/retailers/wallet, commission splits via POST /v1/retailers/earnings, each prepaid top-up through POST /v1/recharge/subscribe and the LAPU cashbook through POST /v1/ledger/entries.

Mitra is Airtel's retailer-facing Android app for Indian distributors and shopkeepers who sell prepaid recharges, LAPU stock, activations and commissions. After OTP login the app wraps every request in a session envelope — retailer MSISDN (userIdentifier), session token (tokenId), deviceId and application=Retailer — and posts it to Airtel's retailer platform. Signed-in calls return the live retailer wallet (currentBalance / thresholdBalance), FTD/MTD commission splits, historical recharge tickets, and LAPU ledger rows with pre/post balances.

Screenshots

  • Mitra screenshot 1
  • Mitra screenshot 2
  • Mitra screenshot 3
  • Mitra screenshot 4
  • Mitra screenshot 5
  • Mitra screenshot 6

API surface

  • Verify retailer OTP and issue session

    POST /v1/auth/otp/verify osint

    Confirms the SMS OTP for a retailer MSISDN and returns the session token / user token pair attached to later wallet, income, recharge and ledger requests.

    Auth: No prior session. Body carries the retailer MSISDN, the SMS OTP and the otpToken from the send-OTP step, plus deviceId / application / appVersion. The returned session token and user token are attached to every later signed-in call.

    • action
    • userIdentifier
    • otp
    • otpToken
    • isOtpThirdParty
    • deviceId
    • application
    • appVersion
    • userAgent
    • result
    • userToken
    • tokenId
    • status
    • message

    Illustrative example reconstructed from the app's interface — not a live capture.

    POST /v1/auth/otp/verify HTTP/1.1
Content-Type: application/json

{
  "action": "consumeAPI",
  "userIdentifier": "9876543210",
  "otp": "482913",
  "otpToken": "otp-tok-9f2a",
  "isOtpThirdParty": "0",
  "deviceId": "a1b2c3d4e5f6",
  "application": "Retailer",
  "appVersion": "635",
  "userAgent": "android"
}
    {
  "result": {
    "deviceId": "a1b2c3d4e5f6",
    "userIdentifier": "9876543210",
    "userToken": "usr-tok-7c11",
    "tokenId": "sess-4e90ab"
  },
  "status": {
    "status": "SUCCESS",
    "message": "OTP verified"
  }
}

    Derived from the app's interface; endpoint details are illustrative, not a live capture.

    • Reconstructed from the app's OTP login flow.
    • Matches the session fields the home screen attaches to every signed-in request.

  • Fetch retailer wallet balance

    POST /v1/retailers/wallet openbanking

    Returns the retailer's live prepaid/LAPU wallet balance and the low-balance threshold shown on the Mitra home screen.

    Auth: Session token from the OTP verify call, sent with the retailer MSISDN and deviceId in the session envelope.

    • token
    • currentBalance
    • thresholdBalance
    • status
    • message

    Illustrative example reconstructed from the app's interface — not a live capture.

    POST /v1/retailers/wallet HTTP/1.1
Content-Type: application/json

{
  "action": "consumeAPI",
  "userIdentifier": "9876543210",
  "tokenID": "sess-4e90ab",
  "deviceId": "a1b2c3d4e5f6",
  "application": "Retailer",
  "appVersion": "635",
  "userAgent": "android",
  "additionalRequestParams": {
    "token": "sess-4e90ab"
  }
}
    {
  "responseObject": {
    "currentBalance": 18450.75,
    "thresholdBalance": 500.0
  },
  "status": {
    "status": "SUCCESS",
    "message": "Balance fetched"
  }
}

    Derived from the app's interface; endpoint details are illustrative, not a live capture.

    • Reconstructed from the wallet card on the app's home screen.
    • Matches the balance and low-balance threshold shown to the retailer.

  • Fetch retailer income and commissions

    POST /v1/retailers/earnings openfinance

    Returns month-to-date and day-to-date retailer earnings split across LAPU income, R-offer commission, OTF commission and scheme-related payouts.

    Auth: Session token from the OTP verify call, sent with the retailer MSISDN and deviceId in the session envelope.

    • token
    • totalMtd
    • totalFtd
    • lapuIncomeResponse
    • lapuIncomeMtd
    • lapuIncomeFtd
    • lapuIncome
    • rOfferCommissionResponse
    • mtd
    • ftd
    • amount
    • transactionId
    • date
    • otfCommissionResponse
    • schemeRelatedCommissionResponses

    Illustrative example reconstructed from the app's interface — not a live capture.

    POST /v1/retailers/earnings HTTP/1.1
Content-Type: application/json

{
  "action": "consumeAPI",
  "userIdentifier": "9876543210",
  "tokenID": "sess-4e90ab",
  "deviceId": "a1b2c3d4e5f6",
  "application": "Retailer",
  "appVersion": "635",
  "additionalRequestParams": {
    "token": "sess-4e90ab"
  }
}
    {
  "responseObject": {
    "totalMtd": 12840.5,
    "totalFtd": 960.0,
    "lapuIncomeResponse": {
      "lapuIncomeMtd": 4100.0,
      "lapuIncomeFtd": 250.0,
      "lapuIncome": 4100.0
    },
    "rOfferCommissionResponse": {
      "mtd": 6200.0,
      "ftd": 480.0,
      "amount": 6200.0,
      "transactionId": 88421109,
      "date": "2026-09-26"
    },
    "otfCommissionResponse": {
      "mtd": 2540.5,
      "ftd": 230.0
    },
    "schemeRelatedCommissionResponses": []
  },
  "status": {
    "status": "SUCCESS",
    "message": "OK"
  }
}

    Derived from the app's interface; endpoint details are illustrative, not a live capture.

    • Reconstructed from the app's income dashboard.
    • Matches the FTD/MTD commission tiles split by product line.

  • List historical recharge transactions

    POST /v1/transactions/search openbanking

    Pages the retailer's recharge history with amount, customer MSISDN, agent, timestamp and success/failure status used by the My Transactions screen.

    Auth: Session token from the OTP verify call. Body also carries pageNumber, size, optional customerNumber / agentNumber and a startDate-endDate window.

    • token
    • pageNumber
    • size
    • customerNumber
    • startDate
    • endDate
    • agentNumber
    • statusCode
    • statusDesc
    • isWLREnabled
    • totalSize
    • lastFiveTransactionDetails
    • totalAmount
    • customerMobileNumber
    • transactionId
    • transactionStatus
    • transactionDateTime
    • wlrtransaction
    • agentName
    • agentNumber

    Illustrative example reconstructed from the app's interface — not a live capture.

    POST /v1/transactions/search HTTP/1.1
Content-Type: application/json

{
  "token": "sess-4e90ab",
  "pageNumber": "1",
  "size": "20",
  "customerNumber": "9810012345",
  "startDate": "2026-09-01",
  "endDate": "2026-09-26",
  "agentNumber": "9890011122"
}
    {
  "responseObject": {
    "statusCode": "200",
    "statusDesc": "SUCCESS",
    "isWLREnabled": "Y",
    "totalSize": 2,
    "lastFiveTransactionDetails": [
      {
        "totalAmount": "299.00",
        "customerMobileNumber": "9810012345",
        "transactionId": "TXN88421109",
        "transactionStatus": "SUCCESS",
        "transactionDateTime": "2026-09-26 10:14:03",
        "wlrtransaction": false,
        "wlrtransactionStatus": 0,
        "agentName": "Ramesh",
        "agentNumber": "9890011122"
      }
    ],
    "transactionStatusResponses": []
  }
}

    Derived from the app's interface; endpoint details are illustrative, not a live capture.

    • Reconstructed from the app's My Transactions history screen.
    • Matches the paged recharge rows with customer, agent and status shown in history.

  • Subscribe R-offer recharge

    POST /v1/recharge/subscribe openfinance

    Executes a prepaid R-offer recharge against the retailer wallet and returns the new accountBalance plus transactionId after mPIN confirmation.

    Auth: Session token from the OTP verify call. Body also requires the retailer mPIN plus retailerNumber / customerNumber / offerId / price.

    • retailerNumber
    • customerNumber
    • offerId
    • price
    • mpin
    • rechargeType
    • channelId
    • retailerCircle
    • connectionType
    • gst
    • latitude
    • longitude
    • httpStatus
    • responseMessage
    • transactionId
    • refTransactionNumber
    • chillarAmount
    • gstText
    • accountBalance
    • fseNumber

    Illustrative example reconstructed from the app's interface — not a live capture.

    POST /v1/recharge/subscribe HTTP/1.1
Content-Type: application/json

{
  "retailerNumber": "9876543210",
  "customerNumber": "9810012345",
  "offerId": "ROFFER_299",
  "price": "299",
  "mpin": "2580",
  "rechargeType": "PREPAID",
  "channelId": "MITRA",
  "retailerCircle": "DL",
  "connectionType": "PREPAID",
  "gst": "53.82",
  "latitude": "28.6139",
  "longitude": "77.2090"
}
    {
  "httpStatus": "200",
  "status": {
    "status": "SUCCESS",
    "message": "Recharge successful"
  },
  "responseObject": {
    "responseMessage": "Recharge of INR 299 successful",
    "transactionId": "TXN88421109",
    "refTransactionNumber": "REF772190",
    "chillarAmount": "0",
    "gstText": "Incl. GST",
    "retailerAccountBalanceAndFSEDetails": {
      "accountBalance": "18151.75",
      "fseNumber": "FSE44021"
    }
  }
}

    Derived from the app's interface; endpoint details are illustrative, not a live capture.

    • Reconstructed from the app's recharge confirmation flow.
    • Matches the mPIN prompt and post-recharge balance shown after a top-up.

  • Fetch LAPU ledger transactions

    POST /v1/ledger/entries openbanking

    Returns date-grouped LAPU ledger rows with amount, sender MSISDN, preBalance/postBalance and credit/debit flag for the retailer cashbook.

    Auth: Session token from the OTP verify call. Filter is the retailer MSISDN plus optional startDate/endDate and transaction type; pageParams carry pageState/pageOffset.

    • filterParams
    • retailerMsisdn
    • startDate
    • endDate
    • queryParam
    • parentTransactionTypeId
    • pageParams
    • pageState
    • pageOffset
    • ledgerTransactions
    • transactionId
    • amount
    • channel
    • senderCircle
    • senderMsisdn
    • transactionDateTime
    • transactionType
    • retailerCircle
    • preBalance
    • postBalance
    • isCredit
    • note
    • status

    Illustrative example reconstructed from the app's interface — not a live capture.

    POST /v1/ledger/entries HTTP/1.1
Content-Type: application/json

{
  "filterParams": {
    "retailerMsisdn": "9876543210",
    "startDate": "2026-09-01",
    "endDate": "2026-09-26",
    "queryParam": "",
    "parentTransactionTypeId": "RECHARGE"
  },
  "pageParams": {
    "pageState": null,
    "pageOffset": 0
  }
}
    {
  "httpStatus": "200",
  "status": {
    "status": "SUCCESS",
    "message": "OK"
  },
  "body": {
    "pageState": "eyJvIjoxMH0",
    "ledgerTransactions": {
      "2026-09-26": [
        {
          "transactionId": "LED99102",
          "amount": "299.00",
          "channel": "MITRA",
          "senderCircle": "DL",
          "senderMsisdn": "9810012345",
          "transactionDateTime": "2026-09-26 10:14:03",
          "transactionType": "RECHARGE",
          "retailerMsisdn": "9876543210",
          "retailerCircle": "DL",
          "status": "SUCCESS",
          "preBalance": "18450.75",
          "postBalance": "18151.75",
          "isCredit": false,
          "note": "R-offer 299"
        }
      ]
    }
  }
}

    Derived from the app's interface; endpoint details are illustrative, not a live capture.

    • Reconstructed from the app's LAPU cashbook screen.
    • Matches the date-grouped ledger rows with running pre/post balances.

Data categories

  • retailer identity
  • wallet balances
  • commissions
  • recharge transactions
  • LAPU ledger

Where teams use this data

  • Nightly LAPU wallet reconciliation

    Pull currentBalance from the wallet call and match it against the last postBalance on the ledger entries feed so an ERP can flag missing credits before the shop opens.

  • Commission payout dashboard

    Read totalMtd, lapuIncomeMtd and rOfferCommissionResponse.mtd from the earnings call to feed a partner-finance view of FTD versus MTD earnings by product line.

  • Recharge dispute lookup

    Query the transactions search by customerNumber and startDate/endDate, then join transactionId to recharge subscribe results when a subscriber claims a failed top-up.

  • Low-balance restock alert

    Compare currentBalance with thresholdBalance after each recharge subscribe call and notify the field-sales agent (fseNumber) when the retailer wallet needs a refill.

Frequently asked questions

What session fields does Mitra send after login?

The OTP verify call returns a session token and user token for the retailer MSISDN (userIdentifier). Later calls wrap those with a device id, application tag and app version in one session envelope.

Which endpoint shows the retailer wallet?

POST /v1/retailers/wallet returns currentBalance and thresholdBalance. After a recharge, the subscribe call also echoes accountBalance plus the field-sales agent id (fseNumber).

How are commissions broken down?

POST /v1/retailers/earnings returns day-to-date and month-to-date totals plus nested LAPU income, offer-commission and one-time-fee commission objects for each product line.

Where is the LAPU cashbook?

POST /v1/ledger/entries pages date-grouped rows with amount, sender MSISDN, preBalance, postBalance and a credit/debit flag for the retailer's cashbook.

More Telecom apps

Topics

  • Mitra API
  • Airtel retailer API
  • LAPU ledger
  • retailer wallet balance
  • R-offer recharge
  • Mitra commissions
  • airtel mitra endpoints

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.

Get a quote