From 4942b1b4ddf97d382a4561ddfb966ea81c35b139 Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 16:46:25 +0530 Subject: [PATCH 1/9] add guide --- .../billpay/api-integration/api-reference.mdx | 2 +- .../payments/billpay/api-integration/upms.mdx | 1067 +++++++++++++++++ 2 files changed, 1068 insertions(+), 1 deletion(-) create mode 100644 content/payments/billpay/api-integration/upms.mdx diff --git a/content/payments/billpay/api-integration/api-reference.mdx b/content/payments/billpay/api-integration/api-reference.mdx index a8a5da81..b9d4f211 100644 --- a/content/payments/billpay/api-integration/api-reference.mdx +++ b/content/payments/billpay/api-integration/api-reference.mdx @@ -1,6 +1,6 @@ --- sidebar_title: API reference page_title: COU Direct Connectivity API reference -order: 6 +order: 7 visible_in_sidebar: true --- diff --git a/content/payments/billpay/api-integration/upms.mdx b/content/payments/billpay/api-integration/upms.mdx new file mode 100644 index 00000000..f8a60dbe --- /dev/null +++ b/content/payments/billpay/api-integration/upms.mdx @@ -0,0 +1,1067 @@ +--- +sidebar_title: Integrating with UPMS +page_title: BBPS COU — Integrating with UPMS +order: 6 +visible_in_sidebar: true +--- + +# Part 1: Understanding UPMS + +This section introduces the core concepts of UPMS, its benefits, and the terminology you'll encounter while integrating. + +## 1. Introduction to UPMS + +### 1.1 What is UPMS? + +UPMS, or **Unified Presentment Management Service**, is a feature within the Bharat Bill Payment System (BBPS) designed to simplify how recurring bills are presented to customers. + +Think of it as a **subscription service for bills**. Instead of end-users manually fetching their bill details (like amount and due date) each cycle for various billers (electricity, phone, loan EMIs, etc.), UPMS allows them to register once through your app. + +Once a customer is registered for UPMS with a specific biller: + +1. The biller automatically pushes the bill details into the BBPS network when a new bill is generated. +2. BBPS makes this information available to us. +3. We then notify your app about the new bill via a webhook (callback). + +This enables a seamless, automated bill presentment experience right within your app. + +### 1.2 Why Integrate with UPMS? + +Integrating with UPMS offers significant advantages for both your app and your end-users: + +- **Improved End-User Experience**: Registered users see their bills automatically in your app, removing the need for them or you to fetch bills each cycle. This shifts bill management from a manual "pull" to an automated "push" model. +- **Timely Bill Awareness & Centralized View**: Proactive notifications about new bills and due dates help users avoid missed payments and late fees. Users can manage subscribed bills from different billers in one place—your app. +- **Increased Engagement**: Simplified bill discovery encourages users to pay digitally via your app, boosting engagement. + +### 1.3 How UPMS Works + +A simplified UPMS flow when using our APIs: + +1. **User Action**: An end-user on your app requests to register for automatic bill presentment for a specific biller (e.g., electricity provider). +2. **API Call (You → Us)**: Your app calls our **Fetch Bill and Create Registration** API with customer and mandate details. +3. **BBPS Interaction (Us → BBPS → Biller)**: We interact securely with BBPS central unit and the biller's system to validate and record the registration. +4. **Acknowledgement (Us → You)**: Our API returns a synchronous response (typically `PENDING`). +5. **Asynchronous Confirmation (Us → You)**: Final registration status (`SUCCESS` or `FAILED`) is communicated later via webhook. +6. **Bill Push (Biller → BBPS → Us)**: On a new bill cycle, the biller pushes bill details to BBPS. +7. **Bill Notification (Us → You)**: We send a callback to your configured endpoint with the bill details. +8. **Presentment (Your App)**: Your app parses the callback, identifies the user, and displays the bill. +9. **Payment (Optional)**: The user can then initiate payment for the presented bill. + +### 1.4 Who is this Guide For? + +This guide is intended for BBPS Agent Institutions integrating Setu's APIs to offer seamless recurring BBPS bill payment services, specifically leveraging UPMS features. It is valuable for individuals or teams seeking to understand the UPMS integration process. + +### 1.5 What this Guide Covers + +This document provides comprehensive information on: + +- Core UPMS concepts and terminology. +- Prerequisites and setup for integrating with Setu's UPMS APIs. +- Detailed explanations of each UPMS API endpoint. +- Handling webhook callbacks for managing registrations and bills. +- Error handling, testing procedures, and best practices. + +## 2. Key UPMS Concepts & Terminology + +### 2.1 UPMS Registration + +A UPMS registration represents an end-customer's mandate with a biller for automatic bill presentment via your app. A successful registration authorizes the biller (with customer consent) to push bill details for that customer through BBPS to us, and subsequently, to you via callbacks. + +### 2.2 Registration Lifecycle + +A UPMS registration progresses through various states: + +- **PENDING**: Initial state after a registration request is accepted but before the registration is confirmed. +- **SUCCESS**: Registration is active; bills will be presented via callbacks. +- **FAILED**: Registration could not be completed (e.g., invalid details). +- **CANCELLED**: Registration permanently cancelled by user or system. +- **DEACTIVATED**: Registration is inactive (temporarily). + +### 2.3 Registration Types + +UPMS supports two primary registration types: + +- **VIEW_N_PAY**: Standard presentment; your app receives bill notifications, displays them, and the user manually initiates payment. +- **AUTO_PAY**: Auto-payment mandate already set up. When a bill is presented, your app initiates payment automatically using Setu's Payment APIs. + +### 2.4 Mandate (`mandate`) + +A JSON object provided when creating/updating a registration, containing: + +- `registrationType`: `VIEW_N_PAY` or `AUTO_PAY`. +- `billPeriod`: Frequency of expected bills (mandatory for some billers; optional for others). +- `toDate`: Expiry date of the registration. +- `debitInfo` (for `AUTO_PAY`): + - `debitType` (string): Specifies the debit rule. Can be `FIXED_AMOUNT` (pay the exact bill amount) or `MAX_AMOUNT` (pay up to this limit). + - `amount` (number): The fixed or maximum amount set for auto-debit (value must be provided in paise). + - `currency` (number): The currency code. Use `356` for `INR`. + - `paymentMode` (string): The payment method intended for auto-debit, like `Internet Banking` or `UPI`. + - `debitDate` (string): The preferred date format (`DD-MMM`, e.g., `10-Feb`) for attempting the auto-debit each cycle. + +### 2.5 Asynchronous Operations & Callbacks + +All UPMS operations (create, update, cancel) are asynchronous: + +- **Synchronous Response**: Immediate HTTP acknowledgment (`200 OK`) indicating `PENDING` status. +- **Asynchronous Outcome**: Final status sent via webhook callback to your server. + +Additionally, you'll receive a callback for each bill generated for the registered user. + +Ensure you implement a reliable webhook listener to receive and process these callbacks. + +# Part 2: Managing Customer Registrations + +## Prerequisite: Configure Your Registration Callback URL + +You must set up and provide us with a secure HTTPS webhook endpoint URL. This endpoint is crucial as it's where our system will send asynchronous notifications (via HTTP POST) regarding: + +- **UPMS Registration Status**: Updates for creation, modification, and cancellation (`CREATE_UPMS_REGISTRATION`, `UPDATE_UPMS_REGISTRATION`, `CANCEL_UPMS_REGISTRATION` events). + +## 3. UPMS Registration Management APIs + +### 3.1 Creating a Registration (Combined with Bill Fetch) + +This process leverages the existing **Bill Fetch API** endpoint (`POST /bbps/bills/fetch/request`). To initiate a UPMS registration alongside fetching the current bill (if available), you simply include the `mandate` object in the standard Bill Fetch request. + +**Endpoint:** `POST /bbps/bills/fetch/request` +[See standard Bill Fetch API Reference](/content/payments/billpay/api-integration/apis.mdx#fetch-bill) + +**Type:** Asynchronous + +**Purpose:** To fetch the current bill and, by adding `mandate`, simultaneously initiate customer registration for future automatic bill presentments (UPMS). + +**Request Structure:** +Note the added `mandate` block for UPMS registration. +```diff +{ + "agent": { /* ... agent details ... */ }, + "biller": { /* ... biller details ... */ }, + "customer": { /* ... customer identifiers ... */ }, ++ "mandate": { /* UPMS specific: details about the mandate as described in section 2.4 */ ++ "registrationType": "VIEW_N_PAY" | "AUTO_PAY", ++ "billPeriod": "MONTHLY" | "ASPRESENTED" | …, ++ "toDate": "YYYY-MM-DD", ++ "debitInfo": { /* required for AUTO_PAY */ } ++ } +} +``` + +**Synchronous Responses:** +- **200 OK** (Accepted): Both bill fetch and UPMS registration initiated. + ```json + { + "success": true, + "data": { + // Your reference ID for tracking this specific bill fetch operation + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102201", + "upmsRegistration": { + // Status of the registration request processing by our system + "status": "PENDING", + // The unique reference ID generated for this specific UPMS registration attempt. + // Use this ID to correlate with the registration callback. + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + } + }, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` +- **200 OK** (Invalid mandate): Bill fetch initiated, no UPMS registration. + ```json + { + "success": true, + "data": { + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102201", + // Status of the registration request processing by our system + "upmsRegistration": { + // No UPMS Registration will be initiated + "status": "FAILED", + // The error details + "error": { + "code": "invalid-debit-info", + "message": "Invalid amount in debit info" + } + } + }, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` +- **400 Bad Request** (Invalid Request): Neither bill fetch nor UPMS registration is initiated. + ```json + { + "success": false, + "error": { + "code": "invalid-parameter", + "message": "Missing required field" + }, + "traceId": "CV4PE82LTNJE9O014OE1" + } + ``` +- **500 Internal Server Error**: An unexpected error occurred on the server. Neither bill fetch nor UPMS registration is initiated. + ```json + { + "success": false, + "error": { + "code": "internal-error", + "message": "Internal Error" + }, + "traceId": "CV4PE82LTNJE9O014OE1" + } + ``` + +**Handling Asynchronous Callbacks for Creation:** + +Two independent callbacks can be triggered following this API call: + +- **Bill Fetch Callback (If Bill Found):** If a current bill exists for the customer, you will receive a `BILL_FETCH` callback containing the bill details. Handle this as described in Part 3. This callback is independent of the registration success/failure. + +- **Registration Status Callback:** For registrations with initial status as `PENDING`, you will receive a `CREATE_UPMS_REGISTRATION` callback to inform you of the final outcome of the registration attempt identified by `upmsRegistration.refId` from the synchronous response. + +**`CREATE_UPMS_REGISTRATION` Callback:** + +- **Event Type:** `event: "CREATE_UPMS_REGISTRATION"` +- **Timestamp:** `timeStamp` (ISO 8601 format) +- **Correlation:** `refId` (Matches the `upmsRegistration.refId` from the sync response, e.g., `HENSVVR4QOS7X1UGPY7JGUV444P10102202`) +- **Trace ID:** `traceId` (For logging/debugging) +- **Outcome:** Check the `data`, `duplicate`, and `error` fields within the callback payload: + + - **For successful registrations:** + - The `data` field will be present, and the `error` field will be absent. + - The `registration` object within `data` will contain the full details of the newly created registration. + + ```json + // Example SUCCESS Callback Payload + { + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "D07LJTJ71N0PUBJKS640", + "timeStamp": "2025-04-28T16:05:34.762+05:30", + "data": { + "registration": { + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605", // Unique reference ID for this registration + "status": "SUCCESS", // Final status of the registration + "biller": { // Same as the biller object in the request + "id": "ABLP01000ANP03" + }, + "customer": { // Same as the customer object in the request, except for the name field + "customerParams": [ + { + "name": "Roll No", + "value": "14989991" + } + ], + "mobile": "7378926241", + "name": "Anjali Desai" // NEW: Optional, only present if the biller shares the customer name + }, + "mandate": { // Same as the mandate object in the request + "billPeriod": "ASPRESENTED", + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Debit Card", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" + }, + "createdAt": "2025-04-28T10:35:33Z", // Timestamp of the registration creation + "updatedAt": "2025-04-28T10:35:34Z" // Timestamp of the last registration modification + } + }, + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605" // Matches registration.refId + } + ``` + + - **For failed registration attempts:** + - The `error` object will be present, containing: + - `code` (string): The error code (Note: Field name might be `Code` as per example). + - `message` (string): A description of the error (Note: Field name might be `Message` as per example). + - The `data` object will be absent. + + ```json + // Example FAILED Callback Payload + { + "event": "CREATE_UPMS_REGISTRATION", + "timeStamp": "2025-03-11T10:20:00.000+05:30", + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102204", // Reference ID of the FAILED attempt from sync response + "error": { + "Code": "biller-registration-failed", + "Message": "Failed to register with Biller" + }, + "traceId": "D07LJTJ71N0PUBJKS640" // Trace ID for this callback + } + ``` + + > **Note:** The error object within failed *callback* payloads uses `Code` and `Message` (PascalCase) field names. + + - **For duplicate registrations:** + - The `data` field will be present, and the `error` field will be absent. + - The `duplicate` object within `data` indicates that a previous registration attempt was `SUCCESS`/`PENDING`. Details of the existing registration can be found here. + - `refId`: The reference ID of the existing successful/pending registration. + - `code`: Code indicating the duplicate situation (e.g., `duplicate-upms-registration`). + - `message`: Description of the duplicate situation. + + ```json + // Example Duplicate Callback Payload + { + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "CVVQVLN5STDFRUU0LLFG", + "timeStamp": "2025-04-16T18:55:42.758+05:30", + "data": { + "duplicate": { + "code": "duplicate-upms-registration", + "message": "Successful UPMS registration already exists", + "refId": "CVVQFN8BT5ONNAN3JCO059wmPQX51061821" // Ref ID of the EXISTING registration + } + }, + "refId": "CVVQVLGBT5ONNAN3JD90qXrHAWg51061855" // Ref ID of the DUPLICATE attempt from sync response + } + ``` + +**Action:** Update your internal registration record based on the callback status and response details (`registration`, `error`, or `duplicate`). + +### 3.2 Viewing Registration Details + +This synchronous endpoint allows you to retrieve the current status and details of a specific, existing UPMS registration immediately. + +**Endpoint:** `GET /upms/registrations/{upmsRegistrationRefID}` + +**Purpose:** To check the details and current status of a UPMS registration. + +**Endpoint Type:** Synchronous. The response contains the full, current details of the registration. + +**Request Breakdown:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The unique reference ID of the UPMS registration you want to view (obtained from a successful `CREATE_UPMS_REGISTRATION` callback, e.g., `D07LJTB71N0PGH5KG32G6dH2QjK51181605`). + +**Response Breakdown:** + +- **On Success (Registration Found): HTTP 200 OK** + ```json + { + "data": { + "biller": { + "id": "ABLP01000ANP03" + }, + "createdAt": "2025-04-24T14:38:46.377Z", + "customer": { + "customerParams": [ + { + "name": "Roll No", + "value": "27257063" + } + ], + "mobile": "9039403265", + "name": "Priya Shukla" + }, + "mandate": { + "billPeriod": "ASPRESENTED", + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Internet Banking", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" + }, + "refId": "D054PTM52FL7R8CJPQ90GZ2ORTG51142008", // Unique reference ID of the registration + "status": "SUCCESS", // Current status + "updatedAt": "2025-04-24T14:38:47.389Z" + }, + "success": true, + "traceId": "D055CNT3GMB863CND9LG" + } + ``` + +- **On Not Found: HTTP 404 Not Found** + ```json + { + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` + +- **On Bad Request: HTTP 400 Bad Request** (e.g., invalid format for `upmsRegistrationRefID`). + ```json + { + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "invalid-ref-id", + "message": "Ref ID length must be 35 characters" + } + } + ``` + +- **On Server Error: HTTP 500 Internal Server Error** + ```json + { + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "internal-error", + "message": "Internal Error" + } + } + ``` + +**Action:** Update your internal registration record based on the API response. + +### 3.3 Updating a Registration + +This asynchronous endpoint allows modification of certain fields of an active UPMS registration. + +**Endpoint:** `PATCH /upms/registrations/{upmsRegistrationRefID}` + +**Purpose:** To modify specific details of an existing, active UPMS registration. + +**Endpoint Type:** Asynchronous. The API call acknowledges the request, and the final result is delivered via callback. + +**Modifiable Mandate Details:** + +- `registrationType` +- `billPeriod` (restrictions may apply) +- `toDate` +- `debitInfo.debitType` +- `debitInfo.amount` +- `debitInfo.debitDate` (restrictions may apply) + +**Request Breakdown:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The ID of the registration to update. +- **Body:** Include only the fields you want to modify within the `mandate` object. + + ```json + // Example: Update expiry date and debit amount + { + "mandate": { + "toDate": "2025-12-31", + "debitInfo": { + "amount": 750000 // 7500.00 INR + } + } + } + ``` + +**Synchronous Response (Acknowledgment):** + +Confirms receipt and basic validation of the update request. + +- **On Acceptance: HTTP 200 OK** + ```json + { + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` + +- **On Bad Request: HTTP 400 Bad Request** (Invalid field, invalid value, trying to update non-modifiable field). + ```json + { + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "invalid-ref-id", // Example code, could vary + "message": "Ref ID length must be 35 characters" // Example message + } + } + ``` + +- **On Not Found: HTTP 404 Not Found** (Registration doesn't exist or is not in an updatable state). + ```json + { + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` + +- **On Server Error: HTTP 500 Internal Server Error** + ```json + { + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "internal-error", + "message": "Internal Error" + } + } + ``` + +**Handling the Asynchronous Callback for Update:** + +You will receive an `UPDATE_UPMS_REGISTRATION` callback with the final outcome. + +**`UPDATE_UPMS_REGISTRATION` Callback:** + +- **Event Type:** `event: "UPDATE_UPMS_REGISTRATION"` +- **Timestamp:** `timeStamp` +- **Correlation:** `refId` (Matches the `upmsRegistrationRefID` from the PATCH request path). +- **Trace ID:** `traceId` +- **Outcome:** + + - **If the update was successful:** + - The `data` object will be present and the `error` object will be absent. + - The `registration` object in `data` will contain the complete, updated details of the registration. Use this to refresh your stored data. + + ```json + { + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", + "timeStamp": "2025-04-28T17:16:59.941+05:30", + "data": { + "registration": { + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "SUCCESS", + "biller": { + "id": "ABLP01000ANP03" + }, + "customer": { + "customerParams": [ + { + "name": "Roll No", + "value": "67d88976" + } + ], + "mobile": "9039403265", + "name": "Gautam Rajput" + }, + "mandate": { + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Internet Banking", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" // Note: This was the updated value in the example + }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Reflects the update time + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" + } + ``` + + - **If the update failed:** + - The `error` object will contain the `code` and `message` explaining the failure (Note: Field names might be `Code`/`Message`). + - The `data` object will be absent. + + ```json + { + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", + "timeStamp": "2025-04-28T17:54:07.062+05:30", + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted update + "error": { + "Code": "biller-update-registration-failed", + "Message": "Failed to update registration with Biller" + } + } + ``` + + > **Note:** The error object within failed *callback* payloads uses `Code` and `Message` (PascalCase) field names. + +**Action:** Update your internal registration record based on the callback status and details. + +### 3.4 Cancelling a Registration + +This asynchronous endpoint permanently cancels an existing UPMS registration. + +**Endpoint:** `DELETE /upms/registrations/{upmsRegistrationRefID}` + +**Purpose:** + +- To permanently stop automatic bill presentments and any associated auto-debits for a specific UPMS registration. +- Once cancelled, the same registration cannot be reactivated. A new registration will need to be created if the user wishes to re-enable automatic presentment. + +**Endpoint Type:** Asynchronous. The API acknowledges the request, and confirmation comes via callback. + +**Request Breakdown:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The ID of the registration to cancel. +- **Body:** None + +**Synchronous Response (Acknowledgment):** + +Confirms receipt of the cancellation request. + +- **On Acceptance: HTTP 200 OK** + ```json + { + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` + +- **On Bad Request: HTTP 400 Bad Request** (e.g., invalid `upmsRegistrationRefID` format). + ```json + { + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "invalid-ref-id", + "message": "Ref ID length must be 35 characters" + } + } + ``` + +- **On Not Found: HTTP 404 Not Found** (Registration doesn't exist). + ```json + { + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` + +- **On Conflict: HTTP 409 Conflict** (e.g., registration is already cancelled or in a state that cannot be cancelled). + ```json + { + "success": false, + "error": { + "code": "invalid-state-transition", + "message": "Registration is already cancelled or in a state that cannot be cancelled" + }, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` + +- **On Server Error: HTTP 500 Internal Server Error** + ```json + { + "success": false, + "traceId": "C3SFG0O6N88R6UI7EQ", + "error": { + "code": "internal-error", + "message": "Internal Error" + } + } + ``` + +**Handling the Asynchronous Callback for Cancellation:** + +You will receive a `CANCEL_UPMS_REGISTRATION` callback confirming the outcome. + +**`CANCEL_UPMS_REGISTRATION` Callback Details:** + +- **Event Type:** `event: "CANCEL_UPMS_REGISTRATION"` +- **Timestamp:** `timeStamp` +- **Correlation:** `refId` (Matches the `upmsRegistrationRefID` from the DELETE request path). +- **Trace ID:** `traceId` +- **Outcome:** + + - **If the cancellation was successful:** + - The `data` object will be present and the `error` object will be absent. + - The `registration` object in `data` will contain the details of the registration, now marked with `status: "CANCELLED"`. + + ```json + { + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", // Example Trace ID + "timeStamp": "2025-04-28T17:16:59.941+05:30", // Example Timestamp + "data": { + "registration": { + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "CANCELLED", + "biller": { /* ... biller details ... */ }, + "customer": { /* ... customer details ... */ }, + "mandate": { /* ... mandate details ... */ }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Time of cancellation + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" + } + ``` + + - **If the cancellation failed:** + - The `error` object will contain the `code` and `message` explaining the failure (Note: Field names might be `Code`/`Message`). + - The `data` object will be absent. + + ```json + { + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", // Example Trace ID + "timeStamp": "2025-04-28T17:54:07.062+05:30", // Example Timestamp + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted cancellation + "error": { + "Code": "registration-cancellation-failed", // Example Error Code + "Message": "Failed to cancel registration with Biller" // Example Error Message + } + } + ``` + + > **Note:** The error object within failed *callback* payloads uses `Code` and `Message` (PascalCase) field names. + +**Action:** Update the status of the registration in your system to `CANCELLED` upon successful confirmation via the callback. + +# Part 3: Handling Bills and Payments + +Once a customer is successfully registered for UPMS (see Part 2), the core value proposition comes into play: receiving automatic bill presentments. This part guides you on how to handle these presented bills and integrate them into your payment flows. + +## Prerequisite: Configure Your Skip Payment Callback URL + +You must set up and provide us with a secure HTTPS webhook endpoint URL. This endpoint is crucial as it's where our system will send asynchronous notifications (via HTTP POST) regarding presented bills and skipped payments (`BILL_FETCH`, `SKIP_PAYMENT` events). + +## 4. Receiving Presented Bills + +The primary way you receive details about a newly generated bill for a registered customer is through the standard **Bill Notification callback** (`BILL_FETCH` event). This is the same event used for responses to manual bill fetches, but includes an identifier for UPMS. + +When a new bill is available for a registered customer, the flow is: + +1. **Bill Generation**: The biller generates a new bill for the customer. +2. **Push to BBPS**: The biller pushes the bill to the BBPS Central Unit. +3. **Notification to COU**: BBPS identifies the UPMS registration and notifies us. +4. **Callback to You**: We send a `BILL_FETCH` webhook with the bill details. ([See standard BILL_FETCH Callback Structure](/content/payments/billpay/api-integration/webhooks.mdx#bill-fetch-webhook)) +5. **Your Processing**: + - Acknowledge with HTTP `200 OK`. + - Parse the JSON payload. + - **Check for `upmsRegistrationRefId`**: Use this field to identify the UPMS registration associated with the bill. + - Extract the bill object(s) from `data.bills`. + - Store or update the bill in your system, associate with the user. + - Display bill details in your app. + +**Example `BILL_FETCH` Callback (for UPMS Presentment):** +Note the presence of `upmsRegistrationRefId` indicating this is for a registered subscription. +```json +{ + "event": "BILL_FETCH", + "timeStamp": "2025-04-17T17:56:55.159+05:30", + "data": { + "additionalInfo": [ + { + "name": "Biller Unique Number", + "value": "Scaroasis" + } + ], + "billerResponseType": "SINGLE", + "billerSelectionType": null, + "bills": [ + { + "amount": 83400, + "billDate": "2025-04-17", + "billNumber": "BILL-226131", + "billPeriod": "MONTHLY", + "customerName": "Nitin Gupta", + "dueDate": "2025-05-02", + "paymentOptions": [ + { + "amount": 75060, + "name": "Early Payment Amount" + }, + { + "amount": 91740, + "name": "Late Payment Amount" + } + ] + } + ], + "exactness": "RANGE", + "refId": "D00F73QLFUHJFPQC2800HVDeelt51071756", // Ref ID for this specific bill fetch instance + "status": "Success", + "upmsRegistrationRefId": "D00EP9IJSBI05F06U9K0eBQWOq851071727" + } +} +``` + +> **Note**: The same webhook endpoint receives notifications for both automatically presented bills (via UPMS) and bills retrieved through manual fetch requests (using separate Bill Fetch API). You can distinguish between these two scenarios by checking the `upmsRegistrationRefId` field within the callback's data object: +> - If `upmsRegistrationRefId` is present (not null), this callback represents an automatic bill presentment for a registered customer. +> - If `upmsRegistrationRefId` is absent or null, this callback is the result of a manual bill fetch request. + +## 5. Initiating Payment for Presented Bills + +When a user opts to pay a presented bill: + +1. **Invoke Payment API**: Construct and send a request to our BBPS Payment API endpoint. ([See Pay Bill API Reference](/content/payments/billpay/api-integration/apis.mdx#pay-bill)) +2. **Follow Payment Flow**: Handle the response and subsequent steps (e.g., status checks, notifications) as defined in the Payment API documentation. + +## 6. Handling Skipped Payments + +Sometimes, a user might pay a bill through a different channel (e.g., directly on the biller's website, via another app) after it has been presented to them in your application via UPMS. To avoid showing already-paid bills as pending, Setu provides a mechanism to notify you about such payments. + +### 6.1 SKIP_PAYMENT Callback Flow + +If a bill is paid elsewhere after presentation, you'll receive a `SKIP_PAYMENT` callback: + +1. **Payment Elsewhere**: User pays via another BBPS channel. +2. **Notification to Us**: BBPS detects external payment and informs us. +3. **Callback to You**: We send a `SKIP_PAYMENT` webhook to your configured endpoint. +4. **Your Processing**: + - Acknowledge with HTTP `200 OK`. + - Parse `data.billRefId` and `data.dateOfPayment`. + - Locate and mark the bill as paid in your system. + +**Example `SKIP_PAYMENT` Callback:** +```json +{ + "event": "SKIP_PAYMENT", + "traceId": "D0508DIBJFBLCSGI36RG", + "timeStamp": "2025-04-25T18:16:46.716+05:30", + "data": { + "billRefId": "D050862BJFBLCSGI36N0e3qv9Zu51151816", + "dateOfPayment": "2025-04-25T18:16:44+05:30" + } +} +``` + +### 6.2 Why Handle SKIP_PAYMENT Callbacks? + +Handling SKIP_PAYMENT callbacks ensures data consistency and improves user experience: + + - **Accurate Bill Status**: Prevents users from seeing bills they've already paid elsewhere as still outstanding in your app. + - **Avoids Double Payments**: Reduces the risk of users accidentally attempting to pay the same bill twice. + - **Clean User Interface**: Keeps the list of pending bills relevant and actionable. + +# Part 4: Testing and Simulation + +This part covers the specialized APIs designed to help you test your integration, particularly your handling of asynchronous callbacks, in non-production environments. + +## 7. Introduction to Simulation APIs + +Integrating asynchronous flows, especially those involving callbacks (webhooks), requires thorough testing. Waiting for real bill generation cycles or actual skipped payments can be slow and unpredictable during development and testing phases. + +To facilitate this, we provide Simulation APIs that allow you to manually trigger specific callback events on demand. + +**Key Purposes:** + +- **Verify Callback Handling:** Ensure your webhook listener correctly receives, parses, and processes `BILL_FETCH` and `SKIP_PAYMENT` callbacks. +- **Test Business Logic:** Test the downstream logic in your application that gets triggered by these callbacks (e.g., displaying bills, marking bills as paid). +- **Accelerate Development:** Trigger events instantly without external dependencies in lower environments. + +**❗ Limitation:** + +- **These Simulation APIs are strictly for use in lower environments only**. They will not function in the Production environment. Attempting to use them in Production will result in an error. + +**Simulatable Events:** + +- `BILL_FETCH` (via Simulate Bill Notification Callback API) +- `SKIP_PAYMENT` (via Simulate Skip Payment Callback API) + +## 8. Simulating a Bill Notification Callback + +This asynchronous API allows you to manually trigger a `BILL_FETCH` callback for a specific, active UPMS registration. + +**Endpoint:** `POST /upms/simulate/{upmsRegistrationRefID}/callbacks/bill` + +**Purpose:** To trigger the delivery of a simulated `BILL_FETCH` callback to your configured webhook endpoint for the specified `upmsRegistrationRefID`. This helps test how your system handles incoming bill presentments. + +**Endpoint Type:** Asynchronous. The API call acknowledges the request to simulate, and the actual `BILL_FETCH` callback is delivered shortly after to your webhook listener. + +**Request Structure:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `upmsRegistrationRefID` (string): The unique reference ID of the active UPMS registration for which you want to simulate a bill notification. This registration must exist and be in a state like `SUCCESS`. +- **Body:** None + +**Synchronous Response (Acknowledgment):** + +Confirms that the request to simulate the callback has been accepted. + +- **On Acceptance: HTTP 200 OK** + ```json + { + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` +- **On Bad Request: HTTP 400 Bad Request** (e.g., Invalid `upmsRegistrationRefID` format). + ```json + { + "success": false, + "error": { + "code": "invalid-registration-ref-id", + "message": "Invalid format for upmsRegistrationRefID" + }, + "traceId": "CV4PE82LTNJE9O014OE1" + } + ``` +- **On Forbidden: HTTP 403 Forbidden** - If attempted in the Production environment. + ```json + { + "success": false, + "error": { + "code": "forbidden-operation", + "message": "Simulation API not allowed in this environment" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` +- **On Not Found: HTTP 404 Not Found** - If the specified `upmsRegistrationRefID` does not exist or is not active. + ```json + { + "success": false, + "error": { + "code": "registration-not-found", + "message": "UPMS registration with the specified refId not found or inactive" + }, + "traceId": "CV4PE82LTNJE9O014OE3" + } + ``` +- **On Server Error: HTTP 500 Internal Server Error**. + ```json + { + "success": false, + "error": { + "code": "internal-error", + "message": "Internal Error" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` + +**Handling the Asynchronous Callback Outcome:** + +Shortly after receiving the 200 OK acknowledgment, your configured webhook listener endpoint should receive an HTTP POST request containing the `BILL_FETCH` callback (which shares the same `BILL_FETCH` event structure). + +- **Callback Payload:** The payload structure will follow the schema described for `BILL_FETCH` events (see Part 3, Section 4), including the `upmsRegistrationRefId` you specified in the simulation request. + +**Action:** Use this API in your test environment to verify that your webhook endpoint correctly receives, parses, and processes incoming bill notifications. Ensure you can link the received bill to the correct user based on the `upmsRegistrationRefId`. + +## 9. Simulating a Skip Payment Callback + +This asynchronous API allows you to manually trigger a `SKIP_PAYMENT` callback for a specific bill reference ID. + +**Endpoint:** `POST /upms/simulate/{billRefId}/callbacks/skip-payment` + +**Purpose:** To trigger the delivery of a simulated `SKIP_PAYMENT` callback to your configured webhook endpoint for the specified `billRefId`. This helps test how your system handles notifications that a bill, previously presented, was paid via another channel. + +**Endpoint Type:** Asynchronous. The API call acknowledges the request, and the actual `SKIP_PAYMENT` callback is delivered shortly after to your webhook listener. + +**Request Structure:** + +- **Headers:** + - `X-PARTNER-ID: ` + - `Authorization: Bearer ` + - `Content-Type: application/json` +- **Path Parameter:** + - `billRefId` (string): The unique reference ID of the specific bill instance for which you want to simulate a skip payment notification. This `billRefId` would typically have been received previously in a `BILL_FETCH` callback (either real or simulated). +- **Body:** None + +**Synchronous Response (Acknowledgment):** + +Confirms that the request to simulate the skip payment callback has been accepted. + +- **On Acceptance: HTTP 200 OK** + ```json + { + "success": true, + "traceId": "CV4PE82LTNJE9O014OE0" + } + ``` +- **On Bad Request: HTTP 400 Bad Request** - e.g., Invalid `billRefId` format, or if the bill state is incompatible (e.g., already marked paid). May include specific codes like `invalid-bill`. + ```json + { + "success": false, + "error": { + "code": "invalid-bill", + "message": "Bill reference ID not found or inactive" + }, + "traceId": "SIM4PE82LTNJE9O014OE0" + } + ``` +- **On Forbidden: HTTP 403 Forbidden** - If attempted in the Production environment. + ```json + { + "success": false, + "error": { + "code": "forbidden-operation", + "message": "Simulation API not allowed in this environment" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` +- **On Not Found: HTTP 404 Not Found** - If the specified `billRefId` does not exist. + ```json + { + "success": false, + "error": { + "code": "bill-not-found", + "message": "Bill with the specified refId not found" + }, + "traceId": "CV4PE82LTNJE9O014OE4" + } + ``` +- **On Server Error: HTTP 500 Internal Server Error**. + ```json + { + "success": false, + "error": { + "code": "internal-error", + "message": "Internal Error" + }, + "traceId": "CV4PE82LTNJE9O014OE2" + } + ``` + +**Handling the Asynchronous Callback Outcome:** + +Shortly after receiving the 200 OK acknowledgment, your configured webhook listener endpoint should receive an HTTP POST request containing the `SKIP_PAYMENT` callback. + +- **Callback Payload:** The payload structure will follow the schema described for `SKIP_PAYMENT` events (see Part 3, Section 6.1). It will include `event: "SKIP_PAYMENT"`, `timeStamp`, `traceId`, and a `data` object containing the `billRefId` you specified and a `dateOfPayment`. + +**Action:** Use this API in your test environment to verify that your webhook endpoint correctly receives `SKIP_PAYMENT` events and that your application logic correctly identifies the bill using `billRefId` and updates its status appropriately (e.g., marks it as paid, removes it from pending lists). + +## 10. General Testing Recommendations + +- **Webhook Listener:** Ensure you have a stable and publicly accessible webhook listener endpoint configured in our system for your Sandbox/UAT environment before using the simulation APIs. +- **Test Scenarios:** Use the simulation APIs to test various scenarios: + - Successful reception and processing of `BILL_FETCH`. + - Successful reception and processing of `SKIP_PAYMENT`. + - Handling potential errors if simulation is called with non-existent `upmsRegistrationRefId` or `billRefId`. +- **Correlation:** Pay attention to correlating the simulation API call with the resulting callback using `traceId` and the relevant reference IDs (`upmsRegistrationRefId`, `billRefId`). +- **Idempotency:** While simulating, consider how your webhook handler deals with potentially receiving the same callback event more than once. + +This concludes the guide on integrating with Setu's UPMS APIs. + + From 86b5cf2d45173da4d36025ad251f4bbecfa1ea6e Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 18:41:32 +0530 Subject: [PATCH 2/9] prefix apis with /api/v2 --- content/payments/billpay/api-integration/upms.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/payments/billpay/api-integration/upms.mdx b/content/payments/billpay/api-integration/upms.mdx index f8a60dbe..d540bbf4 100644 --- a/content/payments/billpay/api-integration/upms.mdx +++ b/content/payments/billpay/api-integration/upms.mdx @@ -121,9 +121,9 @@ You must set up and provide us with a secure HTTPS webhook endpoint URL. This en ### 3.1 Creating a Registration (Combined with Bill Fetch) -This process leverages the existing **Bill Fetch API** endpoint (`POST /bbps/bills/fetch/request`). To initiate a UPMS registration alongside fetching the current bill (if available), you simply include the `mandate` object in the standard Bill Fetch request. +This process leverages the existing **Bill Fetch API** endpoint (`POST /api/v2/bbps/bills/fetch/request`). To initiate a UPMS registration alongside fetching the current bill (if available), you simply include the `mandate` object in the standard Bill Fetch request. -**Endpoint:** `POST /bbps/bills/fetch/request` +**Endpoint:** `POST /api/v2/bbps/bills/fetch/request` [See standard Bill Fetch API Reference](/content/payments/billpay/api-integration/apis.mdx#fetch-bill) **Type:** Asynchronous @@ -329,7 +329,7 @@ Two independent callbacks can be triggered following this API call: This synchronous endpoint allows you to retrieve the current status and details of a specific, existing UPMS registration immediately. -**Endpoint:** `GET /upms/registrations/{upmsRegistrationRefID}` +**Endpoint:** `GET /api/v2/upms/registrations/{upmsRegistrationRefID}` **Purpose:** To check the details and current status of a UPMS registration. @@ -433,7 +433,7 @@ This synchronous endpoint allows you to retrieve the current status and details This asynchronous endpoint allows modification of certain fields of an active UPMS registration. -**Endpoint:** `PATCH /upms/registrations/{upmsRegistrationRefID}` +**Endpoint:** `PATCH /api/v2/upms/registrations/{upmsRegistrationRefID}` **Purpose:** To modify specific details of an existing, active UPMS registration. @@ -606,7 +606,7 @@ You will receive an `UPDATE_UPMS_REGISTRATION` callback with the final outcome. This asynchronous endpoint permanently cancels an existing UPMS registration. -**Endpoint:** `DELETE /upms/registrations/{upmsRegistrationRefID}` +**Endpoint:** `DELETE /api/v2/upms/registrations/{upmsRegistrationRefID}` **Purpose:** @@ -888,7 +888,7 @@ To facilitate this, we provide Simulation APIs that allow you to manually trigge This asynchronous API allows you to manually trigger a `BILL_FETCH` callback for a specific, active UPMS registration. -**Endpoint:** `POST /upms/simulate/{upmsRegistrationRefID}/callbacks/bill` +**Endpoint:** `POST /api/v2/upms/simulate/{upmsRegistrationRefID}/callbacks/bill` **Purpose:** To trigger the delivery of a simulated `BILL_FETCH` callback to your configured webhook endpoint for the specified `upmsRegistrationRefID`. This helps test how your system handles incoming bill presentments. @@ -972,7 +972,7 @@ Shortly after receiving the 200 OK acknowledgment, your configured webhook liste This asynchronous API allows you to manually trigger a `SKIP_PAYMENT` callback for a specific bill reference ID. -**Endpoint:** `POST /upms/simulate/{billRefId}/callbacks/skip-payment` +**Endpoint:** `POST /api/v2/upms/simulate/{billRefId}/callbacks/skip-payment` **Purpose:** To trigger the delivery of a simulated `SKIP_PAYMENT` callback to your configured webhook endpoint for the specified `billRefId`. This helps test how your system handles notifications that a bill, previously presented, was paid via another channel. @@ -1065,3 +1065,4 @@ Shortly after receiving the 200 OK acknowledgment, your configured webhook liste This concludes the guide on integrating with Setu's UPMS APIs. + From 7df22d865a05d326bb1e38aea5a73e8ad23886ac Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 18:50:35 +0530 Subject: [PATCH 3/9] add optional line for creating registration --- content/payments/billpay/api-integration/apis.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/payments/billpay/api-integration/apis.mdx b/content/payments/billpay/api-integration/apis.mdx index 5790ca29..8ebcfa9f 100644 --- a/content/payments/billpay/api-integration/apis.mdx +++ b/content/payments/billpay/api-integration/apis.mdx @@ -30,6 +30,9 @@ For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid, +Optionally, you can also registration the customer with this biller simultaneously to receive future bills as and when they are generated (See [UPMS Integration Guide](upms.mdx)). + +
From 2e19fd3f76babd534024f57880f139b339bbbfdb Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 18:50:58 +0530 Subject: [PATCH 4/9] update FetchRequest --- .../json/payments/billpay/api-integration/FetchRequest.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api-playground/json/payments/billpay/api-integration/FetchRequest.json b/api-playground/json/payments/billpay/api-integration/FetchRequest.json index c314d6c4..e87cd99e 100644 --- a/api-playground/json/payments/billpay/api-integration/FetchRequest.json +++ b/api-playground/json/payments/billpay/api-integration/FetchRequest.json @@ -32,6 +32,10 @@ } ], "mobile": "9481773053" + }, + "mandate": { + "registrationType": "VIEW_N_PAY", + "billPeriod": "ASPRESENTED" } } } From fa671b721383a5dcd710c04eb0836b7d3cab8288 Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 19:36:32 +0530 Subject: [PATCH 5/9] add upms objects --- .../billpay/api-integration/objects.mdx | 126 +++++++++++++++++- 1 file changed, 119 insertions(+), 7 deletions(-) diff --git a/content/payments/billpay/api-integration/objects.mdx b/content/payments/billpay/api-integration/objects.mdx index a6915d07..fb93e6de 100644 --- a/content/payments/billpay/api-integration/objects.mdx +++ b/content/payments/billpay/api-integration/objects.mdx @@ -49,14 +49,28 @@ Payment modes supported by a biller. ## Customer -Customer object holds the customer mobile number and the customer bill parameters. +Customer object holds the customer mobile number and the customer bill parameters. This object is used in the V1 API. -| parameter | type | description | -| ------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------- | -| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number | -| `billParameters` | `{ name: string, value: string}[]` | Bill Parameters. The parameters to send is found in the biller details API. | -| `billParameters[].name` | `string` | Name of the bill parameter. name should match the parameter in biller details API. | -| `billParameters[].value` | `string` | Value of the bill parameter. Value is validate according to the regex found in the biller details. | +| parameter | type | description | +| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number | +| `billParameters` | `{ name: string, value: string}[]` | Bill Parameters used for standard bill fetch/payment. The parameters to send is found in the biller details API. | +| `billParameters[].name` | `string` | Name of the bill parameter. name should match the parameter in biller details API. | +| `billParameters[].value` | `string` | Value of the bill parameter. Value is validate according to the regex found in the biller details. | + +## CustomerV2 + +CustomerV2 object holds the customer mobile number and the customer bill parameters. This is a new object introduced in the V2 API. + +| parameter | type | description | +| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `mobile` | `string` (6, 10 and 20 digits) | Customer Mobile Number | +| `customerParams` | `{ name: string, value: string}[]` | Customer Parameters used for standard bill fetch/payment. The parameters to send is found in the biller details API. | +| `customerParams[].name` | `string` | Name of the customer parameter. name should match the parameter in biller details API. | +| `customerParams[].value` | `string` | Value of the customer parameter. Value is validate according to the regex found in the biller details. | +| `name` | `string` (Optional) | Customer's name as registered with the biller. Only present in UPMS registration callbacks if provided by the biller's system. | + +Note: `customerParams` is a new field introduced in the V2 API in place of `billParameters`. ## Biller @@ -125,6 +139,17 @@ Details pertaining to the Agent which initiates the transaction. Values of the f | message | `string` | Error code description | | type | `FUND_TRANSFER` or `BBPS` or `APP` | Error Type. BBPS errors are due to BBPS, and code and message field contain the actual BBPS error. | +## Error Object (Generic) + +A standard structure for representing errors in API responses or callbacks. + +| parameter | type | description | +| --------- | -------- | -------------------------------------------------------------------------------------------------------------- | +| `code` | `string` | A short code identifying the error category (e.g., `validation-error`, `biller-registration-failed`). | +| `message` | `string` | A human-readable description of the error. | + +**Note:** In some asynchronous UPMS callbacks (e.g., for failed registration/update/cancel), the field names might appear as `Code` and `Message` (PascalCase) instead of `code` and `message`. Your callback handler should accommodate this potential difference. + ## Payment Details | parameter | type | description | @@ -189,6 +214,93 @@ The Payment Bill object contains information about a specific bill to be paid. | `ASPRESENTED` | | `NA` | +## UPMS Registration Type + +Indicates the type of UPMS registration. + +| type | description | +| -------------- | ------------------------------------------------------------------------------ | +| `VIEW_N_PAY` | Standard presentment. Bills are notified, user manually initiates payment. | +| `AUTO_PAY` | Auto-payment mandate. Bills are paid automatically using pre-configured info. | + +## UPMS Debit Type + +Specifies the debit rule for `AUTO_PAY` registrations. + +| type | description | +| -------------- | ------------------------------------------------------- | +| `FIXED_AMOUNT` | Pay the exact bill amount presented. | +| `MAX_AMOUNT` | Pay the bill amount, up to the specified maximum limit. | + +## UPMS Registration Status + +Represents the lifecycle state of a UPMS registration. + +| type | description | +| ------------- | -------------------------------------------------------------------------- | +| `PENDING` | Initial state after request, before confirmation. | +| `SUCCESS` | Registration active; bills will be presented via callbacks. | +| `FAILED` | Registration could not be completed (e.g., invalid details). | +| `CANCELLED` | Registration permanently cancelled by user or system. | +| `DEACTIVATED` | Registration is temporarily inactive (currently not used, future scope). | + +## UPMS Debit Info + +Contains details for automatic debit configuration, required only when `registrationType` is `AUTO_PAY`. + +| parameter | type | description | +| ------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------- | +| `debitType` | [UPMS Debit Type](#upms-debit-type) (Mandatory) | The rule for auto-debit (`FIXED_AMOUNT` or `MAX_AMOUNT`). | +| `amount` | `integer` (Mandatory) | The fixed or maximum amount for auto-debit, in paise. | +| `currency` | `integer` (Mandatory) | Currency code (use `356` for INR). | +| `paymentMode` | [Payment Mode](#payment-mode) (Mandatory) | The payment method intended for auto-debit (e.g., `Internet Banking`, `UPI`). | +| `debitDate` | `string` (Optional) | Preferred date format (`DD-MMM`, e.g., `10-Feb`) for attempting auto-debit each cycle. | + +## UPMS Mandate + +Represents the customer's mandate details provided during UPMS registration creation or update. + +| parameter | type | description | +| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `registrationType` | [UPMS Registration Type](#upms-registration-type) (Mandatory) | `VIEW_N_PAY` or `AUTO_PAY`. | +| `billPeriod` | [Bill Period](#bill-period) (Conditional) | Frequency of expected bills (e.g., `MONTHLY`, `ASPRESENTED`). Mandatory for some billers. | +| `toDate` | `string` (YYYY-MM-DD) (Optional) | Expiry date of the registration. | +| `debitInfo` | [UPMS Debit Info](#upms-debit-info) (Optional) | Required only if `registrationType` is `AUTO_PAY`. Contains auto-debit parameters. | +| `billerParams` | `{ name: string, value: string}[]` (Optional) | Additional parameters specific to the biller for the mandate (e.g., "Low Balance Threshold"). Structure matches `billParameters`. | + +## UPMSRegistration + +Represents the complete details of a UPMS registration, typically received in webhook callbacks. + +| parameter | type | description | +| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `refId` | `string` (Mandatory) | The unique reference ID for this specific UPMS registration instance. | +| `status` | [UPMS Registration Status](#upms-registration-status) (Mandatory) | The current status of the registration (e.g., `PENDING`, `SUCCESS`, `FAILED`, `CANCELLED`, `DEACTIVATED`). | +| `biller` | [Biller](#biller) (Mandatory) | Object containing the `id` of the associated biller. | +| `customer` | [CustomerV2](#customerv2) (Mandatory) | Object containing customer details (`customerParams`, `mobile`, optionally `name`) used for registration. | +| `mandate` | [UPMS Mandate](#upms-mandate) (Mandatory) | The mandate details associated with this registration. | +| `createdAt` | `string` (ISO 8601 datetime) (Mandatory) | Timestamp when the registration was created. | +| `updatedAt` | `string` (ISO 8601 datetime) (Mandatory) | Timestamp when the registration was last updated (status change, modification, cancellation). | + +## UPMS Duplicate Info + +Indicates that a UPMS registration attempt was a duplicate of an existing one. Received within the `data` object of a `CREATE_UPMS_REGISTRATION` callback. + +| parameter | type | description | +| --------- | -------- | ------------------------------------------------------------------------------ | +| `code` | `string` | Code indicating the duplicate situation (e.g., `duplicate-upms-registration`). | +| `message` | `string` | Description of the duplicate situation. | +| `refId` | `string` | The reference ID (`refId`) of the *existing* successful/pending registration. | + +## Skip Payment Data + +Contains details about a bill payment that was skipped because it was paid via an external channel. Received within the `data` object of a `SKIP_PAYMENT` callback. + +| parameter | type | description | +| --------------- | ---------------------------- | ----------------------------------------------------------------------------- | +| `billRefId` | `string` | The unique reference ID of the specific bill instance that was skipped/paid. | +| `dateOfPayment` | `string` (ISO 8601 datetime) | Timestamp indicating when the payment occurred on the external channel. | + ## Biller Selection Type | type | description | From 5ab2ef9efb3d714da80f98cd7fdb10c60755797b Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 20:17:17 +0530 Subject: [PATCH 6/9] update webhooks for UPMS --- .../billpay/api-integration/webhooks.mdx | 354 +++++++++++++++++- 1 file changed, 350 insertions(+), 4 deletions(-) diff --git a/content/payments/billpay/api-integration/webhooks.mdx b/content/payments/billpay/api-integration/webhooks.mdx index 24c86af2..6faf8663 100644 --- a/content/payments/billpay/api-integration/webhooks.mdx +++ b/content/payments/billpay/api-integration/webhooks.mdx @@ -9,22 +9,25 @@ visible_in_sidebar: true Here is the general structure of any webhook— -{` +{`{ "traceId" : "C3SFG0O6N88R6UI7EQ", "timeStamp" : "2021-11-12T00:12:29+05:30", "event" : "BILLER_UPDATES", - "data" : {...}`} + "data" : { /* Present on success */ }, + "error" : { /* Present on failure */ } +}`} 1. `traceId` is a unique ID assigned to the error and used by Setu to debug 2. `timeStamp` denotes the time when the webhook was triggered 3. `event` is a pre-defined list of event types used to define what the webhook was triggered for -4. `data` contains the webhook payload data +4. `data` contains the webhook payload data on successful completion of the event. +5. `error` contains details about the failure if the event could not be completed successfully. It typically includes `code` (or `Code`) and `message` (or `Message`) fields. One of `data` or `error` will be present.
### Bill fetch webhook -This webhook can be used to get details of outstanding bills on BBPS. It will only be triggered if the Fetch bill API is +This webhook can be used to get details of outstanding bills on BBPS. It will only be triggered if the Fetch bill API is consumed. If the bill does not exist then suitable error message will be sent. @@ -62,6 +65,60 @@ URL : To be provided by partner`}
+> **Note**: When a bill is presented automatically for a registered customer, this callback will include an additional field `upmsRegistrationRefId` within the `data` object, linking the bill to the specific registration. +If this field is absent or null, the callback corresponds to a manual bill fetch request. See example below. + + +
+ + + Bill presentment sample request + + + + {`{ + "event": "BILL_FETCH", + "timeStamp": "2025-04-17T17:56:55.159+05:30", + "data": { + "additionalInfo": [ + { + "name": "Biller Unique Number", + "value": "Scaroasis" + } + ], + "billerResponseType": "SINGLE", + "billerSelectionType": null, + "bills": [ + { + "amount": 83400, + "billDate": "2025-04-17", + "billNumber": "BILL-226131", + "billPeriod": "MONTHLY", + "customerName": "Nitin Gupta", + "dueDate": "2025-05-02", + "paymentOptions": [ + { + "amount": 75060, + "name": "Early Payment Amount" + }, + { + "amount": 91740, + "name": "Late Payment Amount" + } + ] + } + ], + "exactness": "RANGE", + "refId": "D00F73QLFUHJFPQC2800HVDeelt51071756", // Ref ID for this specific generated bill. Use this to initiate a payment. + "status": "Success", + "upmsRegistrationRefId": "D00EP9IJSBI05F06U9K0eBQWOq851071727" // Links to the UPMS registration + } +} +`} + +
+ +
### Bill payment webhook @@ -336,4 +393,293 @@ URL : To be provided by partner`} + +### Create UPMS Registration webhook + +This webhook informs you about the final status (Success, Failed, or Duplicate) of a UPMS registration request initiated via the [Fetch Bill and Create Registration API](/content/payments/billpay/api-integration/upms.mdx#31-creating-a-registration-combined-with-bill-fetch). The `refId` in the webhook payload matches the `upmsRegistration.refId` from the synchronous API response. + +{`Method : POST +URL : To be provided by partner (Registration Callback URL)`} + + +
+ + + Create UPMS Registration sample request (Success) + + + + {`{ + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "D07LJTJ71N0PUBJKS640", + "timeStamp": "2025-04-28T16:05:34.762+05:30", + "data": { + "registration": { + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605", // Unique reference ID for this registration + "status": "SUCCESS", // Final status of the registration + "biller": { // Same as the biller object in the request + "id": "ABLP01000ANP03" + }, + "customer": { // Same as the customer object in the request, except for the name field + "customerParams": [ + { + "name": "Roll No", + "value": "14989991" + } + ], + "mobile": "7378926241", + "name": "Anjali Desai" // NEW: Optional, only present if the biller shares the customer name + }, + "mandate": { // Same as the mandate object in the request + "billPeriod": "ASPRESENTED", + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Debit Card", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" + }, + "createdAt": "2025-04-28T10:35:33Z", // Timestamp of the registration creation + "updatedAt": "2025-04-28T10:35:34Z" // Timestamp of the last registration modification + } + }, + "refId": "D07LJTB71N0PGH5KG32G6dH2QjK51181605" // Matches registration.refId +}`} + +
+ + + +
+ + + Create UPMS Registration sample request (Failed) + + + + {`{ + "event": "CREATE_UPMS_REGISTRATION", + "timeStamp": "2025-03-11T10:20:00.000+05:30", + "refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102204", // Reference ID of the FAILED attempt from sync response + "error": { + "Code": "biller-registration-failed", // Note: PascalCase field name + "Message": "Failed to register with Biller" // Note: PascalCase field name + }, + "traceId": "D07LJTJ71N0PUBJKS640" // Trace ID for this callback +}`} + +
+ + + +
+ + + Create UPMS Registration sample request (Duplicate) + + + + {`{ + "event": "CREATE_UPMS_REGISTRATION", + "traceId": "CVVQVLN5STDFRUU0LLFG", + "timeStamp": "2025-04-16T18:55:42.758+05:30", + "data": { + "duplicate": { + "code": "duplicate-upms-registration", + "message": "Successful UPMS registration already exists", + "refId": "CVVQFN8BT5ONNAN3JCO059wmPQX51061821" // Ref ID of the EXISTING registration + } + }, + "refId": "CVVQVLGBT5ONNAN3JD90qXrHAWg51061855" // Ref ID of the DUPLICATE attempt from sync response +}`} + +
+ + +
+ +### Update UPMS Registration webhook + +This webhook confirms the outcome (Success or Failed) of a request to update an existing customer registration using the [Update Registration API](/content/payments/billpay/api-integration/upms.mdx#33-updating-a-registration). The `refId` in the webhook payload matches the `upmsRegistrationRefID` used in the API request path. + +{`Method : POST +URL : To be provided by partner (Registration Callback URL)`} + + +
+ + + Update UPMS Registration sample request (Success) + + + + {`{ + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", + "timeStamp": "2025-04-28T17:16:59.941+05:30", + "data": { + "registration": { // Contains the full, updated registration details + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "SUCCESS", + "biller": { + "id": "ABLP01000ANP03" + }, + "customer": { + "customerParams": [ + { + "name": "Roll No", + "value": "67d88976" + } + ], + "mobile": "9039403265", + "name": "Gautam Rajput" + }, + "mandate": { + "billerParams": [ + { + "name": "Low Balance Threshold", + "value": "500" + } + ], + "debitInfo": { + "amount": 999999999, + "currency": 356, + "debitDate": "10-Feb", + "paymentMode": "Internet Banking", + "type": "FIXED_AMOUNT" + }, + "registrationType": "AUTO_PAY", + "toDate": "2025-12-22" + }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Reflects the update time + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" // Matches the updated registration's refId +}`} + +
+ + + +
+ + + Update UPMS Registration sample request (Failed) + + + + {`{ + "event": "UPDATE_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", + "timeStamp": "2025-04-28T17:54:07.062+05:30", + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted update + "error": { + "Code": "biller-update-registration-failed", // Note: PascalCase field name + "Message": "Failed to update registration with Biller" // Note: PascalCase field name + } +}`} + +
+ + +
+ +### Cancel UPMS Registration webhook + +This webhook confirms the outcome (Success or Failed) of a request to cancel an existing UPMS registration using the [Cancel Registration API](/content/payments/billpay/api-integration/upms.mdx#34-cancelling-a-registration). The `refId` in the webhook payload matches the `upmsRegistrationRefID` used in the API request path. + +{`Method : POST +URL : To be provided by partner (Registration Callback URL)`} + + +
+ + + Cancel UPMS Registration sample request (Success) + + + + {`{ + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07MLCSRLASJ2P3SVAI0", // Example Trace ID + "timeStamp": "2025-04-28T17:16:59.941+05:30", // Example Timestamp + "data": { + "registration": { // Contains details of the cancelled registration + "refId": "D07ML76AIQNN6974G200emsL9K451181716", + "status": "CANCELLED", + "biller": { /* ... biller details ... */ }, + "customer": { /* ... customer details ... */ }, + "mandate": { /* ... mandate details ... */ }, + "createdAt": "2025-04-28T11:46:36Z", + "updatedAt": "2025-04-28T11:46:59Z" // Time of cancellation + } + }, + "refId": "D07ML76AIQNN6974G200emsL9K451181716" // Matches the cancelled registration's refId +}`} + +
+ + + +
+ + + Cancel UPMS Registration sample request (Failed) + + + + {`{ + "event": "CANCEL_UPMS_REGISTRATION", + "traceId": "D07N6PSRLASJ2P3SVAMG", // Example Trace ID + "timeStamp": "2025-04-28T17:54:07.062+05:30", // Example Timestamp + "refId": "D07N6M6AIQNN6974G9EGH18p7p051181753", // The refId of the attempted cancellation + "error": { + "Code": "registration-cancellation-failed", // Example Error Code; Note: PascalCase + "Message": "Failed to cancel registration with Biller" // Example Error Message; Note: PascalCase + } +}`} + +
+ + +
+ +### Skip Payment webhook + +This webhook notifies you when a bill, previously presented via UPMS, has been paid through an external channel (e.g., directly on the biller's site, another app). Use this to update the bill's status in your system. + +{`Method : POST +URL : To be provided by partner (Skip Payment Callback URL)`} + + +
+ + + Skip Payment sample request + + + + {`{ + "event": "SKIP_PAYMENT", + "traceId": "D0508DIBJFBLCSGI36RG", + "timeStamp": "2025-04-25T18:16:46.716+05:30", + "data": { + "billRefId": "D050862BJFBLCSGI36N0e3qv9Zu51151816", // The refId of the bill that was paid externally + "dateOfPayment": "2025-04-25T18:16:44+05:30" // Timestamp of the external payment + } +}`} + +
+ + From ba062da704add73830c2a1273c9ea04b25a1d8d7 Mon Sep 17 00:00:00 2001 From: tanmay Date: Mon, 5 May 2025 20:27:55 +0530 Subject: [PATCH 7/9] update bill fetch request schema --- .../payments/billpay/api-integration.json | 146 +++++++++++++++++- 1 file changed, 145 insertions(+), 1 deletion(-) diff --git a/api-references/payments/billpay/api-integration.json b/api-references/payments/billpay/api-integration.json index acb0c418..9eb3254d 100644 --- a/api-references/payments/billpay/api-integration.json +++ b/api-references/payments/billpay/api-integration.json @@ -292,7 +292,111 @@ } }, "x-go-gen-location": "models", - "x-go-name": "BillerDetails" + "x-go-name": "BillerDetails", + "mandate": { + "type": "object", + "description": "Optional. Include this object to initiate a UPMS registration alongside the bill fetch.", + "required": [ + "registrationType" + ], + "properties": { + "registrationType": { + "type": "string", + "description": "Type of UPMS registration.", + "enum": [ + "VIEW_N_PAY", + "AUTO_PAY" + ] + }, + "billPeriod": { + "type": "string", + "description": "Frequency of expected bills. Mandatory for some billers, optional for others.", + "enum": [ + "ONETIME", + "DAILY", + "WEEKLY", + "BIMONTHLY", + "MONTHLY", + "QUARTERLY", + "HALFYEARLY", + "YEARLY", + "ASPRESENTED" + ] + }, + "toDate": { + "type": "string", + "format": "date", + "description": "Expiry date of the registration (YYYY-MM-DD)." + }, + "debitInfo": { + "type": "object", + "description": "Required only if registrationType is AUTO_PAY. Contains auto-debit parameters.", + "required": [ + "debitType", + "amount", + "currency", + "paymentMode" + ], + "properties": { + "debitType": { + "type": "string", + "description": "The rule for auto-debit.", + "enum": [ + "FIXED_AMOUNT", + "MAX_AMOUNT" + ] + }, + "amount": { + "type": "integer", + "description": "The fixed or maximum amount for auto-debit, in paise." + }, + "currency": { + "type": "integer", + "description": "Currency code (use 356 for INR).", + "example": 356 + }, + "paymentMode": { + "type": "string", + "description": "The payment method intended for auto-debit.", + "enum": [ + "Cash", + "Internet Banking", + "Credit Card", + "Debit Card", + "Prepaid Card", + "IMPS", + "NEFT", + "UPI", + "Wallet", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "debitDate": { + "type": "string", + "description": "Preferred date format (DD-MMM, e.g., 10-Feb) for attempting auto-debit each cycle." + } + } + }, + "billerParams": { + "type": "array", + "description": "Additional parameters specific to the biller for the mandate.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "value": { + "type": "string" + } + } + } + } + } + } } }, "x-omitempty": true @@ -451,6 +555,46 @@ "refId": { "type": "string", "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "upmsRegistration": { + "type": "object", + "description": "Status of the UPMS registration request processing by Setu. Present only if 'mandate' was included in the request.", + "required": [ + "status" + ], + "properties": { + "status": { + "type": "string", + "description": "Initial status of the registration request. Final status comes via webhook.", + "enum": [ + "PENDING", + "FAILED" + ] + }, + "refId": { + "type": "string", + "description": "Reference ID for the UPMS registration attempt. Use this to correlate with the registration callback. Only present if status is PENDING.", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "error": { + "type": "object", + "description": "Details of the error if the registration request failed synchronously (e.g., invalid mandate format). Only present if status is FAILED.", + "required": [ + "code", + "message" + ], + "properties": { + "code": { + "type": "string", + "example": "invalid-debit-info" + }, + "message": { + "type": "string", + "example": "Invalid amount in debit info" + } + } + } + } } } }, From c7eb2e53ddcbeb62920fba447bc5484f4ca9fd40 Mon Sep 17 00:00:00 2001 From: tanmay Date: Wed, 7 May 2025 15:53:23 +0530 Subject: [PATCH 8/9] minor tweak in upms.mdx --- content/payments/billpay/api-integration/upms.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/payments/billpay/api-integration/upms.mdx b/content/payments/billpay/api-integration/upms.mdx index d540bbf4..7c6505db 100644 --- a/content/payments/billpay/api-integration/upms.mdx +++ b/content/payments/billpay/api-integration/upms.mdx @@ -75,7 +75,7 @@ A UPMS registration progresses through various states: - **SUCCESS**: Registration is active; bills will be presented via callbacks. - **FAILED**: Registration could not be completed (e.g., invalid details). - **CANCELLED**: Registration permanently cancelled by user or system. -- **DEACTIVATED**: Registration is inactive (temporarily). +- **DEACTIVATED**: Registration has been deactivated. ### 2.3 Registration Types From 906a4ba119e356f6b8176bfc18fa7a1c9d5ecc88 Mon Sep 17 00:00:00 2001 From: tanmay Date: Wed, 7 May 2025 16:44:31 +0530 Subject: [PATCH 9/9] Update API Integration --- .../payments/billpay/api-integration.json | 9253 +++++++++++------ 1 file changed, 6267 insertions(+), 2986 deletions(-) diff --git a/api-references/payments/billpay/api-integration.json b/api-references/payments/billpay/api-integration.json index 9eb3254d..eadbd03c 100644 --- a/api-references/payments/billpay/api-integration.json +++ b/api-references/payments/billpay/api-integration.json @@ -22,7 +22,9 @@ "paths": { "/api/v2/auth/token": { "post": { - "tags": ["Token API"], + "tags": [ + "Token API" + ], "description": "Fetch token to be used to authorize all Setu APIs", "operationId": "fetchToken", "requestBody": { @@ -99,7 +101,10 @@ "schema": { "allOf": [ { - "required": ["expiresIn", "token"], + "required": [ + "expiresIn", + "token" + ], "type": "object", "properties": { "expiresIn": { @@ -113,7 +118,10 @@ } }, { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -136,11 +144,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -172,9 +187,10 @@ }, "/api/v2/bbps/bills/fetch/request": { "post": { - "tags": ["Fetch"], + "tags": [ + "Fetch" + ], "description": "Bill fetch request API", - "operationId": "FetchRequestV2", "parameters": [ { "name": "X-PARTNER-ID", @@ -192,30 +208,19 @@ "schema": { "allOf": [ { - "required": ["agent", "biller"], + "required": [ + "agent", + "biller" + ], "type": "object", "properties": { "agent": { - "required": ["channel", "id"], + "required": [ + "channel", + "id" + ], "type": "object", "properties": { - "os": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "iOS", - "enum": ["iOS", "Android"] - }, - "postalCode": { - "pattern": "^[1-9][0-9]{5}$", - "type": "string", - "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "600001" - }, - "terminalId": { - "type": "string", - "description": "Mandatory if channel is `ATM`, `AGT`, `KIOSK` and `BSC` . Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "6000011234" - }, "app": { "type": "string", "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", @@ -239,25 +244,6 @@ "MPOS" ] }, - "imei": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "123456789012345" - }, - "mac": { - "type": "string", - "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", - "format": "mac", - "example": "48-4D-7E-CB-DB-6F" - }, - "mobile": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", - "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" - }, "geocode": { "type": "string", "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", @@ -273,16 +259,56 @@ "description": "Mandatory if channel is `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", "example": "ICIC0000152" }, + "imei": { + "type": "string", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "123456789012345" + }, "ip": { "type": "string", "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", "format": "ipv4", "example": "124.170.23.24" + }, + "mac": { + "type": "string", + "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", + "format": "mac", + "example": "48-4D-7E-CB-DB-6F" + }, + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "os": { + "type": "string", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "iOS", + "enum": [ + "iOS", + "Android" + ] + }, + "postalCode": { + "pattern": "^[1-9][0-9]{5}$", + "type": "string", + "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "600001" + }, + "terminalId": { + "type": "string", + "description": "Mandatory if channel is `ATM`, `AGT`, `KIOSK` and `BSC` . Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "6000011234" } } }, "biller": { - "required": ["id"], + "required": [ + "id" + ], "type": "object", "properties": { "id": { @@ -292,109 +318,30 @@ } }, "x-go-gen-location": "models", - "x-go-name": "BillerDetails", - "mandate": { - "type": "object", - "description": "Optional. Include this object to initiate a UPMS registration alongside the bill fetch.", - "required": [ - "registrationType" - ], - "properties": { - "registrationType": { - "type": "string", - "description": "Type of UPMS registration.", - "enum": [ - "VIEW_N_PAY", - "AUTO_PAY" - ] - }, - "billPeriod": { - "type": "string", - "description": "Frequency of expected bills. Mandatory for some billers, optional for others.", - "enum": [ - "ONETIME", - "DAILY", - "WEEKLY", - "BIMONTHLY", - "MONTHLY", - "QUARTERLY", - "HALFYEARLY", - "YEARLY", - "ASPRESENTED" - ] - }, - "toDate": { - "type": "string", - "format": "date", - "description": "Expiry date of the registration (YYYY-MM-DD)." - }, - "debitInfo": { - "type": "object", - "description": "Required only if registrationType is AUTO_PAY. Contains auto-debit parameters.", - "required": [ - "debitType", - "amount", - "currency", - "paymentMode" - ], - "properties": { - "debitType": { - "type": "string", - "description": "The rule for auto-debit.", - "enum": [ - "FIXED_AMOUNT", - "MAX_AMOUNT" - ] - }, - "amount": { - "type": "integer", - "description": "The fixed or maximum amount for auto-debit, in paise." - }, - "currency": { - "type": "integer", - "description": "Currency code (use 356 for INR).", - "example": 356 - }, - "paymentMode": { - "type": "string", - "description": "The payment method intended for auto-debit.", - "enum": [ - "Cash", - "Internet Banking", - "Credit Card", - "Debit Card", - "Prepaid Card", - "IMPS", - "NEFT", - "UPI", - "Wallet", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "debitDate": { - "type": "string", - "description": "Preferred date format (DD-MMM, e.g., 10-Feb) for attempting auto-debit each cycle." - } - } - }, - "billerParams": { - "type": "array", - "description": "Additional parameters specific to the biller for the mandate.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - } - } - } + "x-go-name": "BillerDetails" + }, + "remitter": { + "type": "object", + "properties": { + "aadhaar": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "email": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "name": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "pan": { + "maxLength": 50, + "minLength": 1, + "type": "string" } } } @@ -402,59 +349,46 @@ "x-omitempty": true }, { - "required": ["customer"], + "required": [ + "customer" + ], "type": "object", "properties": { "customer": { "allOf": [ { - "required": ["mobile"], + "required": [ + "mobile" + ], "type": "object", "properties": { - "remitter": { - "type": "object", - "properties": { - "aadhaar": { - "maxLength": 50, - "minLength": 1, - "type": "string" - }, - "email": { - "maxLength": 50, - "minLength": 1, - "type": "string" - }, - "name": { - "maxLength": 50, - "minLength": 1, - "type": "string" - }, - "pan": { - "maxLength": 50, - "minLength": 1, - "type": "string" - } - } + "customerId": { + "type": "string", + "description": "Customer Identifier" }, "mobile": { - "maxLength": 20, + "maxLength": 22, "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", + "pattern": "^\\d{6,22}$", "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" + "description": "Mobile number with 6 to 22 digits are valid." } } }, { - "required": ["customerParams"], + "required": [ + "customerParams" + ], "type": "object", "properties": { "customerParams": { "type": "array", "description": "The bill params for fetching the bill", "items": { - "required": ["name", "value"], + "required": [ + "name", + "value" + ], "type": "object", "properties": { "name": { @@ -473,6 +407,80 @@ } } ] + }, + "mandate": { + "type": "object", + "properties": { + "billPeriod": { + "type": "string", + "description": "Mandatory for Validation & Pay billers. Allowed values: DAILY, WEEKLY, BIMONTHLY, MONTHLY, QUARTERLY, HALFYEARLY, YEARLY\nOptional for Fetch & Pay billers. Allowed values: ASPRESENTED\n", + "nullable": true, + "example": "MONTHLY", + "x-omitempty": true + }, + "billerParams": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Captures the name of the biller parameter to be sent as part of UPMS registration.", + "example": "Low Balance Threshold" + }, + "value": { + "type": "string", + "description": "The value of the biller parameter to be sent as part of UPMS registration.", + "example": "500.0" + } + }, + "description": "Optional. Only some billers require this. Details of the biller parameter to be sent as part of UPMS registration." + }, + "x-omitempty": true + }, + "debitInfo": { + "type": "object", + "properties": { + "amount": { + "type": "integer", + "description": "The fixed or maximum amount set for auto-debit (value must be provided in paise)." + }, + "currency": { + "type": "integer", + "description": "The currency code. Use `356` for `INR`." + }, + "debitDate": { + "type": "string", + "description": "The preferred date format (`DD-MMM`) for attempting the auto-debit each cycle.", + "example": "10-Feb" + }, + "paymentMode": { + "type": "string", + "description": "The payment method intended for auto-debit, allowed values:\n - Internet Banking\n - Debit Card\n - Credit Card\n - Prepaid Card\n - IMPS\n - UPI\n - Wallet\n - NEFT\n - AEPS\n - Account Transfer\n - Bharat QR", + "example": "UPI" + }, + "type": { + "type": "string", + "description": "Specifies the debit rule. Can be `FIXED_AMOUNT` (pay the exact bill amount) or `MAX_AMOUNT` (pay up to this limit).", + "example": "FIXED_AMOUNT" + } + }, + "description": "Details for debit information (mandatory when registrationType is AUTO_PAY)" + }, + "registrationType": { + "type": "string", + "description": "The type of registration (AUTO_PAY or VIEW_N_PAY)", + "example": "AUTO_PAY" + }, + "toDate": { + "type": "string", + "description": "The UPMS registration is invalid after this date. Date format is YYYY-MM-DD", + "nullable": true, + "example": "2025-01-01", + "x-omitempty": true + } + } } } } @@ -533,15 +541,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -549,78 +566,104 @@ }, "message": { "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." } } }, "refId": { "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." }, "upmsRegistration": { - "type": "object", - "description": "Status of the UPMS registration request processing by Setu. Present only if 'mandate' was included in the request.", - "required": [ - "status" - ], - "properties": { - "status": { - "type": "string", - "description": "Initial status of the registration request. Final status comes via webhook.", - "enum": [ - "PENDING", - "FAILED" - ] - }, - "refId": { - "type": "string", - "description": "Reference ID for the UPMS registration attempt. Use this to correlate with the registration callback. Only present if status is PENDING.", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "error": { - "type": "object", - "description": "Details of the error if the registration request failed synchronously (e.g., invalid mandate format). Only present if status is FAILED.", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "string", - "example": "invalid-debit-info" - }, - "message": { - "type": "string", - "example": "Invalid amount in debit info" - } + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." } - } - } - } - } - }, - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10461713" - } - } - } - } - } - }, - "400": { - "description": "Bad request", + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" + } + } + }, + "success": { + "type": "boolean", + "description": "Boolean value indicating the status of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10461713" + } + } + } + } + } + }, + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -651,11 +694,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -684,13 +734,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentBillFetchRequest" @@ -698,9 +754,10 @@ }, "/api/v2/bbps/bills/fetch/response": { "post": { - "tags": ["Fetch"], + "tags": [ + "Fetch" + ], "description": "Bill fetch response API", - "operationId": "FetchResponseV2", "parameters": [ { "name": "X-PARTNER-ID", @@ -716,12 +773,14 @@ "content": { "application/json": { "schema": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "refId": { "type": "string", - "example": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689" + "description": "The generated Reference ID for the request." } }, "x-go-name": "RefIdBasedRequest", @@ -783,7 +842,10 @@ "schema": { "allOf": [ { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "success": { @@ -797,21 +859,26 @@ } }, { - "required": ["data"], + "required": [ + "data" + ], "type": "object", "properties": { "data": { - "required": ["refId", "status"], + "required": [ + "refId", + "status" + ], "type": "object", "properties": { - "refId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, "additionalInfo": { "type": "array", + "description": "This tag captures the additional information provided by the Biller as part of response for a successful transaction.", "items": { - "required": ["name", "value"], + "required": [ + "name", + "value" + ], "type": "object", "properties": { "name": { @@ -824,13 +891,77 @@ } } }, - "x-go-name": "BillAdditionalInfo" + "x-go-name": "BillAdditionalInfo", + "x-omitempty": false + }, + "billerPlanResponse": { + "type": "object", + "properties": { + "planInfo": { + "type": "array", + "description": "Array of plan information as defined in BBPS schema", + "items": { + "required": [ + "details", + "type" + ], + "type": "object", + "properties": { + "details": { + "type": "array", + "description": "Array of plan details", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the plan parameter", + "example": "Plan_ID" + }, + "value": { + "type": "string", + "description": "Value of the plan parameter", + "example": "599" + } + } + } + }, + "type": { + "type": "string", + "description": "Type of the plan as defined in BBPS schema", + "enum": [ + "NEW", + "EXISTING", + "RECOMMENDED", + "CURATED", + "ACTIVATED" + ] + } + } + } + } + }, + "description": "Plan details returned by the biller during validation (used for prepaid recharge)", + "nullable": true, + "x-omitempty": true + }, + "billerRefId": { + "type": "string", + "example": "7f16a032e514" }, "billerResponseType": { "type": "string", "nullable": true, "example": "SINGLE", - "enum": ["SINGLE", "LIST", "SELECTIVE"], + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], "x-nullable": true, "x-omitempty": false }, @@ -839,7 +970,11 @@ "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", "nullable": true, "example": "SINGLE", - "enum": ["SINGLE", "MULTIPLE", "ALL"], + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], "x-nullable": true, "x-omitempty": false }, @@ -856,21 +991,6 @@ ], "type": "object", "properties": { - "customerName": { - "type": "string", - "example": "Manoj Chekuri" - }, - "dueDate": { - "type": "string", - "format": "date", - "example": "2021-09-24" - }, - "maxAmount": { - "type": "integer", - "description": "Maximum amount that can be paid for this bill in paise", - "nullable": true, - "x-omitempty": true - }, "amount": { "type": "integer", "nullable": true, @@ -882,6 +1002,11 @@ "nullable": true, "x-omitempty": true }, + "billDate": { + "type": "string", + "format": "date", + "example": "2021-01-02" + }, "billNumber": { "type": "string", "example": "1232332" @@ -890,10 +1015,14 @@ "type": "string", "example": "ONETIME|DAILY|WEEKLY|BIMONTHLY|MONTHLY|QUARTERLY|HALFYEARLY|YEARLY|ASPRESENTED" }, - "billDate": { + "customerName": { + "type": "string", + "example": "Manoj Chekuri" + }, + "dueDate": { "type": "string", "format": "date", - "example": "2021-01-02" + "example": "2021-09-24" }, "label": { "type": "string", @@ -901,6 +1030,12 @@ "example": "Advance EMI", "x-omitempty": true }, + "maxAmount": { + "type": "integer", + "description": "Maximum amount that can be paid for this bill in paise", + "nullable": true, + "x-omitempty": true + }, "minAmount": { "type": "integer", "description": "Minimum amount that can be paid for this bill in paise", @@ -911,19 +1046,11 @@ "type": "array", "nullable": true, "items": { - "required": ["name"], + "required": [ + "name" + ], "type": "object", "properties": { - "minAmount": { - "type": "integer", - "nullable": true, - "x-omitempty": true - }, - "name": { - "type": "string", - "description": "The display name of the option.", - "example": "2 Months EMI Amount" - }, "amount": { "type": "integer", "description": "The amount that can be paid for this option in paise.", @@ -941,6 +1068,17 @@ "description": "The maximum amount that can be paid for this option in paise.", "nullable": true, "x-omitempty": true + }, + "minAmount": { + "type": "integer", + "description": "The minimum amount that can be paid for this option in paise.", + "nullable": true, + "x-omitempty": true + }, + "name": { + "type": "string", + "description": "The display name of the option.", + "example": "2 Months EMI Amount" } }, "x-go-name": "PaymentOption" @@ -952,12 +1090,22 @@ }, "x-omitempty": true }, - "billerRefId": { + "exactness": { "type": "string", - "example": "7f16a032e514" + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] }, "failureReason": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -970,14 +1118,33 @@ }, "type": { "type": "string", - "enum": ["FUND_TRANSFER", "BBPS", "APP"] + "enum": [ + "FUND_TRANSFER", + "BBPS", + "APP" + ] } } }, + "refId": { + "type": "string", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, "status": { "type": "string", "example": "Success", - "enum": ["Processing", "Success", "Failure"] + "enum": [ + "Processing", + "Success", + "Failure", + "Credit_Adjustment" + ] + }, + "upmsRegistrationRefId": { + "type": "string", + "nullable": true, + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202", + "x-omitempty": true } } } @@ -994,11 +1161,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1029,11 +1203,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1062,13 +1243,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentAsyncRequest" @@ -1076,9 +1263,10 @@ }, "/api/v2/bbps/bills/payment/request": { "post": { - "tags": ["Pay"], + "tags": [ + "Pay" + ], "description": "Bill payment request API", - "operationId": "PaymentRequestV2", "parameters": [ { "name": "X-PARTNER-ID", @@ -1096,91 +1284,190 @@ "schema": { "allOf": [ { - "required": ["paymentDetails"], + "required": [ + "paymentDetails" + ], "type": "object", "properties": { - "refId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "bills": { - "uniqueItems": true, - "type": "array", - "nullable": true, - "example": "Selection on bills in case of list billers", - "items": { - "required": ["amount", "billNumber"], - "type": "object", - "properties": { - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" - }, - "billNumber": { - "type": "string", - "example": "B1234567" - } - }, - "x-omitempty": true - }, - "x-omitempty": true - }, - "paymentDetails": { + "agent": { "required": [ - "amount", - "mode", - "paymentRefId", - "timestamp" + "channel", + "id" ], "type": "object", "properties": { - "timestamp": { + "app": { "type": "string", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "SmartPay" }, - "accountInfo": { - "maxLength": 50, - "minLength": 1, - "type": "string" + "channel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] }, - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" + "geocode": { + "type": "string", + "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "19.0139,72.8254" }, - "currency": { - "type": "integer", - "nullable": true + "id": { + "type": "string", + "description": "The ID of the agent initiating the BBPS transaction.", + "example": "AX01AI06512391457204" }, - "selectedPaymentOptions": { - "type": "array", - "description": "List of selected payment options", - "nullable": true, - "items": { - "required": ["amount", "name"], - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the payment option as returned in bill fetch response.", - "example": "Early Payment Amount" - }, - "amount": { - "minimum": 1, - "type": "integer", - "description": "The amount to be paid for the selected payment option." - } - } + "ifsc": { + "type": "string", + "description": "Mandatory if channel is `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "ICIC0000152" + }, + "imei": { + "type": "string", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "123456789012345" + }, + "ip": { + "type": "string", + "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", + "format": "ipv4", + "example": "124.170.23.24" + }, + "mac": { + "type": "string", + "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", + "format": "mac", + "example": "48-4D-7E-CB-DB-6F" + }, + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "os": { + "type": "string", + "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", + "example": "iOS", + "enum": [ + "iOS", + "Android" + ] + }, + "postalCode": { + "pattern": "^[1-9][0-9]{5}$", + "type": "string", + "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "600001" + }, + "terminalId": { + "type": "string", + "description": "Mandatory if channel is `ATM`, `AGT`, `KIOSK` and `BSC` . Not required for others. This has to match the data submitted to NPCI for this agent ID\n", + "example": "6000011234" + } + } + }, + "biller": { + "required": [ + "id" + ], + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + } + }, + "x-go-gen-location": "models", + "x-go-name": "BillerDetails" + }, + "bills": { + "uniqueItems": true, + "type": "array", + "nullable": true, + "example": "Selection on bills in case of list billers", + "items": { + "required": [ + "amount", + "billNumber" + ], + "type": "object", + "properties": { + "amount": { + "minimum": 1, + "type": "integer", + "description": "Amount in Paise" }, - "x-nullable": true, - "x-omitempty": true + "billNumber": { + "type": "string", + "example": "B1234567" + } }, + "x-omitempty": true + }, + "x-omitempty": true + }, + "dummyBillerResponseAmount": { + "type": "integer", + "description": "On debug, this is the amount passed in biller response COMFORT NEGATIVE 23", + "nullable": true + }, + "dummyCustomerMobile": { + "type": "string", + "description": "On debug, this hijacks the customer mobiler number COMFORT NEGATIVE 30, 31", + "nullable": true + }, + "dummyOrigRefId": { + "type": "string", + "description": "On debug, hijacks orig ref id of payment request - COMFORT PAYMENT - 83", + "nullable": true + }, + "paymentDetails": { + "required": [ + "amount", + "mode", + "paymentRefId", + "timestamp" + ], + "type": "object", + "properties": { "COUcustConvFee": { "type": "integer", "nullable": true }, + "Id": { + "type": "string", + "description": "Pass here the ID of the selected payment plan in payment request. If a plan was selected in payment request, its Id will be a part of the paymentDetails block in payment response.", + "example": "1" + }, + "accountInfo": { + "maxLength": 50, + "minLength": 1, + "type": "string" + }, + "amount": { + "minimum": 1, + "type": "integer", + "description": "Amount in Paise" + }, + "currency": { + "type": "integer", + "nullable": true + }, "custConvFee": { "type": "integer", "nullable": true @@ -1209,107 +1496,68 @@ "minLength": 6, "type": "string", "example": "BD019181220291" + }, + "selectedPaymentOptions": { + "type": "array", + "description": "List of selected payment options", + "nullable": true, + "items": { + "required": [ + "amount", + "name" + ], + "type": "object", + "properties": { + "amount": { + "minimum": 1, + "type": "integer", + "description": "The amount to be paid for the selected payment option." + }, + "name": { + "type": "string", + "description": "The name of the payment option as returned in bill fetch response.", + "example": "Early Payment Amount" + } + } + }, + "x-nullable": true, + "x-omitempty": true + }, + "timestamp": { + "type": "string", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" } } }, - "agent": { - "required": ["channel", "id"], + "refId": { + "type": "string", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "remitter": { "type": "object", "properties": { - "os": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "iOS", - "enum": ["iOS", "Android"] - }, - "postalCode": { - "pattern": "^[1-9][0-9]{5}$", - "type": "string", - "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "600001" - }, - "terminalId": { - "type": "string", - "description": "Mandatory if channel is `ATM`, `AGT`, `KIOSK` and `BSC` . Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "6000011234" - }, - "app": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "SmartPay" - }, - "channel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "imei": { - "type": "string", - "description": "Mandatory if channel is `MOB`, `MOBB`. Not required for others.", - "example": "123456789012345" - }, - "mac": { - "type": "string", - "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", - "format": "mac", - "example": "48-4D-7E-CB-DB-6F" - }, - "mobile": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", - "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" - }, - "geocode": { - "type": "string", - "description": "Mandatory if channel is `AGT`, `BSC` and `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "19.0139,72.8254" + "aadhaar": { + "maxLength": 50, + "minLength": 1, + "type": "string" }, - "id": { - "type": "string", - "description": "The ID of the agent initiating the BBPS transaction.", - "example": "AX01AI06512391457204" + "email": { + "maxLength": 50, + "minLength": 1, + "type": "string" }, - "ifsc": { - "type": "string", - "description": "Mandatory if channel is `BNKBRNCH`. Not required for others. This has to match the data submitted to NPCI for this agent ID\n", - "example": "ICIC0000152" + "name": { + "maxLength": 50, + "minLength": 1, + "type": "string" }, - "ip": { - "type": "string", - "description": "Mandatory if channel is `INT`, `INTB`. Not required for others.", - "format": "ipv4", - "example": "124.170.23.24" + "pan": { + "maxLength": 50, + "minLength": 1, + "type": "string" } } - }, - "biller": { - "required": ["id"], - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - } - }, - "x-go-gen-location": "models", - "x-go-name": "BillerDetails" } }, "x-omitempty": true @@ -1320,53 +1568,38 @@ "customer": { "allOf": [ { - "required": ["mobile"], + "required": [ + "mobile" + ], "type": "object", "properties": { - "remitter": { - "type": "object", - "properties": { - "aadhaar": { - "maxLength": 50, - "minLength": 1, - "type": "string" - }, - "email": { - "maxLength": 50, - "minLength": 1, - "type": "string" - }, - "name": { - "maxLength": 50, - "minLength": 1, - "type": "string" - }, - "pan": { - "maxLength": 50, - "minLength": 1, - "type": "string" - } - } + "customerId": { + "type": "string", + "description": "Customer Identifier" }, "mobile": { - "maxLength": 20, + "maxLength": 22, "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", + "pattern": "^\\d{6,22}$", "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" + "description": "Mobile number with 6 to 22 digits are valid." } } }, { - "required": ["customerParams"], + "required": [ + "customerParams" + ], "type": "object", "properties": { "customerParams": { "type": "array", "description": "The bill params for fetching the bill", "items": { - "required": ["name", "value"], + "required": [ + "name", + "value" + ], "type": "object", "properties": { "name": { @@ -1445,15 +1678,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1461,21 +1703,80 @@ }, "message": { "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." } } }, "refId": { "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" } } }, "success": { "type": "boolean", + "description": "Boolean value indicating the status of the request", "example": true }, "traceId": { "type": "string", + "description": "The traceId generated for the request", "example": "HENSVVR4QOS7X1UGPY7JGUV444P10461713" } } @@ -1488,11 +1789,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1567,15 +1875,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1583,21 +1900,80 @@ }, "message": { "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." } } }, "refId": { "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" } } }, "success": { "type": "boolean", + "description": "Boolean value indicating the status of the request", "example": true }, "traceId": { "type": "string", + "description": "The traceId generated for the request", "example": "HENSVVR4QOS7X1UGPY7JGUV444P10461713" } } @@ -1610,11 +1986,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -1643,13 +2026,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentBillPaymentRequestV2" @@ -1657,7 +2046,9 @@ }, "/api/v2/bbps/bills/payment/response": { "post": { - "tags": ["Pay"], + "tags": [ + "Pay" + ], "description": "Bill payment response API", "parameters": [ { @@ -1674,12 +2065,14 @@ "content": { "application/json": { "schema": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "refId": { "type": "string", - "example": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689" + "description": "The generated Reference ID for the request." } }, "x-go-name": "RefIdBasedRequest", @@ -1690,76 +2083,6 @@ "required": true }, "responses": { - "400": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "validation-error" - }, - "message": { - "type": "string", - "example": "Input is invalid" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - } - } - } - }, - "500": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "validation-error" - }, - "message": { - "type": "string", - "example": "Input is invalid" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - } - } - } - }, "200": { "description": "OK", "headers": { @@ -1809,37 +2132,131 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId", "status"], + "required": [ + "refId", + "status" + ], "type": "object", "properties": { - "lastPaidDate": { + "additionalInfo": { + "type": "array", + "description": "This tag captures the additional information provided by the Biller as part of response for a successful transaction.", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Line item 1" + }, + "value": { + "type": "string", + "example": "Value 1" + } + } + }, + "x-go-name": "BillAdditionalInfo", + "x-omitempty": false + }, + "billerId": { "type": "string", - "format": "date-time", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "billerRefId": { + "type": "string", + "example": "ZA6291A177" + }, + "bills": { + "uniqueItems": true, + "type": "array", "nullable": true, - "example": "2020-12-12T13:12:00+05:30" + "example": "The bills paid in case of list billers", + "items": { + "required": [ + "amount", + "billNumber" + ], + "type": "object", + "properties": { + "amount": { + "minimum": 1, + "type": "integer", + "description": "Amount in Paise" + }, + "billNumber": { + "type": "string", + "example": "B1234567" + } + }, + "x-omitempty": true + }, + "x-omitempty": true }, - "paymentDetails": { + "failureReason": { "required": [ - "amount", - "mode", - "paymentRefId", - "timestamp" + "code", + "message" ], "type": "object", "properties": { - "timestamp": { + "code": { "type": "string", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" + "example": "ERR004" }, - "accountInfo": { - "maxLength": 50, - "minLength": 1, - "type": "string" + "message": { + "type": "string", + "example": "customer not found" + }, + "type": { + "type": "string", + "enum": [ + "FUND_TRANSFER", + "BBPS", + "APP" + ] + } + } + }, + "lastPaidDate": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2020-12-12T13:12:00+05:30" + }, + "paymentDetails": { + "required": [ + "amount", + "mode", + "paymentRefId", + "timestamp" + ], + "type": "object", + "properties": { + "COUcustConvFee": { + "type": "integer", + "nullable": true + }, + "Id": { + "type": "string", + "description": "Pass here the ID of the selected payment plan in payment request. If a plan was selected in payment request, its Id will be a part of the paymentDetails block in payment response.", + "example": "1" + }, + "accountInfo": { + "maxLength": 50, + "minLength": 1, + "type": "string" }, "amount": { "minimum": 1, @@ -1850,33 +2267,6 @@ "type": "integer", "nullable": true }, - "selectedPaymentOptions": { - "type": "array", - "description": "List of selected payment options", - "nullable": true, - "items": { - "required": ["amount", "name"], - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the payment option as returned in bill fetch response.", - "example": "Early Payment Amount" - }, - "amount": { - "minimum": 1, - "type": "integer", - "description": "The amount to be paid for the selected payment option." - } - } - }, - "x-nullable": true, - "x-omitempty": true - }, - "COUcustConvFee": { - "type": "integer", - "nullable": true - }, "custConvFee": { "type": "integer", "nullable": true @@ -1905,6 +2295,37 @@ "minLength": 6, "type": "string", "example": "BD019181220291" + }, + "selectedPaymentOptions": { + "type": "array", + "description": "List of selected payment options", + "nullable": true, + "items": { + "required": [ + "amount", + "name" + ], + "type": "object", + "properties": { + "amount": { + "minimum": 1, + "type": "integer", + "description": "The amount to be paid for the selected payment option." + }, + "name": { + "type": "string", + "description": "The name of the payment option as returned in bill fetch response.", + "example": "Early Payment Amount" + } + } + }, + "x-nullable": true, + "x-omitempty": true + }, + "timestamp": { + "type": "string", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" } } }, @@ -1915,79 +2336,16 @@ "status": { "type": "string", "example": "Success", - "enum": ["Processing", "Success", "Failure"] + "enum": [ + "Processing", + "Success", + "Failure", + "Credit_Adjustment" + ] }, "transactionId": { "type": "string", "example": "AX30910192192192192" - }, - "additionalInfo": { - "type": "array", - "items": { - "required": ["name", "value"], - "type": "object", - "properties": { - "name": { - "type": "string", - "example": "Line item 1" - }, - "value": { - "type": "string", - "example": "Value 1" - } - } - }, - "x-go-name": "BillAdditionalInfo" - }, - "billerId": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - }, - "failureReason": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "ERR004" - }, - "message": { - "type": "string", - "example": "customer not found" - }, - "type": { - "type": "string", - "enum": ["FUND_TRANSFER", "BBPS", "APP"] - } - } - }, - "billerRefId": { - "type": "string", - "example": "ZA6291A177" - }, - "bills": { - "uniqueItems": true, - "type": "array", - "nullable": true, - "example": "The bills paid in case of list billers", - "items": { - "required": ["amount", "billNumber"], - "type": "object", - "properties": { - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" - }, - "billNumber": { - "type": "string", - "example": "B1234567" - } - }, - "x-omitempty": true - }, - "x-omitempty": true } } }, @@ -2005,17 +2363,107 @@ } } } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } } }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentAsyncRequest" @@ -2023,14 +2471,15 @@ }, "/api/v2/bbps/bills/complaint/request": { "post": { - "tags": ["Dispute"], + "tags": [ + "Dispute" + ], "description": "Raise dispute request API", - "operationId": "DisputeRequestV2", "parameters": [ { "name": "X-PARTNER-ID", "in": "header", - "description": "Partner ID", + "description": "The Partner ID provided by Setu.", "required": true, "schema": { "type": "integer" @@ -2043,7 +2492,10 @@ "schema": { "allOf": [ { - "required": ["description", "disputeType"], + "required": [ + "description", + "disputeType" + ], "type": "object", "properties": { "description": { @@ -2053,7 +2505,6 @@ "disputeType": { "type": "string", "description": "The type of NPCI dispute", - "example": "account-not-updated", "enum": [ "account-not-updated", "double-payment", @@ -2061,13 +2512,20 @@ "others", "amount-deducted-biller-credited-no-transaction-id", "amount-deducted-biller-not-credited-no-transaction-id", - "amount-deducted-multiple-times" + "amount-deducted-multiple-times", + "service-not-received", + "service-disconnected", + "late-payment-surcharge", + "wrong-amount", + "payment-info-delay" ] } } }, { - "required": ["transactionId"], + "required": [ + "transactionId" + ], "type": "object", "properties": { "transactionId": { @@ -2133,15 +2591,24 @@ "content": { "application/json": { "schema": { - "required": ["data", "success", "traceId"], + "required": [ + "data", + "success", + "traceId" + ], "type": "object", "properties": { "data": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "duplicate": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2149,38 +2616,104 @@ }, "message": { "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." } } }, "refId": { "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - } - } - }, - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10461713" - } - } - } - } - } - }, - "400": { - "description": "Bad request", - "content": { + "description": "The generated Reference ID for the request." + }, + "upmsRegistration": { + "type": "object", + "properties": { + "duplicate": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + } + } + }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "invalid-mandate" + }, + "message": { + "type": "string", + "example": "The mandate configuration is invalid" + } + }, + "description": "Present only when acknowledgement status for the registration is FAILED" + }, + "refId": { + "type": "string", + "description": "The reference ID for the UPMS registration", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + }, + "status": { + "type": "string", + "description": "Status of the registration request processing by our system", + "example": "PENDING", + "enum": [ + "PENDING", + "FAILED" + ] + } + }, + "description": "Present only when upmsRegistration was requested" + } + } + }, + "success": { + "type": "boolean", + "description": "Boolean value indicating the status of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request", + "example": "HENSVVR4QOS7X1UGPY7JGUV444P10461713" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2207,15 +2740,22 @@ } }, "500": { - "description": "Bad request", + "description": "Internal server error", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2244,13 +2784,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentDisputeRequest" @@ -2258,13 +2804,15 @@ }, "/api/v2/bbps/bills/complaint/response": { "post": { - "tags": ["Dispute"], + "tags": [ + "Dispute" + ], "description": "Raise dispute response API", "parameters": [ { "name": "X-PARTNER-ID", "in": "header", - "description": "Partner ID", + "description": "The Partner ID provided by Setu.", "required": true, "schema": { "type": "integer" @@ -2275,12 +2823,14 @@ "content": { "application/json": { "schema": { - "required": ["refId"], + "required": [ + "refId" + ], "type": "object", "properties": { "refId": { "type": "string", - "example": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689" + "description": "The generated Reference ID for the request." } }, "x-go-name": "RefIdBasedRequest", @@ -2340,7 +2890,10 @@ "content": { "application/json": { "schema": { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { "data": { @@ -2357,18 +2910,35 @@ "type": "string", "example": "ICICI BOU" }, + "disposition": { + "type": "string", + "enum": [ + "D11", + "D12", + "D13", + "D21", + "D22", + "D23", + "D31", + "D32" + ] + }, "disputeId": { "type": "string", "example": "OP0121046567755" }, "refId": { "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" + "description": "The generated Reference ID for the request." }, "remarks": { "type": "string", "example": "Resolved in favour of Biller" }, + "responseReason": { + "type": "string", + "example": "Ticket already IN-PROGRESS" + }, "status": { "type": "string", "description": "BBPS Complaint status", @@ -2382,7 +2952,23 @@ "ASSIGNED_TO_OU", "ESCALATED", "RESOLVED", - "UNRESOLVED" + "UNRESOLVED", + "REJECTED", + "DEFAULT_RESOLVED", + "REFUNDED", + "PENDING_REFUND" + ] + }, + "ticketTAT": { + "type": "string", + "format": "date", + "nullable": true + }, + "ticketType": { + "type": "string", + "enum": [ + "DISPUTE", + "COMPLAINT" ] } }, @@ -2408,11 +2994,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2443,11 +3036,18 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -2476,54 +3076,62 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ], "x-codegen-request-body-name": "CouAgentAsyncRequest" } }, - "/api/v2/bbps/disputes": { + "/api/v2/bbps/billers": { "get": { - "tags": ["List"], - "description": "Returns the list of disputes.", - "operationId": "getDisputesV2", + "tags": [ + "List" + ], + "description": "Returns the list of billers.", "parameters": [ { "name": "X-PARTNER-ID", "in": "header", - "description": "Partner ID", + "description": "The Partner ID provided by Setu.", "required": true, "schema": { "type": "integer" } }, { - "name": "status", + "name": "categoryName", + "in": "query", + "description": "Biller category. The query parameter follows a multi instance format. Usage: categoryName=category1&categoryName=category2", + "style": "form", + "explode": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "ids", "in": "query", "style": "form", "explode": false, "schema": { - "uniqueItems": true, "type": "array", "items": { - "type": "string", - "enum": [ - "INITIALIZED", - "ASSIGNED", - "RE_ASSIGNED", - "ASSIGNED_TO_BOU", - "ASSIGNED_TO_COU", - "ASSIGNED_TO_OU", - "ESCALATED", - "RESOLVED", - "UNRESOLVED" - ] + "type": "string" } } }, @@ -2532,120 +3140,132 @@ "in": "query", "description": "Limit", "schema": { - "maximum": 1000.0, + "maximum": 250.0, "minimum": 1.0, "type": "integer" } }, { - "name": "categories", + "name": "after", "in": "query", - "description": "Biller Category", - "style": "form", - "explode": false, "schema": { - "uniqueItems": true, - "type": "array", - "items": { - "type": "string" - } + "type": "string" } }, { - "name": "months", + "name": "search", "in": "query", - "description": "Month ranges. A full-date notation as defined by 'RFC 3339, section 5.6' has to be provided but only month and year will be considered.", - "style": "form", - "explode": false, "schema": { - "uniqueItems": true, - "type": "array", - "items": { - "type": "string", - "format": "date", - "example": "2022-07-19" - } + "type": "string" } }, { - "name": "after", + "name": "pincode", "in": "query", "schema": { "type": "string" } }, { - "name": "mobile", + "name": "city", "in": "query", - "description": "Mobile number with 6, 10 and 20 digits are valid.", "schema": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", "type": "string" } }, { - "name": "transactionIds", + "name": "state", "in": "query", - "description": "Transaction IDs", - "style": "form", - "explode": false, "schema": { - "uniqueItems": true, - "type": "array", - "items": { - "type": "string" - } + "type": "string" } }, { - "name": "paymentRefIds", + "name": "country", "in": "query", - "description": "Agent's payment reference Ids", - "style": "form", - "explode": false, "schema": { - "uniqueItems": true, - "type": "array", - "items": { - "type": "string" - } + "type": "string" } }, { - "name": "billerIds", + "name": "coverage", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "tags", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "paymentChannel", "in": "query", - "description": "The biller ID on BBPS", "style": "form", "explode": false, "schema": { - "uniqueItems": true, "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] } } }, { - "name": "expand", + "name": "paymentMode", "in": "query", "style": "form", "explode": false, "schema": { - "uniqueItems": true, "type": "array", "items": { "type": "string", - "example": "BILLER", - "enum": ["BILLER", "TRANSACTION"] + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] } } + }, + { + "name": "updatedSince", + "in": "query", + "description": "Used to fetch billers updated since the given date-time in IST", + "schema": { + "type": "string", + "format": "date-time" + } } ], "responses": { "200": { - "description": "List of disputes", + "description": "List of billers", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -2693,1709 +3313,1081 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "required": ["success", "traceId"], - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - }, - { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "data": { + "required": [ + "billers" + ], "type": "object", "properties": { - "data": { - "type": "object", - "properties": { - "disputes": { - "type": "array", - "items": { - "allOf": [ - { - "type": "object", - "properties": { - "biller": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "ADIT00000NAT0T" - }, - "country": { - "type": "string", - "example": "IND" - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "LIST", - "SELECTIVE" - ], - "x-nullable": true, - "x-omitempty": false - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "MULTIPLE", - "ALL" - ], - "x-nullable": true, - "x-omitempty": false - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "example": true - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "state": { - "type": "string", - "example": "TEL" - }, - "logo": { - "type": "string", - "example": "logo" - }, - "name": { - "type": "string", - "example": "Aditya Birla Sun Life Insurance" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "exactness": { - "type": "string", - "description": "Biller exactness", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" - ] - }, - "fetchApiType": { - "type": "string", - "example": "BILL_FETCH", - "enum": [ - "BILL_FETCH", - "BILL_VALIDATE", - "BILL_DIRECT" - ] - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "categoryName": { - "type": "string", - "example": "loan-repayment" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Loan Account Number" - } - } - } - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "pincode": { - "type": "string", - "example": "pincode" - } - }, - "x-go-name": "CouBillerDetails" - }, - "billerId": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - }, - "complaintId": { - "type": "string", - "example": "Loan Repayment" - }, - "lastModifiedAt": { - "type": "string", - "description": "Dispute's last modified timestamp", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "refId": { - "type": "string", - "example": "Loan Repayment" - }, - "responseCode": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "assigned": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "complaintStatus": { - "type": "string", - "description": "BBPS Complaint status", - "example": "ASSIGNED", - "enum": [ - "INITIALIZED", - "ASSIGNED", - "RE_ASSIGNED", - "ASSIGNED_TO_BOU", - "ASSIGNED_TO_COU", - "ASSIGNED_TO_OU", - "ESCALATED", - "RESOLVED", - "UNRESOLVED" - ] - }, - "createdAt": { - "type": "string", - "description": "Dispute's creation timestamp", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "remarks": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "responseReason": { - "type": "string", - "example": "ADIT00000NATRA" - }, - "transactionId": { - "type": "string", - "description": "Setu BillPay Transaction ID.", - "example": "AX30910192192192192" - } - } - }, - { - "type": "object", - "properties": { - "mobile": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", - "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" - }, - "paymentRefId": { - "type": "string", - "description": "Agent's payment reference ID" - }, - "transaction": { - "allOf": [ - { - "type": "object", - "properties": { - "amount": { - "type": "integer" - }, - "bills": { - "type": "array", - "items": { - "required": [ - "amount", - "billNumber" - ], - "type": "object", - "properties": { - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" - }, - "billNumber": { - "type": "string", - "example": "B1234567" - } - }, - "x-omitempty": true - } - }, - "refId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "status": { - "type": "string", - "example": "Success", - "enum": [ - "Processing", - "Success", - "Error" - ] - }, - "biller": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "ADIT00000NAT0T" - }, - "country": { - "type": "string", - "example": "IND" - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "LIST", - "SELECTIVE" - ], - "x-nullable": true, - "x-omitempty": false - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "MULTIPLE", - "ALL" - ], - "x-nullable": true, - "x-omitempty": false - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "example": true - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "state": { - "type": "string", - "example": "TEL" - }, - "logo": { - "type": "string", - "example": "logo" - }, - "name": { - "type": "string", - "example": "Aditya Birla Sun Life Insurance" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "exactness": { - "type": "string", - "description": "Biller exactness", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" - ] - }, - "fetchApiType": { - "type": "string", - "example": "BILL_FETCH", - "enum": [ - "BILL_FETCH", - "BILL_VALIDATE", - "BILL_DIRECT" - ] - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "categoryName": { - "type": "string", - "example": "loan-repayment" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Loan Account Number" - } - } - } - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "pincode": { - "type": "string", - "example": "pincode" - } - }, - "x-go-name": "CouBillerDetails" - }, - "billerId": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - }, - "customerParams": { - "type": "array", - "description": "The bill params for fetching the bill", - "items": { - "required": ["name", "value"], - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The display name of the parameter. This has to match what is sent in fields.", - "example": "Loan Number" - }, - "value": { - "type": "string", - "description": "The value of the customer parameter", - "example": "1895159" - } - } - } - }, - "timestamp": { - "type": "string", - "description": "Timestamp provided by partner while making payment request.", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "transactionId": { - "type": "string", - "description": "Setu BillPay Transaction ID.", - "example": "AX30910192192192192" - } - } - }, - { - "type": "object", - "properties": { - "mobile": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", - "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" - }, - "paymentRefId": { - "type": "string", - "description": "Agent's payment reference ID" - } - } - } - ] - } - } - } - ] - } - }, - "nextPage": { - "type": "string", - "example": "/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" - }, - "total": { - "type": "integer" - } - } - } - } - } - ] - } - } - } - }, - "400": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "validation-error" - }, - "message": { - "type": "string", - "example": "Input is invalid" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - } - } - } - }, - "500": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "validation-error" - }, - "message": { - "type": "string", - "example": "Input is invalid" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - } - } - } - } - }, - "security": [ - { - "Production": ["bbps:partner"] - }, - { - "Sandbox": ["bbps:partner"] - }, - { - "QA": ["bbps:partner"] - } - ] - } - }, - "/api/v2/bbps/transactions": { - "get": { - "tags": ["List"], - "description": "Returns the list of transactions.", - "operationId": "getTxnsV2", - "parameters": [ - { - "name": "X-PARTNER-ID", - "in": "header", - "description": "Partner ID", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "name": "limit", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "name": "after", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "startDate", - "in": "query", - "description": "start date of the timestamp provided by the partner while making the request.", - "schema": { - "type": "string", - "format": "date" - } - }, - { - "name": "endDate", - "in": "query", - "description": "end date of the timestamp provided by the partner while making the request.", - "schema": { - "type": "string", - "format": "date" - } - }, - { - "name": "billerId", - "in": "query", - "description": "Transaction BillerId", - "schema": { - "type": "string" - } - }, - { - "name": "ids", - "in": "query", - "description": "Transaction Reference Ids", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - } - } - }, - { - "name": "categories", - "in": "query", - "description": "Biller Category", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - } - } - }, - { - "name": "billerFetchApiType", - "in": "query", - "description": "Biller Fetch Api Type", - "schema": { - "type": "string", - "enum": ["BILL_FETCH", "BILL_VALIDATE", "BILL_DIRECT"] - } - }, - { - "name": "months", - "in": "query", - "description": "Month ranges. A full-date notation as defined by 'RFC 3339, section 5.6' has to be provided but only month and year will be considered.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "date", - "example": "2022-07-19" - } - } - }, - { - "name": "status", - "in": "query", - "description": "Transaction Status", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "example": "Success", - "enum": ["Processing", "Success", "Error"] - } - } - }, - { - "name": "mobile", - "in": "query", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "schema": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", - "type": "string" - } - }, - { - "name": "expand", - "in": "query", - "style": "form", - "explode": false, - "schema": { - "uniqueItems": true, - "type": "array", - "items": { - "type": "string", - "example": "BILLER", - "enum": ["BILLER"] - } - } - } - ], - "responses": { - "500": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "required": ["error", "success", "traceId"], - "type": "object", - "properties": { - "error": { - "required": ["code", "message"], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "validation-error" - }, - "message": { - "type": "string", - "example": "Input is invalid" - } - } - }, - "success": { - "type": "boolean", - "example": false - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - } - } - } - }, - "200": { - "description": "List of Txns", - "headers": { - "X-Frame-Options": { - "description": "X Frame options", - "schema": { - "type": "string" - } - }, - "Strict-Transport-Security": { - "description": "Strict transport security", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "Cache control", - "schema": { - "type": "string" - } - }, - "X-Content-Type-Options": { - "description": "X Content type options", - "schema": { - "type": "string" - } - }, - "Content-Security-Policy": { - "description": "Content security policy", - "schema": { - "type": "string" - } - }, - "Pragma": { - "description": "Pragma", - "schema": { - "type": "string" - } - }, - "X-XSS-Protection": { - "description": "X Xss Protection", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "required": ["success", "traceId"], - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - } - }, - { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "nextPage": { - "type": "string", - "example": "/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" - }, - "transactions": { - "type": "array", - "items": { - "allOf": [ - { - "type": "object", - "properties": { - "amount": { - "type": "integer" - }, - "bills": { - "type": "array", - "items": { - "required": ["amount", "billNumber"], - "type": "object", - "properties": { - "amount": { - "minimum": 1, - "type": "integer", - "description": "Amount in Paise" - }, - "billNumber": { - "type": "string", - "example": "B1234567" - } - }, - "x-omitempty": true - } - }, - "refId": { - "type": "string", - "example": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" - }, - "status": { - "type": "string", - "example": "Success", - "enum": [ - "Processing", - "Success", - "Error" - ] - }, - "biller": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "ADIT00000NAT0T" - }, - "country": { - "type": "string", - "example": "IND" - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "LIST", - "SELECTIVE" - ], - "x-nullable": true, - "x-omitempty": false - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": [ - "SINGLE", - "MULTIPLE", - "ALL" - ], - "x-nullable": true, - "x-omitempty": false - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": [ - "ALPHANUMERIC", - "NUMERIC" - ] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" - } - } - } - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "example": true - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "state": { - "type": "string", - "example": "TEL" - }, - "logo": { - "type": "string", - "example": "logo" - }, - "name": { - "type": "string", - "example": "Aditya Birla Sun Life Insurance" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "exactness": { - "type": "string", - "description": "Biller exactness", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" - ] - }, - "fetchApiType": { - "type": "string", - "example": "BILL_FETCH", - "enum": [ - "BILL_FETCH", - "BILL_VALIDATE", - "BILL_DIRECT" - ] - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "categoryName": { - "type": "string", - "example": "loan-repayment" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Loan Account Number" - } - } - } - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "pincode": { - "type": "string", - "example": "pincode" - } + "billers": { + "type": "array", + "items": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" }, - "x-go-name": "CouBillerDetails" - }, - "billerId": { - "type": "string", - "description": "The biller ID on BBPS", - "example": "MAHI00000NATIC" - }, - "customerParams": { - "type": "array", - "description": "The bill params for fetching the bill", - "items": { - "required": ["name", "value"], - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The display name of the parameter. This has to match what is sent in fields.", - "example": "Loan Number" - }, - "value": { - "type": "string", - "description": "The value of the customer parameter", - "example": "1895159" - } - } + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" } - }, - "timestamp": { - "type": "string", - "description": "Timestamp provided by partner while making payment request.", - "format": "date-time", - "example": "2020-12-12T13:12:00+05:30" - }, - "transactionId": { - "type": "string", - "description": "Setu BillPay Transaction ID.", - "example": "AX30910192192192192" } } - }, + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "pincode": { + "type": "string", + "example": "pincode" + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upms_registration_overriding_rule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true + } + }, + "x-go-name": "CouBillerDetails" + } + }, + "nextPage": { + "type": "string", + "example": "/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" + }, + "total": { + "type": "integer" + } + } + }, + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/bbps/billers/plans": { + "get": { + "tags": [ + "List" + ], + "description": "Returns the list of plans for a given set of billers", + "operationId": "getBillerPlans", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "billerIds", + "in": "query", + "description": "Biller IDs", + "required": true, + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of plans to return per page", + "schema": { + "maximum": 1000.0, + "minimum": 1.0, + "type": "integer" + } + }, + { + "name": "after", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "updatedSince", + "in": "query", + "description": "Used to fetch plans updated since the given date-time in IST", + "schema": { + "type": "string", + "format": "date-time" + } + } + ], + "responses": { + "200": { + "description": "List of plans for the biller", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "data": { + "required": [ + "plans" + ], + "type": "object", + "properties": { + "nextPage": { + "type": "string", + "example": "/api/bbps/billers/plans?biller_ids=BILLER_01&after=ABCC00000PTNNS" + }, + "plans": { + "type": "array", + "items": { + "required": [ + "Id", + "amountInRupees", + "categoryType", + "description", + "status" + ], + "type": "object", + "properties": { + "Id": { + "type": "string", + "description": "Plan ID", + "example": "1.0", + "x-order": 1.0 + }, + "additionalInfo": { + "minItems": 1, + "type": "array", + "description": "Plan Additional information details provided by the Biller.", + "example": [ { - "type": "object", - "properties": { - "mobile": { - "maxLength": 20, - "minLength": 6, - "pattern": "^\\d{6}(\\d{4}(\\d{10})?)?$", - "type": "string", - "description": "Mobile number with 6, 10 and 20 digits are valid.", - "example": "9481773053" - }, - "paymentRefId": { - "type": "string", - "description": "Agent's payment reference ID" - } - } + "paramName": "Mobile Number", + "paramValue": "Text" } + ], + "items": { + "type": "object", + "properties": { + "paramName": { + "type": "string", + "example": "Plan Additional information parameter name." + }, + "paramValue": { + "type": "string", + "example": "Plan Additional information parameter value." + } + }, + "example": { + "paramName": "Mobile Number", + "paramValue": "Text" + }, + "x-go-name": "PlanAdditionalInfoItem" + }, + "x-omitempty": true + }, + "amountInRupees": { + "type": "string", + "example": "22.0", + "x-order": 2.0 + }, + "billerId": { + "type": "string", + "description": "Biller ID to which the plan belongs to", + "example": "1.0", + "x-order": 0.0 + }, + "categorySubType": { + "type": "object", + "properties": {}, + "description": "Plan sub category as defined by the Biller.", + "example": { + "subType": "1 Month" + }, + "x-omitempty": true, + "x-order": 4.0 + }, + "categoryType": { + "type": "string", + "description": "Plan category as defined by the Biller.", + "example": "VIP", + "x-order": 3.0 + }, + "description": { + "type": "string", + "description": "Plan description as defined by the Biller.", + "example": "Unlimited Live Sports" + }, + "effectiveFrom": { + "type": "string", + "description": "Effective from date of corresponding Plan.", + "format": "date", + "nullable": true, + "example": "2017-07-21", + "x-omitempty": false + }, + "effectiveTo": { + "type": "string", + "description": "Effective to date of corresponding Plan.", + "format": "date", + "nullable": true, + "example": "2020-08-21", + "x-omitempty": false + }, + "status": { + "type": "string", + "description": "Effective to date of corresponding Plan.", + "example": "ACTIVE", + "enum": [ + "ACTIVE", + "DEACTIVATED" ] } } } + }, + "total": { + "type": "integer" + } + } + }, + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/bbps/categories": { + "get": { + "tags": [ + "List" + ], + "description": "Returns the list of categories.", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "List of categories", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "data": { + "required": [ + "categories" + ], + "type": "object", + "properties": { + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "billerCount": { + "type": "integer" + }, + "name": { + "type": "string", + "example": "Loan Repayment" + } + } + } + } + } + }, + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" } } + }, + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } - ] + } } } } @@ -4405,11 +4397,60 @@ "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -4438,48 +4479,59 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ] } }, - "/api/v2/bbps/billers": { + "/api/v2/bbps/disputes": { "get": { - "tags": ["List"], - "description": "Returns the list of billers.", - "operationId": "getBillersV2", + "tags": [ + "List" + ], + "description": "Returns the list of disputes.", "parameters": [ { "name": "X-PARTNER-ID", "in": "header", - "description": "Partner ID", + "description": "The Partner ID provided by Setu.", "required": true, "schema": { "type": "integer" } }, { - "name": "categoryName", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "ids", + "name": "status", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "items": { - "type": "string" + "type": "string", + "enum": [ + "INITIALIZED", + "ASSIGNED", + "RE_ASSIGNED", + "ASSIGNED_TO_BOU", + "ASSIGNED_TO_COU", + "ASSIGNED_TO_OU", + "ESCALATED", + "RESOLVED", + "UNRESOLVED" + ] } } }, @@ -4494,126 +4546,120 @@ } }, { - "name": "after", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "name": "search", + "name": "categories", "in": "query", + "description": "Biller Category", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "type": "string" + } } }, { - "name": "pincode", + "name": "months", "in": "query", + "description": "Month ranges. A full-date notation as defined by 'RFC 3339, section 5.6' has to be provided but only month and year will be considered.", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "type": "string", + "format": "date" + } } }, { - "name": "city", + "name": "after", "in": "query", "schema": { "type": "string" } }, { - "name": "state", + "name": "mobile", "in": "query", + "description": "Mobile number with 6 to 22 digits are valid.", "schema": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", "type": "string" } }, { - "name": "country", + "name": "customerId", "in": "query", + "description": "Customer Identifier", "schema": { "type": "string" } }, { - "name": "coverage", + "name": "transactionIds", "in": "query", + "description": "Transaction IDs", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "type": "string" + } } }, { - "name": "tags", + "name": "paymentRefIds", "in": "query", + "description": "Partner provided transaction Ids", + "style": "form", + "explode": false, "schema": { - "type": "string" + "type": "array", + "items": { + "maxLength": 35, + "minLength": 6, + "type": "string" + } } }, { - "name": "paymentChannel", + "name": "billerIds", "in": "query", + "description": "The biller ID on BBPS", "style": "form", "explode": false, "schema": { "type": "array", "items": { - "type": "string", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] + "type": "string" } } }, { - "name": "paymentMode", + "name": "expand", "in": "query", "style": "form", "explode": false, "schema": { + "uniqueItems": true, "type": "array", "items": { "type": "string", "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" + "BILLER", + "TRANSACTION" ] } } - }, - { - "name": "updatedSince", - "in": "query", - "description": "Used to fetch billers updated since the given date-time in IST", - "schema": { - "type": "string", - "format": "date-time" - } } ], "responses": { "200": { - "description": "List of billers", + "description": "List of disputes", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -4661,356 +4707,3276 @@ "content": { "application/json": { "schema": { - "required": ["success", "traceId"], - "type": "object", - "properties": { - "data": { - "required": ["billers"], + "allOf": [ + { + "required": [ + "success", + "traceId" + ], "type": "object", "properties": { - "total": { - "type": "integer" + "success": { + "type": "boolean", + "example": true }, - "billers": { - "type": "array", - "items": { - "required": [ - "categoryName", - "customerParams", - "exactness", - "fetchApiType", - "id", - "name", - "payWithoutFetchAllowed", - "paymentChannels", - "paymentModes", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "ADIT00000NAT0T" - }, - "country": { - "type": "string", - "example": "IND" - }, - "paymentChannels": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentChannel", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentChannel": { - "type": "string", - "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", - "example": "INT", - "enum": [ - "INT", - "INTB", - "MOB", - "BNKBRNCH", - "BSC", - "AGT", - "KIOSK", - "ATM", - "MOBB", - "POS", - "MPOS" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } - } - } - }, - "responseType": { - "type": "string", - "nullable": true, - "example": "SINGLE", - "enum": ["SINGLE", "LIST", "SELECTIVE"], - "x-nullable": true, - "x-omitempty": false - }, - "selectionType": { - "type": "string", - "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", - "nullable": true, - "example": "SINGLE", - "enum": ["SINGLE", "MULTIPLE", "ALL"], - "x-nullable": true, - "x-omitempty": false - }, - "billerAdditionalInfo": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": ["ALPHANUMERIC", "NUMERIC"] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + }, + { + "type": "object", + "properties": { + "data": { + "required": [ + "disputes" + ], + "type": "object", + "properties": { + "disputes": { + "type": "array", + "items": { + "allOf": [ + { + "type": "object", + "properties": { + "assigned": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "biller": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "pincode": { + "type": "string", + "example": "pincode" + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upms_registration_overriding_rule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true + } + }, + "x-go-name": "CouBillerDetails" + }, + "billerId": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "complaintId": { + "type": "string", + "example": "Loan Repayment" + }, + "complaintStatus": { + "type": "string", + "description": "BBPS Complaint status", + "example": "ASSIGNED", + "enum": [ + "INITIALIZED", + "ASSIGNED", + "RE_ASSIGNED", + "ASSIGNED_TO_BOU", + "ASSIGNED_TO_COU", + "ASSIGNED_TO_OU", + "ESCALATED", + "RESOLVED", + "UNRESOLVED", + "REJECTED", + "DEFAULT_RESOLVED", + "REFUNDED", + "PENDING_REFUND" + ] + }, + "createdAt": { + "type": "string", + "description": "Dispute's creation timestamp", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "disposition": { + "type": "string", + "enum": [ + "D11", + "D12", + "D13", + "D21", + "D22", + "D23", + "D31", + "D32" + ] + }, + "lastModifiedAt": { + "type": "string", + "description": "Dispute's last modified timestamp", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "remarks": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "responseCode": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "responseReason": { + "type": "string", + "example": "ADIT00000NATRA" + }, + "ticketTAT": { + "type": "string", + "format": "date", + "nullable": true + }, + "ticketType": { + "type": "string", + "enum": [ + "DISPUTE", + "COMPLAINT" + ] + }, + "transactionId": { + "type": "string", + "description": "Setu BillPay Transaction ID.", + "example": "AS01910192192192192" + } } - } - } - }, - "billerAdditionalInfoPayment": { - "type": "array", - "items": { - "required": [ - "dataType", - "optional", - "paramName" - ], - "type": "object", - "properties": { - "dataType": { - "type": "string", - "example": "ALPHANUMERIC", - "enum": ["ALPHANUMERIC", "NUMERIC"] - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Package Duration" + }, + { + "type": "object", + "properties": { + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "paymentRefID": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "description": "Unique identifier provided by Partner for the payment request.", + "example": "BD019181220291" + }, + "transaction": { + "allOf": [ + { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "biller": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "pincode": { + "type": "string", + "example": "pincode" + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upms_registration_overriding_rule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true + } + }, + "x-go-name": "CouBillerDetails" + }, + "billerId": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "custConvFee": { + "type": "integer", + "description": "Customer convenience fee in paise" + }, + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "customerParams": { + "type": "array", + "description": "The bill params for fetching the bill", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. This has to match what is sent in fields.", + "example": "Loan Number" + }, + "value": { + "type": "string", + "description": "The value of the customer parameter", + "example": "1895159" + } + } + } + }, + "etherealTransaction": { + "required": [ + "amount", + "billRefId", + "refId", + "status", + "transactionId" + ], + "type": "object", + "properties": { + "amount": { + "type": "string", + "example": "100.00" + }, + "billRefId": { + "type": "string", + "description": "The BBPS Ref ID", + "example": "C3SFG0O6N88R6UI7EQ" + }, + "refId": { + "type": "string", + "example": "COUWL910192192192192" + }, + "status": { + "type": "string", + "enum": [ + "INIT", + "SUCCESS", + "FAILURE", + "PENDING", + "UNKNOWN" + ] + }, + "transactionId": { + "type": "string", + "example": "Q910192192192192" + } + } + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "refundStatus": { + "type": "string", + "enum": [ + "Required", + "Requested", + "Processed" + ] + }, + "status": { + "type": "string", + "example": "Success", + "enum": [ + "Processing", + "Success", + "Error", + "Credit_Adjustment" + ] + }, + "timestamp": { + "type": "string", + "description": "Timestamp provided by partner while making payment request.", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "transactionId": { + "type": "string", + "description": "Setu BillPay Transaction ID.", + "example": "AS01910192192192192" + } + } + }, + { + "type": "object", + "properties": { + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "paymentRefId": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "description": "Unique identifier provided by Partner for the payment request.", + "example": "BD019181220291" + } + } + } + ] + } } } - } - }, - "city": { - "type": "string", - "example": "Hyderabad" - }, - "enforcesSameDayFetchPay": { - "type": "boolean", - "example": true, - "x-omitempty": false - }, - "payWithoutFetchAllowed": { - "type": "boolean", - "example": true - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - }, - "tags": { - "type": "string", - "example": "tags" - }, - "modifiedAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "state": { - "type": "string", - "example": "TEL" - }, - "logo": { - "type": "string", - "example": "logo" - }, - "name": { - "type": "string", - "example": "Aditya Birla Sun Life Insurance" - }, - "coverage": { - "type": "string", - "example": "IND-TEL-Hyderabad" - }, - "customerParamsGroups": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "string", - "example": "Param 1" - } - } - }, - "exactness": { - "type": "string", - "description": "Biller exactness", - "example": "Exact", - "enum": [ - "Exact", - "Exact and above", - "Exact and below", - "Any", - "RANGE" - ] - }, - "fetchApiType": { - "type": "string", - "example": "BILL_FETCH", - "enum": [ - "BILL_FETCH", - "BILL_VALIDATE", - "BILL_DIRECT" ] - }, - "subCategoryName": { - "type": "string", - "example": "DAIRY" - }, - "bbpsUpdateTimestamp": { - "type": "string", - "description": "Last updated date-time of the Biller accurate to the nearest day.", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": true - }, - "categoryName": { - "type": "string", - "example": "loan-repayment" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "nullable": true, - "example": "2021-11-12T13:37:04.572+05:30", - "x-omitempty": false - }, - "customerParams": { - "type": "array", - "items": { - "required": [ - "dataType", - "maxLength", - "minLength", - "optional", - "paramName", - "regex", - "values", - "visibility" - ], - "type": "object", - "properties": { - "regex": { - "type": "string", - "example": "^[a-zA-Z0-9]{7,15}" - }, - "values": { - "type": "string" - }, - "visibility": { - "type": "boolean", - "example": true - }, - "dataType": { - "type": "string", - "example": "ALPHANUMERIC" - }, - "maxLength": { - "type": "integer" - }, - "minLength": { - "type": "integer" - }, - "optional": { - "type": "boolean", - "example": false - }, - "paramName": { - "type": "string", - "example": "Loan Account Number" - } + } + }, + "nextPage": { + "type": "string", + "example": "/api/bbps/disputes?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" + } + } + } + } + } + ] + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/bbps/transactions": { + "get": { + "tags": [ + "List" + ], + "description": "Returns the list of transactions.", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer" + } + }, + { + "name": "after", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "startDate", + "in": "query", + "description": "start date of the timestamp provided by the partner while making the request.", + "required": true, + "schema": { + "type": "string", + "format": "date" + } + }, + { + "name": "endDate", + "in": "query", + "description": "end date of the timestamp provided by the partner while making the request.", + "required": true, + "schema": { + "type": "string", + "format": "date" + } + }, + { + "name": "billerId", + "in": "query", + "description": "Transaction BillerId", + "schema": { + "type": "string" + } + }, + { + "name": "ids", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "categories", + "in": "query", + "description": "Biller Category", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "billerFetchApiType", + "in": "query", + "description": "Biller Fetch Api Type", + "schema": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + } + }, + { + "name": "months", + "in": "query", + "description": "Month ranges. A full-date notation as defined by 'RFC 3339, section 5.6' has to be provided but only month and year will be considered.", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "date" + } + } + }, + { + "name": "status", + "in": "query", + "description": "Transaction Status", + "style": "form", + "explode": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "Processing", + "Success", + "Error" + ] + } + } + }, + { + "name": "mobile", + "in": "query", + "description": "Mobile number with 6 to 22 digits are valid.", + "schema": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string" + } + }, + { + "name": "customerId", + "in": "query", + "description": "Customer Identifier", + "schema": { + "type": "string" + } + }, + { + "name": "expand", + "in": "query", + "style": "form", + "explode": false, + "schema": { + "uniqueItems": true, + "type": "array", + "items": { + "type": "string", + "enum": [ + "BILLER", + "ETHEREAL_TRANSACTION" + ] + } + } + }, + { + "name": "refundStatus", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "Required", + "Requested", + "Processed" + ] + } + } + ], + "responses": { + "200": { + "description": "List of Txns", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + }, + { + "required": [ + "data" + ], + "type": "object", + "properties": { + "data": { + "allOf": [ + { + "type": "object", + "properties": { + "nextPage": { + "type": "string", + "example": "/api/bbps/transactions?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" + } + } + }, + { + "type": "object", + "properties": { + "transactions": { + "type": "array", + "items": { + "allOf": [ + { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "biller": { + "required": [ + "categoryName", + "customerParams", + "exactness", + "fetchApiType", + "id", + "name", + "payWithoutFetchAllowed", + "paymentChannels", + "paymentModes", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "bbpsUpdateTimestamp": { + "type": "string", + "description": "Last updated date-time of the Biller accurate to the nearest day.", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": true + }, + "billerAdditionalInfo": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "billerAdditionalInfoPayment": { + "type": "array", + "items": { + "required": [ + "dataType", + "optional", + "paramName" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC", + "enum": [ + "ALPHANUMERIC", + "NUMERIC" + ] + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Package Duration" + } + } + } + }, + "categoryName": { + "type": "string", + "description": "Biller Category", + "example": "loan-repayment" + }, + "city": { + "type": "string", + "example": "Hyderabad" + }, + "country": { + "type": "string", + "example": "IND" + }, + "coverage": { + "type": "string", + "example": "IND-TEL-Hyderabad" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "dataType", + "maxLength", + "minLength", + "optional", + "paramName", + "regex", + "values", + "visibility" + ], + "type": "object", + "properties": { + "dataType": { + "type": "string", + "example": "ALPHANUMERIC" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "optional": { + "type": "boolean", + "example": false + }, + "paramName": { + "type": "string", + "example": "Loan Account Number" + }, + "regex": { + "type": "string", + "example": "^[a-zA-Z0-9]{7,15}" + }, + "values": { + "type": "string", + "example": "CHOICE1,CHOICE2,CHOICE3" + }, + "visibility": { + "type": "boolean", + "example": true + } + } + } + }, + "customerParamsGroups": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "example": "Param 1" + } + } + }, + "enforcesSameDayFetchPay": { + "type": "boolean", + "example": true, + "x-omitempty": false + }, + "exactness": { + "type": "string", + "example": "Exact", + "enum": [ + "Exact", + "Exact and above", + "Exact and below", + "Any", + "RANGE" + ] + }, + "fetchApiType": { + "type": "string", + "enum": [ + "BILL_FETCH", + "BILL_VALIDATE", + "BILL_DIRECT" + ] + }, + "id": { + "type": "string", + "description": "Identifier of the biller in BBPS.", + "example": "ADIT00000NAT0T" + }, + "interchangeFee": { + "type": "array", + "items": { + "type": "object", + "properties": { + "feeCode": { + "type": "string", + "example": "CCF1" + }, + "feeDesc": { + "type": "string", + "example": "Customer Convenience Fee" + }, + "feeDirection": { + "type": "string", + "example": "C2B" + }, + "interchangeFeeDetails": { + "required": [ + "effctvFrom", + "effctvTo", + "flatFee", + "percentFee", + "tranAmtRangeMax", + "tranAmtRangeMin" + ], + "type": "object", + "properties": { + "effctvFrom": { + "type": "string", + "example": "2024-01-01" + }, + "effctvTo": { + "type": "string", + "example": "2024-12-31" + }, + "flatFee": { + "type": "number", + "format": "decimal", + "example": 0.0 + }, + "percentFee": { + "type": "number", + "format": "decimal", + "example": 1.0 + }, + "tranAmtRangeMax": { + "type": "integer", + "format": "int64" + }, + "tranAmtRangeMin": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "logo": { + "type": "string", + "example": "logo" + }, + "modifiedAt": { + "type": "string", + "format": "date-time", + "nullable": true, + "example": "2021-11-12T13:37:04.572+05:30", + "x-omitempty": false + }, + "name": { + "type": "string", + "description": "Name of the biller.", + "example": "Umbrella Corporation" + }, + "payWithoutFetchAllowed": { + "type": "boolean", + "description": "Flag indicating if the Biller accepts adhoc payment", + "example": true + }, + "paymentChannels": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentChannel", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentChannel": { + "type": "string", + "description": "This is the initiating channel.\n1. `AGT`: Offline agent.\n2. `BNKBRNCH`: Bank branch.\n3. `BSC`: Business correspondent\n4. `MOB`: Mobile application\n5. `INT`: Internet portal\n6. `INTB`: Internet banking\n7. `MOBB`: Mobile banking\n8. `ATM`: ATM\n9. `KIOSK`: KIOSK\n", + "example": "INT", + "enum": [ + "INT", + "INTB", + "MOB", + "BNKBRNCH", + "BSC", + "AGT", + "KIOSK", + "ATM", + "MOBB", + "POS", + "MPOS" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "paymentModes": { + "type": "array", + "items": { + "required": [ + "maxLimit", + "minLimit", + "paymentMode", + "supportsPendingStatus" + ], + "type": "object", + "properties": { + "maxLimit": { + "type": "integer" + }, + "minLimit": { + "type": "integer" + }, + "paymentMode": { + "type": "string", + "example": "Internet Banking", + "enum": [ + "Internet Banking", + "Debit Card", + "Credit Card", + "Prepaid Card", + "IMPS", + "Cash", + "UPI", + "Wallet", + "NEFT", + "AEPS", + "Account Transfer", + "Bharat QR", + "USSD" + ] + }, + "supportsPendingStatus": { + "type": "boolean", + "example": false + } + } + } + }, + "pincode": { + "type": "string", + "example": "pincode" + }, + "planRequirement": { + "type": "string", + "description": "Indicates if plan selection is required for bill payments", + "example": "MANDATORY", + "enum": [ + "MANDATORY", + "OPTIONAL", + "CONDITIONAL" + ], + "x-omitempty": true + }, + "responseType": { + "type": "string", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "LIST", + "SELECTIVE" + ], + "x-nullable": true, + "x-omitempty": false + }, + "selectionType": { + "type": "string", + "description": "Defined only for billers with response type as LIST. SINGLE: User can pay only one of the bills in bill fetch response. MULTIPLE: User can pay any combination of bills in bill fetch response. ALL: User has to pay all the bills in bill fetch response.", + "nullable": true, + "example": "SINGLE", + "enum": [ + "SINGLE", + "MULTIPLE", + "ALL" + ], + "x-nullable": true, + "x-omitempty": false + }, + "state": { + "type": "string", + "example": "TEL" + }, + "subCategoryName": { + "type": "string", + "example": "DAIRY" + }, + "supportsPendingStatus": { + "type": "boolean", + "description": "Flag indicating whether pending status is applicable for the biller or not", + "example": false + }, + "tags": { + "type": "string", + "example": "tags" + }, + "upms_registration_overriding_rule": { + "type": "string", + "description": "Rule specifying how to handle UPMS registration conflicts", + "nullable": true, + "example": "NEWEST", + "x-omitempty": true + } + }, + "x-go-name": "CouBillerDetails" + }, + "billerId": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + }, + "custConvFee": { + "type": "integer", + "description": "Customer convenience fee in paise" + }, + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "customerParams": { + "type": "array", + "description": "The bill params for fetching the bill", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. This has to match what is sent in fields.", + "example": "Loan Number" + }, + "value": { + "type": "string", + "description": "The value of the customer parameter", + "example": "1895159" + } + } + } + }, + "etherealTransaction": { + "required": [ + "amount", + "billRefId", + "refId", + "status", + "transactionId" + ], + "type": "object", + "properties": { + "amount": { + "type": "string", + "example": "100.00" + }, + "billRefId": { + "type": "string", + "description": "The BBPS Ref ID", + "example": "C3SFG0O6N88R6UI7EQ" + }, + "refId": { + "type": "string", + "example": "COUWL910192192192192" + }, + "status": { + "type": "string", + "enum": [ + "INIT", + "SUCCESS", + "FAILURE", + "PENDING", + "UNKNOWN" + ] + }, + "transactionId": { + "type": "string", + "example": "Q910192192192192" + } + } + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "refundStatus": { + "type": "string", + "enum": [ + "Required", + "Requested", + "Processed" + ] + }, + "status": { + "type": "string", + "example": "Success", + "enum": [ + "Processing", + "Success", + "Error", + "Credit_Adjustment" + ] + }, + "timestamp": { + "type": "string", + "description": "Timestamp provided by partner while making payment request.", + "format": "date-time", + "example": "2020-12-12T13:12:00+05:30" + }, + "transactionId": { + "type": "string", + "description": "Setu BillPay Transaction ID.", + "example": "AS01910192192192192" + } + } + }, + { + "type": "object", + "properties": { + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "paymentRefId": { + "maxLength": 35, + "minLength": 6, + "type": "string", + "description": "Unique identifier provided by Partner for the payment request.", + "example": "BD019181220291" + } + } + } + ] + } + } + } + } + ] + } + } + } + ], + "x-go-name": "TransactionsResponse" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/health": { + "get": { + "tags": [ + "Health" + ], + "description": "Health check", + "operationId": "getHealth", + "responses": { + "200": { + "description": "Ok", + "content": { + "application/json": { + "schema": { + "required": [ + "environment", + "server", + "version" + ], + "type": "object", + "properties": { + "environment": { + "type": "string", + "example": "PROD" + }, + "server": { + "type": "string", + "example": "mistborn" + }, + "version": { + "type": "string", + "example": "db42717a829da9d3061e4f409f3c0ee9935b72a5" + } + }, + "x-go-name": "HealthResponseParam", + "x-omitempty": true + } + } + } + } + } + } + }, + "/api/v2/upms/registrations/{upmsRegistrationRefID}": { + "get": { + "tags": [ + "UPMS" + ], + "description": "This synchronous endpoint allows you to retrieve the current status and details of a specific, existing UPMS registration immediately.", + "operationId": "ViewUPMSRegistration", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefID", + "in": "path", + "description": "The reference ID of the UPMS registration you want to view.", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + }, + { + "name": "debug", + "in": "query", + "description": "DEBUG-FIELD: In debug, if the UPMS View Registration is sent to NPCI", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "OK", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "data": { + "required": [ + "biller", + "createdAt", + "customer", + "mandate", + "refId", + "status" + ], + "type": "object", + "properties": { + "biller": { + "required": [ + "id" + ], + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The biller ID on BBPS", + "example": "MAHI00000NATIC" + } + }, + "x-go-gen-location": "models", + "x-go-name": "BillerDetails" + }, + "createdAt": { + "type": "string", + "description": "Timestamp when registration was created", + "format": "date-time", + "example": "2024-06-15T10:30:45+05:30" + }, + "customer": { + "required": [ + "customerParams", + "mobile" + ], + "type": "object", + "properties": { + "customerId": { + "type": "string", + "description": "Customer Identifier" + }, + "customerParams": { + "type": "array", + "items": { + "required": [ + "name", + "value" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The display name of the parameter. This has to match what is sent in fields.", + "example": "Loan Number" + }, + "value": { + "type": "string", + "description": "The value of the customer parameter", + "example": "1895159" } } - }, - "paymentModes": { - "type": "array", - "items": { - "required": [ - "maxLimit", - "minLimit", - "paymentMode", - "supportsPendingStatus" - ], - "type": "object", - "properties": { - "maxLimit": { - "type": "integer" - }, - "minLimit": { - "type": "integer" - }, - "paymentMode": { - "type": "string", - "example": "Internet Banking", - "enum": [ - "Internet Banking", - "Debit Card", - "Credit Card", - "Prepaid Card", - "IMPS", - "Cash", - "UPI", - "Wallet", - "NEFT", - "AEPS", - "Account Transfer", - "Bharat QR", - "USSD" - ] - }, - "supportsPendingStatus": { - "type": "boolean", - "example": false - } + } + }, + "mobile": { + "maxLength": 22, + "minLength": 6, + "pattern": "^\\d{6,22}$", + "type": "string", + "description": "Mobile number with 6 to 22 digits are valid." + }, + "name": { + "maxLength": 100, + "type": "string", + "description": "Customer name registered with the Biller.", + "example": "Manoj Chekuri" + } + } + }, + "mandate": { + "type": "object", + "properties": { + "billPeriod": { + "type": "string", + "description": "Mandatory for Validation & Pay billers. Allowed values: DAILY, WEEKLY, BIMONTHLY, MONTHLY, QUARTERLY, HALFYEARLY, YEARLY\nOptional for Fetch & Pay billers. Allowed values: ASPRESENTED\n", + "nullable": true, + "example": "MONTHLY", + "x-omitempty": true + }, + "billerParams": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Captures the name of the biller parameter to be sent as part of UPMS registration.", + "example": "Low Balance Threshold" + }, + "value": { + "type": "string", + "description": "The value of the biller parameter to be sent as part of UPMS registration.", + "example": "500.0" } + }, + "description": "Optional. Only some billers require this. Details of the biller parameter to be sent as part of UPMS registration." + }, + "x-omitempty": true + }, + "debitInfo": { + "type": "object", + "properties": { + "amount": { + "type": "integer", + "description": "The fixed or maximum amount set for auto-debit (value must be provided in paise)." + }, + "currency": { + "type": "integer", + "description": "The currency code. Use `356` for `INR`." + }, + "debitDate": { + "type": "string", + "description": "The preferred date format (`DD-MMM`) for attempting the auto-debit each cycle.", + "example": "10-Feb" + }, + "paymentMode": { + "type": "string", + "description": "The payment method intended for auto-debit, allowed values:\n - Internet Banking\n - Debit Card\n - Credit Card\n - Prepaid Card\n - IMPS\n - UPI\n - Wallet\n - NEFT\n - AEPS\n - Account Transfer\n - Bharat QR", + "example": "UPI" + }, + "type": { + "type": "string", + "description": "Specifies the debit rule. Can be `FIXED_AMOUNT` (pay the exact bill amount) or `MAX_AMOUNT` (pay up to this limit).", + "example": "FIXED_AMOUNT" } }, - "pincode": { - "type": "string", - "example": "pincode" - } + "description": "Details for debit information (mandatory when registrationType is AUTO_PAY)" }, - "x-go-name": "CouBillerDetails" + "registrationType": { + "type": "string", + "description": "The type of registration (AUTO_PAY or VIEW_N_PAY)", + "example": "AUTO_PAY" + }, + "toDate": { + "type": "string", + "description": "The UPMS registration is invalid after this date. Date format is YYYY-MM-DD", + "nullable": true, + "example": "2025-01-01", + "x-omitempty": true + } + } + }, + "refId": { + "type": "string", + "description": "The generated Reference ID for the request." + }, + "status": { + "type": "string", + "description": "A UPMS registration progresses through various states. The status field captures the current state of the registration. The possible values are: - PENDING: Initial state after a registration request is accepted but before the registration is confirmed. - SUCCESS: Registration is active; bills will be presented via callbacks. - FAILED: Registration could not be completed (e.g., invalid details). - CANCELLED: Registration permanently cancelled by user or system. - DEACTIVATED: Registration has been deactivated.", + "enum": [ + "SUCCESS", + "FAILED", + "PENDING", + "CANCELLED", + "DEACTIVATED" + ] + }, + "updatedAt": { + "type": "string", + "description": "Timestamp when registration was last updated", + "format": "date-time", + "example": "2024-06-16T11:22:33+05:30" + } + } + }, + "success": { + "type": "boolean", + "description": "Boolean value indicating the status of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The unique traceId generated for the request", + "example": "CV4PE82LTNJE9O014OE0" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + }, + "delete": { + "tags": [ + "UPMS" + ], + "description": "This asynchronous endpoint permanently triggers cancellation of an active UPMS registration.", + "operationId": "CancelUPMSRegistration", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefID", + "in": "path", + "description": "The reference ID of the UPMS registration you want to cancel.", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success response", + "headers": { + "X-Frame-Options": { + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "schema": { + "type": "string" + } + }, + "Pragma": { + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "schema": { + "type": "string" + } + } + }, + "content": { + "*/*": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Indicator to denote whether the request is successful.", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request.", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found or unauthorized access", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "409": { + "description": "Registration status invalid for cancellation", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "*/*": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + }, + "patch": { + "tags": [ + "UPMS" + ], + "description": "Update details for a UPMS registration. This is an asynchronous API which only acknowledges receipt of a valid request. The actual result of the update operation will be communicated via a callback.\n", + "operationId": "UpdateUPMSRegistration", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "upmsRegistrationRefID", + "in": "path", + "description": "The reference ID of the UPMS registration you want to update.", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "mandate" + ], + "type": "object", + "properties": { + "mandate": { + "type": "object", + "properties": { + "billPeriod": { + "type": "string", + "description": "Desired frequency for bill presentation/payment. Valid only for billers with fetchApiType=BILL_VALIDATE, except ASPRESENTED.", + "enum": [ + "DAILY", + "WEEKLY", + "BIMONTHLY", + "MONTHLY", + "QUARTERLY", + "HALFYEARLY", + "YEARLY", + "ASPRESENTED" + ] + }, + "debitInfo": { + "type": "object", + "properties": { + "amount": { + "maximum": 999999999, + "minimum": 1, + "type": "integer", + "description": "The amount for FIXED_AMOUNT or maximum limit for MAX_AMOUNT.", + "nullable": true, + "x-omitempty": true + }, + "debitDate": { + "pattern": "^(0[1-9]|[12][0-9]|3[01])-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)$", + "type": "string", + "description": "Preferred date for debit (DD-MMM format). Valid only for billers with fetchApiType=BILL_VALIDATE.", + "example": "02-Jan" + }, + "type": { + "type": "string", + "description": "Type of debit limit.", + "example": "FIXED_AMOUNT", + "enum": [ + "FIXED_AMOUNT", + "MAX_AMOUNT" + ] } }, - "nextPage": { + "description": "Debit details for AUTO_PAY mandate updates. Only include fields that need changing." + }, + "registrationType": { + "type": "string", + "description": "Type of registration (AUTO_PAY or VIEW_N_PAY).", + "enum": [ + "AUTO_PAY", + "VIEW_N_PAY" + ] + }, + "toDate": { + "type": "string", + "description": "The date until which the mandate is valid (YYYY-MM-DD). Must be a future date.", + "format": "date", + "example": "2025-01-01" + } + }, + "description": "Details of the mandate to be updated. Only include fields that need changing." + } + }, + "x-go-name": "CouAgentUpdateUPMSRegistrationRequest", + "x-omitempty": true + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Update request acknowledged successfully.", + "headers": { + "X-Frame-Options": { + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "schema": { + "type": "string" + } + }, + "Pragma": { + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Indicator to denote whether the request is successful.", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request.", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "400": { + "description": "Bad request (e.g., validation error)", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { "type": "string", - "example": "/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS" + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found or unauthorized access", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "409": { + "description": "Conflict (e.g., trying to update a cancelled registration)", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" } } }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -5025,27 +7991,156 @@ }, "success": { "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ], + "x-codegen-request-body-name": "CouAgentUpdateUPMSRegistrationRequest" + } + }, + "/api/v2/upms/simulate/{billRefId}/callbacks/skip-payment": { + "post": { + "tags": [ + "UPMS" + ], + "description": "Simulates a skip payment notification for the specified bill. Validates the request, acknowledges receipt, and triggers an asynchronous callback delivery that indicates a payment was made through an alternative channel. For lower environments only.", + "operationId": "SimulateSkipPaymentNotification", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "billRefId", + "in": "path", + "description": "Reference ID of the Bill", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Request accepted and queued for processing", + "headers": { + "X-Frame-Options": { + "description": "X Frame options", + "schema": { + "type": "string" + } + }, + "Strict-Transport-Security": { + "description": "Strict transport security", + "schema": { + "type": "string" + } + }, + "Cache-Control": { + "description": "Cache control", + "schema": { + "type": "string" + } + }, + "X-Content-Type-Options": { + "description": "X Content type options", + "schema": { + "type": "string" + } + }, + "Content-Security-Policy": { + "description": "Content security policy", + "schema": { + "type": "string" + } + }, + "Pragma": { + "description": "Pragma", + "schema": { + "type": "string" + } + }, + "X-XSS-Protection": { + "description": "X Xss Protection", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Boolean value indicating the success of the request", "example": true }, "traceId": { "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" + "description": "The traceId generated for the request", + "example": "CV4PE82LTNJE9O014OE0" } - } + }, + "x-go-name": "SimulateCallbackResponse" } } } }, "400": { - "description": "Bad request", + "description": "Bad request - validation failed", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -5071,16 +8166,23 @@ } } }, - "500": { - "description": "Bad request", + "403": { + "description": "Forbidden - operation not allowed in current environment", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -5105,47 +8207,24 @@ } } } - } - }, - "security": [ - { - "Production": ["bbps:partner"] }, - { - "Sandbox": ["bbps:partner"] - }, - { - "QA": ["bbps:partner"] - } - ] - } - }, - "/api/v2/bbps/categories": { - "get": { - "tags": ["List"], - "description": "Returns the list of categories.", - "parameters": [ - { - "name": "X-PARTNER-ID", - "in": "header", - "description": "Partner ID", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "responses": { - "400": { - "description": "Bad request", + "404": { + "description": "Bill not found", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -5172,15 +8251,22 @@ } }, "500": { - "description": "Bad request", + "description": "Internal server error", "content": { "application/json": { "schema": { - "required": ["error", "success", "traceId"], + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -5205,9 +8291,59 @@ } } } + } + }, + "security": [ + { + "Production": [ + "bbps:partner" + ] + }, + { + "Sandbox": [ + "bbps:partner" + ] + }, + { + "QA": [ + "bbps:partner" + ] + } + ] + } + }, + "/api/v2/upms/simulate/{upmsRegistrationRefId}/callbacks/bill": { + "post": { + "tags": [ + "UPMS" + ], + "description": "Simulates a bill notification for the specified UPMS registration. Validates the request, acknowledges receipt, and triggers an asynchronous callback delivery. For lower environments only.", + "operationId": "SimulateBillNotification", + "parameters": [ + { + "name": "X-PARTNER-ID", + "in": "header", + "description": "The Partner ID provided by Setu.", + "required": true, + "schema": { + "type": "integer" + } }, + { + "name": "upmsRegistrationRefId", + "in": "path", + "description": "Reference ID of the UPMS registration", + "required": true, + "schema": { + "maxLength": 35, + "minLength": 35, + "type": "string" + } + } + ], + "responses": { "200": { - "description": "List of categories", + "description": "Request accepted and queued for processing", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -5255,11 +8391,45 @@ "content": { "application/json": { "schema": { - "required": ["success", "traceId"], + "required": [ + "success", + "traceId" + ], + "type": "object", + "properties": { + "success": { + "type": "boolean", + "description": "Boolean value indicating the success of the request", + "example": true + }, + "traceId": { + "type": "string", + "description": "The traceId generated for the request", + "example": "CV4PE82LTNJE9O014OE0" + } + }, + "x-go-name": "SimulateCallbackResponse" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], "type": "object", "properties": { "error": { - "required": ["code", "message"], + "required": [ + "code", + "message" + ], "type": "object", "properties": { "code": { @@ -5274,32 +8444,137 @@ }, "success": { "type": "boolean", - "example": true + "example": false }, "traceId": { "type": "string", "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "403": { + "description": "Forbidden in current environment", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } }, - "data": { - "required": ["categories"], + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "404": { + "description": "Registration not found", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], "type": "object", "properties": { - "categories": { - "type": "array", - "items": { - "type": "object", - "properties": { - "billerCount": { - "type": "integer" - }, - "name": { - "type": "string", - "example": "Loan Repayment" - } - } - } + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" + } + } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "required": [ + "error", + "success", + "traceId" + ], + "type": "object", + "properties": { + "error": { + "required": [ + "code", + "message" + ], + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "validation-error" + }, + "message": { + "type": "string", + "example": "Input is invalid" } } + }, + "success": { + "type": "boolean", + "example": false + }, + "traceId": { + "type": "string", + "example": "C3SFG0O6N88R6UI7EQ" } } } @@ -5309,13 +8584,19 @@ }, "security": [ { - "Production": ["bbps:partner"] + "Production": [ + "bbps:partner" + ] }, { - "Sandbox": ["bbps:partner"] + "Sandbox": [ + "bbps:partner" + ] }, { - "QA": ["bbps:partner"] + "QA": [ + "bbps:partner" + ] } ] }