telebirr wallet and finance data API

telebirr is Ethio telecom SC's mobile-money super-app for Ethiopia: customers sign in with an Ethio telecom MSISDN and PIN (or fingerprint), then send birr to a contact or merchant QR, buy airtime, pay ethio telecom bills and fuel, move money to a linked bank account, hold a USD wallet alongside the ETB balance, and open Mela micro-loans, Sanduq savings and Endekise overdraft from the finance tab. Chat pocket-money, request-money, scheduled transfers and a Visa PAN sit next to the home functions grid. It is the consumer counterpart of telebirr Partner, aimed at anyone with an Ethiopian mobile number, and it competes locally with CBE Birr, M-PESA Ethiopia and HelloCash as the telco's own wallet.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

• Sign in and load customer profile

  POST /v1/mm/session/pin osint

  Authenticates the subscriber and returns the session token plus the KYC profile used to render the home header (MSISDN, names, ID, customer level and receive-money QR).

  Auth: MSISDN plus PIN (or biometric). No prior token. Response token and accessToken become X-Auth-Token on later calls; tokenRenewalEnable / tokenRenewalIntervalTime drive session renewal.

  • token
  • accessToken
  • encryptMsisdn
  • tokenRenewalEnable
  • tokenRenewalIntervalTime
  • customer.msisdn
  • customer.firstName
  • customer.idType
  • customer.idNumber
  • customer.customerLevel
  • qrCode

  POST /v1/mm/session/pin HTTP/1.1
  Content-Type: application/json
  
  {"initiatorMsisdn":"2519xxxxxxx","initiatorPin":"******","pinVersion":"1"}

  {
    "responseCode": "0",
    "responseDesc": "Success",
    "serverTimestamp": "2026-10-04T12:01:00Z",
    "token": "sess-8f21c4a0",
    "accessToken": "at-c91e2b77",
    "encryptMsisdn": "enc-msisdn",
    "supportPinLogin": "true",
    "tokenRenewalEnable": true,
    "tokenRenewalIntervalTime": 600000,
    "tokenRenewalLimit": 3,
    "qrCode": "000201...",
    "customer": {
      "msisdn": "251911223344",
      "firstName": "Abebe",
      "nickName": "Abebe",
      "idType": "NATIONAL_ID",
      "idNumber": "3124****",
      "idName": "Abebe Bekele",
      "customerLevel": "L2",
      "gender": "M",
      "birthday": "1990-03-12",
      "qrCode": "000201..."
    }
  }

• Read ETB wallet balance

  GET /v1/mm/ledger/etb openbanking

  Reads the primary telebirr ETB wallet balance shown on My Balance.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • amount
  • amountDisplay
  • currency
  • unit
  • unitType
  • responseCode

  GET /v1/mm/ledger/etb HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "responseDesc": "Success",
    "amount": "1250.50",
    "amountDisplay": "1,250.50",
    "currency": "ETB",
    "unit": "ETB",
    "unitType": "FIAT"
  }

• List multi-currency wallet balances

  GET /v1/mm/ledger/currencies openbanking

  Returns the ETB main wallet, USD wallet and reward-balance rows that populate My Balance / My USD Balance.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • balances
  • balanceId
  • accountType
  • accountTypeAlias
  • accountTypeNameDisplay
  • amount
  • amountDisplay
  • currency
  • unit
  • unitType
  • forward

  GET /v1/mm/ledger/currencies HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "balances": [
      {
        "balanceId": "BAL-ETB-1",
        "accountType": "MAIN",
        "accountTypeAlias": "telebirr",
        "accountTypeNameDisplay": "telebirr balance",
        "amount": "1250.50",
        "amountDisplay": "1,250.50",
        "currency": "ETB",
        "unit": "ETB",
        "unitType": "FIAT",
        "order": "1",
        "forward": "my_balance"
      },
      {
        "balanceId": "BAL-USD-1",
        "accountType": "USD",
        "accountTypeAlias": "usd_wallet",
        "accountTypeNameDisplay": "USD balance",
        "amount": "42.00",
        "amountDisplay": "42.00",
        "currency": "USD",
        "unit": "USD",
        "unitType": "FIAT",
        "order": "2",
        "forward": "my_usd_balance"
      }
    ]
  }

• Page wallet transaction history

  GET /v1/mm/passbook openbanking

  Pages the transaction-history screen: counterparty, type, amount and order id per wallet movement.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • transRecords
  • orderId
  • amount
  • amountDisplay
  • currency
  • transType
  • transTypeDisplay
  • oppositeName
  • executeOperatorName
  • transTime
  • startNum
  • count
  • filterTypes

  GET /v1/mm/passbook?startNum=0&count=20&startTime=2026-09-01+00:00:00&endTime=2026-10-04+23:59:59 HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "transRecords": [
      {
        "orderId": "ORD-998877",
        "amount": "499.00",
        "amountDisplay": "499.00",
        "currency": "ETB",
        "transType": "P2P",
        "transTypeDisplay": "Transfer",
        "oppositeName": "Bekele Tadesse",
        "executeOperatorName": "Abebe Bekele",
        "transTime": 1759593600000
      }
    ]
  }

• Fetch transaction receipt detail

  GET /v1/mm/passbook/{orderId} openbanking

  Loads the receipt sheet for one wallet order, including refund/reverse flags and labeled tradeDetails rows.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • paymentOrderId
  • linkedOrderId
  • linkedOrderType
  • amount
  • amountDisplay
  • currency
  • businessType
  • tradeStatus
  • tradeStatusDesc
  • tradeDesc
  • refundStatus
  • reverseStatus
  • tradeDetails

  GET /v1/mm/passbook/ORD-998877 HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "paymentOrderId": "PAY-998877",
    "linkedOrderId": "ORD-998877",
    "linkedOrderType": "P2P",
    "amount": "499.00",
    "amountDisplay": "499.00",
    "currency": "ETB",
    "businessType": "TRANSFER",
    "tradeStatus": "SUCCESS",
    "tradeStatusDesc": "Completed",
    "tradeDesc": "Send money",
    "refundStatus": "NONE",
    "reverseStatus": "NONE",
    "exportImage": true,
    "unit": "ETB",
    "unitType": "FIAT",
    "tradeDetails": [{"label": "Receiver", "value": "Bekele Tadesse"}]
  }

• Quote a wallet-to-wallet transfer

  POST /v1/mm/p2p/quote openbanking

  Quotes fee and debit amount for a P2P send and issues the prepayId the PIN confirmation screen submits.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token; requests carry initiatorMsisdn.

  • prepayId
  • oppositeName
  • originalAmount
  • feeAmount
  • actualAmount
  • balance
  • balanceDisplay
  • currency
  • expire

  POST /v1/mm/p2p/quote HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Content-Type: application/json
  
  {"initiatorMsisdn":"251911223344","receiverMsisdn":"251922334455","amount":"499.00","currency":"ETB"}

  {
    "responseCode": "0",
    "prepayId": "PRE-441122",
    "oppositeName": "Bekele Tadesse",
    "originalAmount": "499.00",
    "originalAmountDisplay": "499.00",
    "feeAmount": "2.50",
    "feeAmountDisplay": "2.50",
    "actualAmount": "501.50",
    "actualAmountDisplay": "501.50",
    "balance": "1250.50",
    "balanceDisplay": "1,250.50",
    "currency": "ETB",
    "expire": "120",
    "unit": "ETB",
    "unitType": "FIAT"
  }

• Execute a wallet-to-wallet transfer

  POST /v1/mm/p2p/commit openbanking

  Commits a PIN-confirmed P2P transfer and returns orderId, transId and the debit breakdown shown on the result screen.

  Auth: Session X-Auth-Token plus encrypted initiatorPin and pinVersion for money-moving calls.

  • prepayId
  • initiatorPin
  • pinVersion
  • notes
  • fundsSource
  • orderId
  • transId
  • orderStatus
  • originalAmount
  • feeAmount
  • actualAmount
  • currency
  • transTime

  POST /v1/mm/p2p/commit HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Content-Type: application/json
  
  {"prepayId":"PRE-441122","initiatorPin":"******","pinVersion":"1","notes":"rent","fundsSource":"WALLET"}

  {
    "responseCode": "0",
    "orderId": "ORD-998877",
    "transId": "TXN-110022",
    "orderStatus": "SUCCESS",
    "businessType": "TRANSFER",
    "originalAmount": "499.00",
    "originalAmountDisplay": "499.00",
    "feeAmount": "2.50",
    "feeAmountDisplay": "2.50",
    "actualAmount": "501.50",
    "actualAmountDisplay": "501.50",
    "currency": "ETB",
    "transTime": "2026-10-04 12:05:11",
    "title": "Transfer successful"
  }

• List banks for wallet-to-bank payout

  GET /v1/mm/banks openbanking

  Lists destination banks (short code, masked account, holder name) for the Transfer to Bank picker.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • bankConfigs
  • recents
  • bankShortCode
  • bankName
  • bankNameI18n
  • bankAccountNo
  • holderName
  • showHolderName
  • logo

  GET /v1/mm/banks HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "bankConfigs": [
      {
        "bankShortCode": "CBE",
        "bankName": "Commercial Bank of Ethiopia",
        "bankNameI18n": "Commercial Bank of Ethiopia",
        "bankAccountNo": "1000********12",
        "holderName": "Abebe Bekele",
        "showHolderName": "true"
      }
    ],
    "recents": []
  }

• Transfer wallet funds to a bank account

  POST /v1/mm/payout/bank openbanking

  Pays out ETB from the wallet to a linked bank card/account selected from the bank picker.

  Auth: Session X-Auth-Token plus encrypted initiatorPin and pinVersion for money-moving calls.

  • bankCardId
  • amount
  • note
  • tradeType
  • orderId
  • transId
  • orderStatus
  • originalAmount
  • feeAmount
  • actualAmount
  • currency

  POST /v1/mm/payout/bank HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Content-Type: application/json
  
  {"initiatorMsisdn":"251911223344","bankCardId":"BC-88","amount":"800.00","note":"salary","tradeType":"WALLET_TO_BANK","initiatorPin":"******","pinVersion":"1"}

  {
    "responseCode": "0",
    "orderId": "ORD-BANK-12",
    "transId": "TXN-BANK-12",
    "orderStatus": "SUCCESS",
    "originalAmount": "800.00",
    "feeAmount": "5.00",
    "actualAmount": "805.00",
    "currency": "ETB",
    "transTime": "2026-10-04 12:08:00"
  }

• Read Mela loan credit limit

  GET /v1/mm/mela/limit openfinance

  Loads the Mela / partner-bank credit limit and score that gate the loan-market and My telebirr Mela screens.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • creditLimit
  • creditScore
  • productList
  • productId
  • productName
  • avaiableLimit
  • minLimit
  • maxLimit
  • termDays
  • companyName
  • bankCode
  • fundsLenderId

  GET /v1/mm/mela/limit?bankCode=CBE&fundsLenderId=LENDER-1 HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "creditLimit": "15000",
    "creditScore": "720",
    "productList": [
      {
        "productId": "MELA-STD",
        "productName": "telebirr Mela",
        "productNameI18n": "telebirr Mela",
        "companyName": "Commercial Bank of Ethiopia",
        "avaiableLimit": "12000",
        "minLimit": "100",
        "maxLimit": "15000",
        "termDays": 30,
        "allowApplyNPL": true
      }
    ]
  }

• List Mela loan products and contracts

  GET /v1/mm/mela/contracts openfinance

  Lists the subscriber's Mela contracts with outstanding, principal and due date for My telebirr Mela.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • active
  • totalCreditAmount
  • totalOutstandingAmount
  • totalPaidAmount
  • contracts
  • contractId
  • loanBalance
  • outstandingAmount
  • principal
  • disburseAmount
  • loanDueDate
  • status
  • currentInstallment
  • totalInstallments

  GET /v1/mm/mela/contracts HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "active": true,
    "currency": "ETB",
    "totalCreditAmount": "15000.00",
    "totalOutstandingAmount": "3200.00",
    "totalPaidAmount": "1800.00",
    "contracts": [
      {
        "contractId": "CTR-1001",
        "productId": "MELA-STD",
        "productName": "telebirr Mela",
        "loanBalance": "3200.00",
        "outstandingAmount": "3200.00",
        "principal": "3000.00",
        "principalAmount": "3000.00",
        "disburseAmount": "3000.00",
        "loanDueDate": "2026-11-01",
        "status": "ACTIVE",
        "isActive": true,
        "currentInstallment": "1",
        "totalInstallments": "1",
        "currency": "ETB"
      }
    ]
  }

• Read a Mela loan contract

  GET /v1/mm/mela/contracts/{contractId} openfinance

  Opens one Mela contract with repayment schedule and disbursement/repay ledger lines.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • contractId
  • loanBalance
  • outstandingAmount
  • principal
  • disburseAmount
  • loanDueDate
  • status
  • allowRollover
  • repaymentSchedules
  • transactionList
  • transactionId
  • transactionAmount
  • transactionType
  • walletOrderID

  GET /v1/mm/mela/contracts/CTR-1001 HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "contractId": "CTR-1001",
    "productName": "telebirr Mela",
    "loanBalance": "3200.00",
    "outstandingAmount": "3200.00",
    "principal": "3000.00",
    "disburseAmount": "3000.00",
    "loanDueDate": "2026-11-01",
    "status": "ACTIVE",
    "allowRollover": true,
    "allowIntall": false,
    "repaymentSchedules": [{"dueDate": "2026-11-01", "amount": "3200.00"}],
    "transactionList": [
      {
        "transactionId": "LTX-1",
        "orderID": "ORD-LOAN-1",
        "walletOrderID": "WO-1",
        "transactionAmount": "3000.00",
        "transactionType": "DISBURSE",
        "transactionTitle": "Loan disbursement",
        "transactionTime": "2026-09-01 10:00:00",
        "transfer": "In",
        "balance": "3000.00",
        "currency": "ETB"
      }
    ]
  }

• List Sanduq saving accounts

  GET /v1/mm/sanduq/accounts openfinance

  Lists Sanduq / locked-saving accounts with principal, accrued interest, rate and maturity for My telebirr saving.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • accountItems
  • accountNo
  • productName
  • balance
  • availableBalance
  • frozenBalance
  • principalAmount
  • accruedInterest
  • productRateValue
  • maturityDate
  • openAccountDate
  • status
  • currency

  GET /v1/mm/sanduq/accounts HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "numberOfTotal": "1",
    "startNumberOfReturned": "1",
    "endNumberOfReturned": "1",
    "accountItems": [
      {
        "accountNo": "SAV-4401",
        "custAccountNo": "CA-4401",
        "accountType": "LOCKED",
        "productID": "SANDUQ-30",
        "productUnquieID": "SANDUQ-30-A",
        "productName": "telebirr Sanduq",
        "productNameI18N": "telebirr Sanduq",
        "balance": "5000.00",
        "availableBalance": "5000.00",
        "frozenBalance": "0.00",
        "unclearingBalance": "0.00",
        "principalAmount": "5000.00",
        "accruedInterest": "41.10",
        "productRateValue": "10",
        "productRateValueMode": "YEAR",
        "maturityDate": "2026-12-01",
        "openAccountDate": "2026-09-01",
        "status": "ACTIVE",
        "currency": "ETB"
      }
    ]
  }

• Wallet spend analytics (daily graph)

  GET /v1/mm/spend/daily opendata

  Feeds the in-app spend graph: period credit/debit totals and per-day bars.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • totalCreditAmount
  • totalDebitAmount
  • totalTransactionCount
  • transactionDailyList
  • daily
  • creditAmount
  • debitAmount

  GET /v1/mm/spend/daily?startTime=2026-09-01&endTime=2026-09-30 HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "totalCreditAmount": "12000.00",
    "totalDebitAmount": "8450.00",
    "totalTransactionCount": "37",
    "transactionDailyList": [
      {"daily": "2026-09-12", "creditAmount": "500.00", "debitAmount": "120.00"}
    ]
  }

• Issue a receive-money QR

  POST /v1/mm/receive/qr openbanking

  Issues the rotating merchant/person QR shown on 'use telebirr scan to pay me'.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • qrCode
  • qrCodes
  • effectiveTime
  • expiredTime
  • refreshTime

  POST /v1/mm/receive/qr HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Content-Type: application/json
  
  {"initiatorMsisdn":"251911223344"}

  {
    "responseCode": "0",
    "qrCode": "000201...",
    "qrCodes": [
      {
        "qrCode": "000201...",
        "effectiveTime": "2026-10-04T12:00:00Z",
        "expiredTime": "2026-10-04T12:05:00Z",
        "refreshTime": "30"
      }
    ]
  }

• Fetch CRM KYC record

  GET /v1/mm/kyc/profile osint

  Pulls the ethio telecom CRM KYC record (names, national ID, woreda/kebele address, photo) used in upgrades and profile.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • firstName
  • middleName
  • lastName
  • idNumber
  • dateOfBirth
  • gender
  • nationality
  • region
  • city
  • woreda
  • kebele
  • zone
  • isRegisteredInCRM
  • photo

  GET /v1/mm/kyc/profile HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "firstName": "Abebe",
    "middleName": "Kebede",
    "lastName": "Bekele",
    "idNumber": "3124****",
    "dateOfBirth": "1990-03-12",
    "gender": "M",
    "nationality": "ET",
    "nationalityDisplay": "Ethiopian",
    "region": "Addis Ababa",
    "regionDisplay": "Addis Ababa",
    "city": "Addis Ababa",
    "woreda": "04",
    "kebele": "12",
    "zone": "Arada",
    "isRegisteredInCRM": "true",
    "photo": "base64..."
  }

• Quote USD–ETB exchange rate

  GET /v1/mm/fx/quote openfinance

  Returns the USD-to-ETB rate used on My USD Balance before a currency-exchange debit.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • sourceCurrency
  • targetCurrency
  • exchangeRate
  • responseCode

  GET /v1/mm/fx/quote?sourceCurrency=USD&targetCurrency=ETB HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "responseDesc": "Success",
    "exchangeRate": "57.2500"
  }

• Read issued Visa PAN

  GET /v1/mm/card/visa openbanking

  Loads the subscriber's issued Visa PAN (or apply=false) for My Visa PAN.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • apply
  • visaPAN
  • visaBackgroundUrl
  • responseCode

  GET /v1/mm/card/visa HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "apply": true,
    "visaPAN": "4***********1234"
  }

• Read Endekise overdraft limit

  GET /v1/mm/endekise/limit openfinance

  Reads Endekise credit-pay availableLimit and totalLimit cached on the home credit-pay tile.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • limitInfo
  • limitInfo.currency
  • availableLimit
  • totalLimit
  • serverTimestamp
  • initiatorMsisdn

  GET /v1/mm/endekise/limit HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "serverTimestamp": "2026-10-04T12:10:00Z",
    "limitInfo": {
      "currency": "ETB",
      "availableLimit": "2500.00",
      "totalLimit": "5000.00"
    }
  }

• List Endekise overdraft contracts

  GET /v1/mm/endekise/contracts openfinance

  Lists Endekise credit-pay contracts with unpaid/paid amounts and due dates for Credit Pay Home.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • availableLimit
  • totalLimit
  • totalPaidAmount
  • totalUnpaidAmount
  • contracts
  • contractId
  • contractName
  • contractState
  • outstandingAmount
  • paidAmount
  • dueDate
  • periodStartDate

  GET /v1/mm/endekise/contracts HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "active": true,
    "availableLimit": "2500.00",
    "totalLimit": "5000.00",
    "totalPaidAmount": "800.00",
    "totalUnpaidAmount": "1200.00",
    "currency": "ETB",
    "contracts": [
      {
        "contractId": "OD-2201",
        "contractName": "Endekise",
        "contractState": "ACTIVE",
        "outstandingAmount": "1200.00",
        "paidAmount": "800.00",
        "disburseAmount": "2000.00",
        "principal": "2000.00",
        "totalAmount": "2000.00",
        "dueDate": "2026-10-31",
        "periodStartDate": "2026-10-01",
        "isActive": true
      }
    ]
  }

