When Users Need to Select Plans

1. Overview

Some services require your users to choose a plan before payment - like mobile recharge plans, DTH packages, or broadband subscriptions. This guide shows you how to handle these plan selection flows in your app.

📖 This extends Flow 2: Bill Validation → Payment from the master guide

What this means for your users:

• Instead of paying a bill amount, they choose from available plans
• Plans have fixed prices and specific benefits (data, validity, channels, etc.)
• Payment happens after plan selection

1.1 Common Services That Need Plans

• Mobile Prepaid Recharge - Data plans, talk time, combo offers
• DTH/Cable TV - Channel packages, validity periods
• Broadband Services - Speed upgrades, data top-ups
• OTT Subscriptions - Monthly, annual, family plans

1.2 What You'll Build

• Plan selection screens for your users
• Integration with plan APIs
• Validation and payment flows with selected plans

2. Two User Experience Patterns

Your users will encounter one of two plan selection patterns, depending on the service:

2.1 Pattern 1: Choose From Full Catalog

User Flow: Browse plans → Select plan → Enter account details → Pay

What users see: Complete list of available plans upfront (like mobile recharge plans)

Examples: BSNL/MTNL mobile recharge, DTH packages, OTT subscriptions

2.2 Pattern 2: Get Personalized Options

User Flow: Enter account details → See custom plans → Select plan → Pay

What users see: Plans tailored to their account (like broadband upgrade options)

Examples: You Broadband plans, Airtel Wi-Fi recharge options

3. Implementation Guide

3.1 Pattern 1: Choose From Full Catalog

User Experience: Show all available plans immediately, let user choose, then collect account details.

Implementation Steps:

1. Get Available Plans → GET /api/v2/bbps/billers/plans
2. User Selects Plan + Enters Details → Your app collects both
3. Validate Account + Plan → POST /api/v2/bbps/bills/fetch/request (include plan ID)
4. Process Payment → POST /api/v2/bbps/bills/payment/request

💡 Key Point: You must include the selected plan ID when validating the account to ensure the plan is still available.

3.2 Pattern 2: Get Personalized Options

User Experience: Collect account details first, then show plans customized for that account.

Implementation Steps:

1. User Enters Account Details → Your app collects account info
2. Validate Account → POST /api/v2/bbps/bills/fetch/request (no plan ID)
3. Get Custom Plans → Response includes plans available for this account
4. User Selects Plan → Your app presents the options
5. Process Payment → POST /api/v2/bbps/bills/payment/request (include plan ID)

💡 Key Point: Plans are revealed only after account validation, so you can't show them upfront.

3.3 Quick Reference: Which Pattern to Use

3.4 How to Detect Which Pattern to Implement

Check the biller metadata from List Billers API to determine the pattern:

Pattern 1 Detection:

{
  "planRequirement": "MANDATORY"
}

Pattern 2 Detection:

{
  "planRequirement": "OPTIONAL",
  "responseType": "SELECTIVE"
}

Other billers require no plan selection.

→ Use standard Bill Validation flow

4. Pattern 1: Full Catalog Selection

What this means: All available plans can be fetched upfront and shown to users immediately.

4.1 Examples of This Pattern

4.2 Step 1: Get Available Plans

4.2.1 Fetch All Plans for a Service

Retrieve all available plans for specific billers using the dedicated endpoint (See API Reference).

Request: GET /api/v2/bbps/billers/plans?billerIds=BILLER_ID

Response:

4.2.2 Pagination Support

For billers with large plan catalogs, the API supports efficient pagination:

Initial Request: GET /api/v2/bbps/billers/plans?billerIds=YOUR_BILLER_ID&limit=1000

Pagination Response Fields:

Next Page Request: GET /api/v2/bbps/billers/plans?billerIds=YOUR_BILLER_ID&limit=100&after=LAST_PLAN_ID_FROM_PAGE_1

Pagination Example:

For a biller with 3,700 plans using limit=1000:

4.2.3 Plan Structure

Each plan object contains both mandatory and optional fields:

interface Plan {
  // Mandatory fields
  Id: string;                    // 1-32 chars, alphanumeric
  categoryType: string;          // 1-100 chars, alphanumeric  
  amountInRupees: string;        // 1-10 digits, decimals supported
  description: string;           // text with special chars allowed
  effectiveFrom: string;         // ISO date format
  effectiveTo: string;           // ISO date format
  status: "ACTIVE" | "DEACTIVATED";
  
  // Optional fields
  categorySubType?: {
    subType: string;
  };
  additionalInfo?: Array<{
    paramName: string;
    paramValue: string;
  }>;
}

4.2.4 Plan Update Webhooks

Receive real-time notifications when biller plans are modified (See Webhook Reference):

4.3 Step 2: Present Plans to Users

For Mobile Recharge: Use the first 4-5 digits of the mobile number to auto-detect operator and circle, but always let users change these values.

4.4 Step 3: Validate Account + Selected Plan

Request Format: Most static plan billers accept the plan ID as customer.customerParams[name="Id"]. Include the plan ID from Step 1 along with the user's account details.

POST /api/v2/bbps/bills/fetch/request
{
  "biller": { "id": "{{BILLER_ID}}" },
  "customer": {
    "mobile": "9999999999",
    "customerParams": [
      { "name": "Id", "value": "3" },
      { "name": "Subscriber Number", "value": "ABC12345" }
    ]
  },
  "agent": { "id": "{{AGENT_ID}}", "channel": "INT" }
}

V1 users: Use customer.billParameters instead of customer.customerParams.

Complete Request Example:

Response:

4.4.1 Check Validation Status

Request: POST /api/v2/bbps/bills/fetch/response

Response:

4.4.2 Validation Webhook

4.5 Step 4: Process Payment

Process payment for validated plans using the reference ID from validation.

Request: POST /api/v2/bbps/bills/payment/request

Response:

4.5.1 Check Payment Status

Request: POST /api/v2/bbps/bills/payment/response

Response:

4.5.2 Payment Webhook

5. Pattern 2: Personalized Options

What this means: Plans are customized based on the user's account and only shown after account validation.

5.1 Examples of This Pattern

5.2 Step 1: Validate Account (Without Plan Selection)

Validate customer account without requiring plan selection upfront.

Request: POST /api/v2/bbps/bills/fetch/request

Response:

5.3 Step 2: Get Personalized Plans from Validation Response

Request: POST /api/v2/bbps/bills/fetch/response

Response with Dynamic Plans:

5.3.1 Validation Webhook with Plans

5.4 Step 3: Process Payment with Selected Plan

Process payment including the selected plan ID in payment details.

Request: POST /api/v2/bbps/bills/payment/request

Response:

5.4.1 Check Payment Status

Request: POST /api/v2/bbps/bills/payment/response

Response with Plan ID:

5.4.2 Payment Webhook with Plan ID

It is similar to this webhook but with added plan details: