# BBPS biller registry with params — recon note

Date: 2026-11-13. Trigger: the Jan 2024 BHIM/Ram Janmabhoomi Teerth Kshetra biller finding (https://x.com/logic/status/1751498229542429173) — biller added to BHIM via app update instead of registry-driven auto-add, with biller params visible in the payload. Question: where can a non-member actually get the BBPS biller registry *with fetch params*?

## TL;DR

- The authoritative registry is NPCI's **Biller MDM API** (BBPCU-side). It is **member-only** (COU/AI credentials). NPCI publishes the count (~17,940+ billers via its top BOU, bharat-connect.com) but not the registry.
- The full schema is public (spec PDFs + BillAvenue ASP standards + COU sandbox docs from Setu/Cashfree/PayU/Razorpay/Eko).
- Real biller records with params are only findable today in **leaked/sample data on GitHub** and inside **app bundles** (BHIM bundles/queries its own catalog).
- The open-data ask: NPCI should publish the biller directory (id, name, category, coverage, fetch requirement, customer params) the way it publishes UPI app stats.

## The schema (one biller)

From BillAvenue's public BBPS technical standards PDF + live sample (`raw/npci/bbps-biller-info-sample-billavenue.xml`):

| Field | Meaning | Example |
| --- | --- | --- |
| `billerId` | unique BBPS code | `BILAVAIRTEL001`, `CCA00000NAT01` shape |
| `billerName` | display name | AIRTEL |
| `billerCategory` | 25+ categories | Mobile Prepaid, Electricity… |
| `billerAdhoc` | pay without fetch (new request ID) | true/false |
| `billerCoverage` | geographic reach | IND / state / city |
| `billerFetchRequiremet` (sic, BillAvenue typo) | MANDATORY / OPTIONAL / NOT_SUPPORTED | drives whether amount is typed vs fetched |
| `billerPaymentExactness` | Exact / Exact and above / etc | |
| `billerSupportBillValidation` | pre-pay validation API | NOT_SUPPORTED / SUPPORTED |
| `billerInputParams/paramInfo` | **the params**: `paramName`, `dataType`, `isOptional`, `minLength`, `maxLength`, `regEx`, `values` (dropdown choices), `visibility` | Mobile Number, NUMERIC, 10–10 |
| `CustomerParamGroups` | grouped inputs (some billers require several) | |
| `billerAmountOptions` | BASE_BILL_AMOUNT + fixed/extra components | |
| `billerPaymentModes` | modes + per-mode min/max in paise | UPI, NEFT, CASH… |
| `billerPaymentChannels` | INT/BSC/POS/INTB/MOBB/AGT limits | |

The JSON MDM variant (NPCI 2022 circular "006 Enhancement Biller Fetch Master Data Management (MDM) API") carries the same fields.

## Where the data actually lives

### Official (member-gated)
- Bharat Connect API Specifications PDF (134 pp) + MDM API circular: `bharat-connect.com/pdfs/notified-documents/BBPS-API-SPECIFICATIONS.pdf` and `bharat-connect.com/strapi/uploads/006_Enhancement_Biller_Fetch_MDM_API_04_11_2022_*.pdf`. **Cloudflare JS-wall** blocks sandbox + ocitwo curl (403); Google indexes the text. Older versions v13.0/v14.0 archived on Wayback at `web.archive.org/web/20220927044126*/bharatbillpay.com/images/library/circular/pdf/BBPS-API-Specifications-v14.0.pdf` (IA was flaky on fetch day; CDX metadata confirmed 200-status captures).
- BOAT (Biller Onboarding & Automated Testing) portal on bharat-connect.com — member tooling.

### Public docs describing the same registry (no data)
- BillAvenue BBPS technical standards (ASP): `billavenue.com/document/bbps_technical_standards.pdf` — **downloaded to `raw/npci/billavenue-bbps-technical-standards.pdf`**, includes Biller Info request/response XML.
- COU sandbox docs: Setu (`docs.setu.co/payments/billpay` — biller object with `customerParams[]`), Cashfree (`POST /bbps/cou/v1/billers/info` — full catalog + MDM, needs client id/secret), PayU (`bbps-sb.payu.in`), Razorpay (`/v1/bill_payments/billers`), Eko (`/ekoapi/v2/billpayments/operators`), Digiledge. All auth-gated.

### Actual records found in the wild (GitHub)
- `ShubhVaishnav/PayBills` → `app/billerInfoResponse.xml` — 4 real BillAvenue billers with full params. **Saved: `raw/npci/bbps-biller-info-sample-billavenue.xml`**.
- `udayjaggumanthri/MpayHub` — Django BBPS app with VimoPay/BillAvenue catalog sync (`apps/integrations/vimopay_bbps/catalog_sync.py` maps category codes; `persist_biller.py` persists MDM). **⚠ Also contains `BILLAVENUE_E030_REMITTER_SUPPORT_PACKET.txt` with live-looking BillAvenue UAT credentials (Institute ID, Access Code, Agent ID) committed publicly. UAT-only, but still a leak — worth a responsible-disclosure ping to the repo owner / BillAvenue.**
- Schema-only hits (49 for `billerFetchReq`, 56 for `billerAdhoc`): `KPlakshya/BBPS-*` XSDs, `stafo_rn_app` MDM TypeScript types, `Roundpay_Exchange`, `gmaxepay`, `digispay` etc — all confirm one BillAvenue/NPCI MDM shape; none ship the full catalog.

### BHIM (NPCI's own COU app)
- BHIM 2.3.1 (2020, `npci.bhim`) is React Native: billers come from its backend (`fetchBillers` API; response fields `bbpsBillerId`, `billValidationSupport`, `minAmount/maxAmount`, `customerParams` — matches MDM), cached locally. No bundled catalog in 2.3.1.
- The Jan 2024 tweet showed a newer BHIM shipping the biller **in the app update** — so current builds likely bundle the catalog (JSON in assets/bundle). That bundle = NPCI-side registry copy with params, obtainable without membership.
- Blocked on fetch day: APKPure's npci.bhim page (Turnstile in both agent-browser and Zo browser; version listing empty; default download returns the stale 2020 build), APKMirror not tried. Current BHIM needs Play-adjacent source (ocitwo + a Play-token pipeline, or apkmirror when CF cooperates).

### Old bharatbillpay.com APIs (archived)
- `api/Lead/BindBillerName`, `api/Lead/Query`, `api/Lead/OTPValidation` — biller-empanelment lead forms (biller *name* dropdown only, not the registry).
- `api/NearestBBPOutlet/GetByPincode` — archived 200; agent-outlet finder, no params.

### White-label ASP APIs (all gated)
idspay, Paysprint, Vibhu, KwikApi, Surepass, FidyPay etc. advertise "biller list with params" APIs (`api.idspay.in/v3/billers/list?category=Electricity` etc.) — every one requires signup/API key; idspay's docs page response sample is illustrative, not live.

## Next steps (if we want the full registry)

1. **BHIM current APK** → extract bundled catalog (highest-value, reproducible, NPCI-side data). Source via ocitwo against apkmirror/apkcombo, or a Play token pipeline. Compare against 2.3.1 to show the bundle-vs-registry drift (the tweet's thesis, extended).
2. **Wayback when IA recovers** → pull BBPS-API-Specifications-v14.0.pdf + MDM circular PDF (CDX snapshots confirmed); they define exact JSON MDM fields for the fetcher.
3. **Setu/Cashfree sandbox account** (free signup) → `POST /bbps/cou/v1/billers/info` with empty body returns *all* billers with MDM. Sandboxed data ≈ production registry mirror; ToS may restrict bulk export — check before harvest.
4. **The consumer ask**: NPCI/Bharat Connect publishes biller *count* but not the directory. An open biller directory (id, name, category, coverage, fetch requirement, params, adhoc/payment flags) is basic transparency — biller params are exactly where friction and dark patterns live (mandatory fetch vs adhoc, exactness, per-mode limits). Fits the payments-stat-hub catalog as a registry dataset.