• List request-money orders

  GET /v1/mm/collect/orders openbanking

  Lists request-money (collect) orders with payee/payer identifiers and status for the Request Money inbox.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • totalCount
  • requestMoneyOrderInfos
  • requestMoneyOrderId
  • amount
  • payAmount
  • currency
  • payeeName
  • payeeIdentifier
  • payerName
  • payerIdentifier
  • status
  • statusDisplay
  • paymentMethod

  GET /v1/mm/collect/orders HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "totalCount": "2",
    "requestMoneyOrderInfos": [
      {
        "requestMoneyOrderId": "RM-7788",
        "amount": "250.00",
        "payAmount": "250.00",
        "currency": "ETB",
        "payeeName": "Abebe Bekele",
        "payeeIdentifier": "251911223344",
        "payerName": "Bekele Tadesse",
        "payerIdentifier": "251922334455",
        "status": "PENDING",
        "statusDisplay": "Waiting",
        "paymentMethod": "WALLET"
      }
    ]
  }

• List scheduled automatic payments

  GET /v1/mm/schedules openbanking

  Lists Automatic Payment schedules (amount, frequency, receiver MSISDN and reminder window) shown on the scheduled-transfer screen.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • reminderScheduleInfoDetails
  • reminderScheduleId
  • scheduleName
  • amount
  • currency
  • frequency
  • receiverMsisdn
  • firstPaymentReminderDate
  • issuePaymentReminderUntil
  • transactionType
  • needConfirmation
  • initiatorIdentifier

  GET /v1/mm/schedules HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "reminderScheduleInfoDetails": [
      {
        "reminderScheduleId": "SCH-3301",
        "scheduleName": "Rent",
        "amount": "8000.00",
        "currency": "ETB",
        "frequency": "5",
        "receiverMsisdn": "251922334455",
        "firstPaymentReminderDate": "2026-11-01",
        "issuePaymentReminderUntil": "2027-11-01",
        "transactionType": "TRANSFER",
        "needConfirmation": "true",
        "initiatorIdentifier": "251911223344"
      }
    ]
  }

• List airtime recharge denominations

  GET /v1/mm/airtime/denoms openbanking

  Loads Buy Airtime denominations (operator shortCode and priceId / finalPrice) for the airtime picker.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • topUpPageData
  • currency
  • customPriceId
  • operators
  • operatorName
  • shortCode
  • prices
  • priceId
  • priceDisplay
  • finalPrice
  • mode
  • discountDesc

  GET /v1/mm/airtime/denoms HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "topUpPageData": {
      "currency": "ETB",
      "customPriceId": "CUSTOM",
      "operators": [
        {
          "operatorName": "ethio telecom",
          "shortCode": "251",
          "prices": [
            {
              "priceId": "AIR-50",
              "priceDisplay": "50.00",
              "finalPrice": "50.00",
              "mode": "0",
              "operatorShortCode": "251",
              "order": "1",
              "discountDesc": ""
            }
          ]
        }
      ]
    }
  }

• Quote a fuel payment

  POST /v1/mm/fuel/quote openbanking

  Quotes a fuel payment (amount plus labeled displayItems) before PIN confirmation on Pay Fuel.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • amount
  • displayItems

  POST /v1/mm/fuel/quote HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Content-Type: application/json
  
  {"initiatorMsisdn":"251911223344","amount":"1500.00","currency":"ETB"}

  {
    "responseCode": "0",
    "amount": "1500.00",
    "displayItems": [
      {"label": "Station", "value": "NOC Addis"},
      {"label": "Plate", "value": "AA-3-12345"}
    ]
  }

