Setu Bharat Connect BillPay

Check payment status for both BBPS and UPI. ⚠️ CRITICAL: Requires a refId for which payment link has been generated. ⚠️ IMPORTANT: Always check payment status before generating a new payment link to avoid double payments. Payment links do NOT expire after payment. NOTE: If BBPS status returns error code 'invalid-ref-id', assume BBPS status is pending.

Fetch bill details for a biller. ⚠️ CRITICAL: Always use list_billers_tool first to validate and get the correct biller ID before calling fetch_bill_tool or fetch_payment_details_tool. Only call if list_billers returned total=1 OR user explicitly chose a biller when total>1. ⚠️ CRITICAL VALIDATION REQUIREMENTS: ALWAYS validate customerParams against biller rules BEFORE calling this. Use the regex, minLength, maxLength from list_billers response. Explain validation errors to user in plain English. Suggest corrections if format is wrong. Example: If biller requires 10 digits and user provides 12, extract/suggest the correct 10-digit format before calling. Amounts are in PAISA (divide by 100 for Rupees). ⚠️ IMPORTANT: If bill fetch is successful and customer name/details are returned but no amount is present, ask the user to input the amount.

Fetch payment details (shortlink) for a bill. ⚠️ CRITICAL: Always use list_billers_tool first to validate and get the correct biller ID before calling fetch_payment_details_tool. Returns only the short link. ⚠️ IMPORTANT: The returned URL must be displayed to the customer as a clickable link with small, concise link text (e.g., 'Pay Bill', 'Recharge', 'Donate', 'Repay', 'Pay Tax', 'Pay Fees', 'Subscribe', 'Pay Rent'). Payment links do NOT expire after a payment. Always check payment status before generating a new payment link to avoid double payments. ⚠️ FOR BILL_DIRECT BILLERS: refId is NOT required (no bill fetch needed), but userAmount is required. For BILL_VALIDATE and other billers, refId is required.

Get the status and details of a dispute/complaint raised on the BBPS platform. Use the refId returned from raise_dispute (data.refId). Returns data.disposition with dispositionDescription. Uses authenticated user's mobile number for guest login cookie.

Get saved bills (bills that have been paid before). Supports pagination and filtering by date ranges and categories. Uses partner token for authentication. ⚠️ IMPORTANT: If user is asking for pending bills instead of saved bills/past payments, use get_saved_bills_tool to get saved bills, then use fetch_bill_tool with the biller ID and customer params from saved bills to fetch the current/pending bill. ⚠️ CRITICAL VALIDATION REQUIREMENTS: When using customer params from saved bills to fetch pending bills via fetch_bill_tool, ALWAYS validate customerParams against biller rules BEFORE calling fetch_bill_tool. Use the regex, minLength, maxLength from list_billers response. Explain validation errors to user in plain English. Suggest corrections if format is wrong.

Get transaction receipt PDF URL for a transaction. ⚠️ IMPORTANT: The returned URL must be displayed to the customer as a clickable link with small, concise link text (e.g., 'Download receipt', 'View receipt'). Uses partner token for authentication. ⚠️ CRITICAL: Requires BBPS transaction reference ID (BBPSTxnRefId), NOT the BBPS ref_id. Get it from: list_payments tool response (BBPSTxnRefId field) OR check_payment_status tool response (bbps_status > data > transactionId).

List billers with optional filters. No authentication required. ⚠️ CRITICAL: If total > 1, ask user which biller to use before calling fetch_bill.

List all available bill payment categories. No authentication required.

List disputes raised on the BBPS platform. Supports filtering by status, categories, months, mobile, customerId, transactionIds, paymentRefIds, billerIds, and expand options. Uses partner token and (if available) authenticated user's mobile number for guest login cookie.

List payment history. Supports pagination, filtering by status, categories, date ranges, and more. Uses partner token for authentication.

Raise a complaint/dispute on the BBPS platform for a payment made by the user. Setu submits this to BBPS. ⚠️ CRITICAL: Always ask the user if they want to raise a dispute on the BBPS platform before calling this tool. Requires BBPS transaction ID (BBPSTxnRefId from list_payments or check_payment_status). Uses authenticated user's mobile number for guest login cookie.