• List billers for scheduled payments

  GET /v1/mm/billers opendata

  Lists billers (code, name, reference label) that Automatic Payment can schedule against.

  Auth: Session token and accessToken from PIN sign-in, sent as X-Auth-Token.

  • billerItems
  • billerCode
  • billerName
  • referenceName

  GET /v1/mm/billers HTTP/1.1
  X-Auth-Token: sess-8f21c4a0
  Accept: application/json

  {
    "responseCode": "0",
    "billerItems": [
      {
        "billerCode": "ETHIO-TEL",
        "billerName": "ethio telecom",
        "referenceName": "Account number"
      },
      {
        "billerCode": "AAWSA",
        "billerName": "Addis water",
        "referenceName": "Customer ID"
      }
    ]
  }

Data categories

• balances
• transactions
• transfers
• loans
• savings
• kyc
• qr_payments
• fx
• cards
• overdraft
• request_money
• scheduled_payments
• airtime
• fuel
• billers

Where teams use this data

• ETB wallet reconciliation

  Nightly jobs read amount / amountDisplay from the main wallet and the balances[] rows (accountType, currency, balanceId) so an ERP or agent till can match telebirr cash-in against its own ledger, including the USD wallet.

• P2P and bank-payout ops

  Collections platforms consume prepayId, feeAmount and actualAmount from the transfer quote, then settle on orderId / transId / orderStatus after PIN confirmation, fan wallet-to-bank payouts out through bankShortCode / bankAccountNo / holderName, and match request-money collects on requestMoneyOrderId / payeeIdentifier / status.

• Mela, Sanduq and Endekise servicing

  Credit and savings partners sync creditLimit, loanBalance, outstandingAmount and loanDueDate for Mela contracts, availableBalance, accruedInterest and maturityDate for Sanduq accounts, and availableLimit / totalLimit plus Endekise contractId / dueDate on the overdraft book.

• KYC, airtime and receive-QR overlay

  Onboarding and merchant tools reuse CRM firstName / idNumber / woreda / kebele plus the rotating qrCode with expiredTime, while airtime desks pull operators[].prices[].priceId / finalPrice and billers list billerCode / billerName without storing the PIN.

Frequently asked questions

Related apps

• CashBook - Balance & Expense
• Dhan Barse
• IndianOil ONE
• inyad Konnash: Bookkeeping App
• Paytm
• Intuit QuickBooks for Business
• Invoice Simple: Invoice Maker
• Kariyer.net Job Search

Apps similar to telebirr

• CBEBirr Plus — CBEBirr Plus is Commercial Bank of Ethiopia's internet app for the CBEBirr mobile-money wallet, covering the same operations as the USSD CBEBirr channel.
• M-PESA Safaricom Ethiopia — M-PESA is Safaricom Ethiopia's mobile-money app, advertised on the operator's site for sending payments and managing money from a Safaricom Ethiopia line.
• AwashBIRR Pro — AwashBIRR Pro is Awash Bank's mobile-money app for billers, merchants and bank customers to pay electricity and school fees, pay merchants and take a micro-loan.
• Dashen Mobile — Dashen Mobile is Dashen Bank's consumer app that replaced Amole Lite, putting the Amole wallet and a Dashen bank account on one surface for transfers and charity donations.
• Kacha — Kacha Digital Financial Services is a National Bank of Ethiopia-licensed payment-instrument issuer whose products include a consumer wallet, payments, remittance into Kacha mobile wallets, and a super-app with loans and insurance.
• CoopApp — CoopApp is Cooperative Bank of Oromia's official app for digital banking in Ethiopia, including instant money transfers from a COOP account.
• HellOOpass Personal — HellOOpass Personal is BelCash Labs' Addis Ababa wallet app for viewing and topping up a wallet, making payments and tracking history.

More Payments apps

• 

  CashBook - Balance & Expense

  Payments · 17 endpoints

• 

  Dhan Barse

  Payments · 14 endpoints

• 

  HP PAY

  Payments · 12 endpoints

• 

  IndianOil ONE

  Payments · 12 endpoints

Topics

• telebirr API
• telebirr wallet balance
• Ethio telecom mobile money
• Mela loan API
• Sanduq savings
• ETB P2P transfer
• telebirr KYC