From a0d7bb0e20aee494718003790a1969b7aae03853 Mon Sep 17 00:00:00 2001 From: Sreejit7 Date: Fri, 19 Sep 2025 15:52:39 +0530 Subject: [PATCH] Fix billpay docs broken hyperlinks and complaint response scenarios --- .../payments/billpay/api-integration.json | 406 +++--------------- .../payments/billpay/api-integration/apis.mdx | 8 +- .../api-integration/harmonization_of_tat.mdx | 4 +- .../api-integration/plan-mdm-integration.mdx | 12 +- .../billpay/api-integration/quickstart.mdx | 6 +- .../payments/billpay/api-integration/upms.mdx | 6 +- .../billpay/api-integration/v2-migration.mdx | 14 +- 7 files changed, 86 insertions(+), 370 deletions(-) diff --git a/api-references/payments/billpay/api-integration.json b/api-references/payments/billpay/api-integration.json index f23e2b70..662ded14 100644 --- a/api-references/payments/billpay/api-integration.json +++ b/api-references/payments/billpay/api-integration.json @@ -5432,83 +5432,9 @@ ], "type": "object", "properties": { - "duplicate": { - "required": [ - "code", - "message" - ], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "duplicate-ref-id" - }, - "message": { - "type": "string" - }, - "refId": { - "type": "string", - "description": "The generated Reference ID for the request." - } - } - }, "refId": { "type": "string", "description": "The generated Reference ID for the request." - }, - "upmsRegistration": { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "Status of the registration request processing by our system", - "example": "PENDING", - "enum": [ - "PENDING", - "FAILED" - ] - }, - "duplicate": { - "required": [ - "code", - "message" - ], - "type": "object", - "properties": { - "code": { - "type": "string", - "example": "duplicate-ref-id" - }, - "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" - } - }, - "description": "Present only when upmsRegistration was requested" } } }, @@ -5683,7 +5609,7 @@ }, "responses": { "200": { - "description": "Success - Dispute successfully created and initialized in the system", + "description": "Success - Dispute assigned to appropriate resolver for investigation", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -5749,7 +5675,7 @@ "properties": { "remarks": { "type": "string", - "example": "Complaint has been registered successfully" + "example": "Dispute assigned to appropriate resolver for investigation" }, "ticketType": { "type": "string", @@ -5761,14 +5687,14 @@ }, "assignedTo": { "type": "string", - "example": "SETU" + "example": "ICICI BOU" }, "status": { "type": "string", "description": "BBPS Complaint status", - "example": "INITIALIZED", + "example": "ASSIGNED", "enum": [ - "INITIALIZED" + "ASSIGNED" ] }, "disputeId": { @@ -5797,8 +5723,8 @@ } } }, - "200-dispute-assigned-to-bou": { - "description": "Success - Dispute assigned to Biller Operating Unit for investigation", + "200-dispute-default-resolved": { + "description": "Success - Dispute automatically resolved due to timeout or default process in favour of customer", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -5864,7 +5790,11 @@ "properties": { "remarks": { "type": "string", - "example": "Dispute assigned to Biller Operating Unit for investigation" + "example": "Dispute automatically resolved due to timeout or default process in favour of customer" + }, + "responseReason": { + "type": "string", + "example": "Automatic resolution due to timeout" }, "ticketType": { "type": "string", @@ -5881,125 +5811,30 @@ "status": { "type": "string", "description": "BBPS Complaint status", - "example": "ASSIGNED_TO_BOU", + "example": "DEFAULT_RESOLVED", "enum": [ - "ASSIGNED_TO_BOU" + "DEFAULT_RESOLVED" ] }, - "disputeId": { - "type": "string", - "example": "OP0121046567755" - }, - "refId": { - "type": "string", - "description": "The generated Reference ID for the request." - } - }, - "x-go-name": "DisputeResponseData" - }, - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - }, - "x-go-name": "CouAgentDisputeResponse", - "x-omitempty": true - } - } - } - }, - "200-dispute-assigned-to-cou": { - "description": "Success - Dispute assigned to Customer Operating Unit 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": { - "data": { - "required": [ - "assignedTo", - "disputeId", - "refId", - "remarks", - "status" - ], - "type": "object", - "properties": { - "remarks": { + "ticketTAT": { "type": "string", - "example": "Dispute assigned to Customer Operating Unit for processing" + "format": "date", + "nullable": true, + "example": "2024-01-20" }, - "ticketType": { + "disposition": { "type": "string", "enum": [ - "DISPUTE", - "COMPLAINT" + "D11", + "D12", + "D13", + "D21", + "D22", + "D23", + "D31", + "D32" ], - "example": "COMPLAINT" - }, - "assignedTo": { - "type": "string", - "example": "SETU COU" - }, - "status": { - "type": "string", - "description": "BBPS Complaint status", - "example": "ASSIGNED_TO_COU", - "enum": [ - "ASSIGNED_TO_COU" - ] + "example": "D11" }, "disputeId": { "type": "string", @@ -6027,8 +5862,8 @@ } } }, - "200-dispute-escalated": { - "description": "Success - Dispute escalated to higher authority for resolution", + "200-dispute-pending-refund": { + "description": "Success - Refund approved and currently being processed", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -6094,11 +5929,11 @@ "properties": { "remarks": { "type": "string", - "example": "Dispute escalated to higher authority due to complexity" + "example": "Refund approved and currently being processed" }, "responseReason": { "type": "string", - "example": "Requires management intervention" + "example": "Refund processing in progress" }, "ticketType": { "type": "string", @@ -6110,16 +5945,30 @@ }, "assignedTo": { "type": "string", - "example": "NPCI Escalation Team" + "example": "ICICI BOU" }, "status": { "type": "string", "description": "BBPS Complaint status", - "example": "ESCALATED", + "example": "PENDING_REFUND", "enum": [ - "ESCALATED" + "PENDING_REFUND" ] }, + "disposition": { + "type": "string", + "enum": [ + "D11", + "D12", + "D13", + "D21", + "D22", + "D23", + "D31", + "D32" + ], + "example": "D11" + }, "disputeId": { "type": "string", "example": "OP0121046567755" @@ -6147,7 +5996,7 @@ } }, "200-dispute-refunded": { - "description": "Success - Dispute resolved with successful refund to customer", + "description": "Success - Refund successfully processed and completed", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -6213,7 +6062,7 @@ "properties": { "remarks": { "type": "string", - "example": "Refund processed successfully to customer account" + "example": "Refund successfully processed and completed" }, "responseReason": { "type": "string", @@ -6286,7 +6135,7 @@ } }, "200-dispute-rejected": { - "description": "Success - Dispute rejected due to invalid claim or insufficient evidence", + "description": "Success - Dispute rejected due to insufficient evidence or invalid claims at biller's end", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -6352,7 +6201,7 @@ "properties": { "remarks": { "type": "string", - "example": "Dispute rejected due to insufficient evidence" + "example": "Dispute rejected due to insufficient evidence or invalid claims at biller's end" }, "responseReason": { "type": "string", @@ -6364,11 +6213,11 @@ "DISPUTE", "COMPLAINT" ], - "example": "COMPLAINT" + "example": "DISPUTE" }, "assignedTo": { "type": "string", - "example": "SETU COU" + "example": "ICICI BOU" }, "status": { "type": "string", @@ -6418,147 +6267,8 @@ } } }, - "200-dispute-resolved-favor-biller": { - "description": "Success - Dispute resolved in biller favor, no refund applicable", - "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": [ - "assignedTo", - "disputeId", - "refId", - "remarks", - "status" - ], - "type": "object", - "properties": { - "remarks": { - "type": "string", - "example": "Resolved in favour of Biller" - }, - "responseReason": { - "type": "string", - "example": "Biller provided valid service proof" - }, - "ticketType": { - "type": "string", - "enum": [ - "DISPUTE", - "COMPLAINT" - ], - "example": "DISPUTE" - }, - "assignedTo": { - "type": "string", - "example": "ICICI BOU" - }, - "status": { - "type": "string", - "description": "BBPS Complaint status", - "example": "RESOLVED", - "enum": [ - "RESOLVED" - ] - }, - "ticketTAT": { - "type": "string", - "format": "date", - "nullable": true, - "example": "2024-01-15" - }, - "disposition": { - "type": "string", - "enum": [ - "D11", - "D12", - "D13", - "D21", - "D22", - "D23", - "D31", - "D32" - ], - "example": "D23" - }, - "disputeId": { - "type": "string", - "example": "OP0121046567755" - }, - "refId": { - "type": "string", - "description": "The generated Reference ID for the request." - } - }, - "x-go-name": "DisputeResponseData" - }, - "success": { - "type": "boolean", - "example": true - }, - "traceId": { - "type": "string", - "example": "C3SFG0O6N88R6UI7EQ" - } - }, - "x-go-name": "CouAgentDisputeResponse", - "x-omitempty": true - } - } - } - }, - "200-dispute-resolved-favor-customer": { - "description": "Success - Dispute resolved in customer favor with refund eligibility", + "200-dispute-resolved": { + "description": "Success - Dispute successfully resolved through investigation in favour of customer", "headers": { "X-Frame-Options": { "description": "X Frame options", @@ -6624,7 +6334,7 @@ "properties": { "remarks": { "type": "string", - "example": "Resolved in favour of Customer" + "example": "Dispute successfully resolved through investigation in favour of customer" }, "responseReason": { "type": "string", diff --git a/content/payments/billpay/api-integration/apis.mdx b/content/payments/billpay/api-integration/apis.mdx index 52f22743..6d0b3e3c 100644 --- a/content/payments/billpay/api-integration/apis.mdx +++ b/content/payments/billpay/api-integration/apis.mdx @@ -17,7 +17,7 @@ For this, the core `fetch`, `pay` and `dispute` APIs are asynchronous. Each API ### Fetch bill -The Fetch bill API with endpoint `/bbps/bills/fetch/request` is used to get bill details for a customer. You need to pass the details of the customer and also the business they want to fetch their bill from. +The Fetch bill API with endpoint `/bbps/bills/fetch/request` is used to get bill details for a customer. You need to pass the details of the customer and also the business they want to fetch their bill from. For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid, you will need to provide— @@ -275,13 +275,13 @@ In the response you either get the bill details, or "Processing" status if the b ### Pay bill -The Pay bill API is used to send details of a payment done by a user on your app/website to Setu. Setu uses this information to confirm a payment with the biller. +The Pay bill API is used to send details of a payment done by a user on your app/website to Setu. Setu uses this information to confirm a payment with the biller.
### Raise dispute -The Raise Dispute API is used to Raise a compliant for a payment done by a user on your app/website to Setu. Setu uses this information and raises a compliant on the BBPS Platform. +The Raise Dispute API is used to Raise a compliant for a payment done by a user on your app/website to Setu. Setu uses this information and raises a compliant on the BBPS Platform.
@@ -324,7 +324,7 @@ For your convenience, Setu also provides actions to list data in bulk, that can > List disputes - —lists all the raised disputes using the Dispute API. + —lists all the raised disputes using the Dispute API. diff --git a/content/payments/billpay/api-integration/harmonization_of_tat.mdx b/content/payments/billpay/api-integration/harmonization_of_tat.mdx index 7e299ebd..3ed7612f 100644 --- a/content/payments/billpay/api-integration/harmonization_of_tat.mdx +++ b/content/payments/billpay/api-integration/harmonization_of_tat.mdx @@ -17,7 +17,7 @@ This document details the enhancements made to the dispute APIs to incorporate t ### 1. Dispute Request API Updates -The request api has been updated to include the new dispute types See API Reference . +The request api has been updated to include the new dispute types See API Reference . #### Dispute Type Mappings @@ -38,7 +38,7 @@ The following table shows how dispute types map to dispositions and ticket types ### 2. Dispute Response API Updates -The response api has been updated to include the new status values and fields See API Reference . +The response api has been updated to include the new status values and fields See API Reference . #### New Status Values diff --git a/content/payments/billpay/api-integration/plan-mdm-integration.mdx b/content/payments/billpay/api-integration/plan-mdm-integration.mdx index 33d5e367..e0734a61 100644 --- a/content/payments/billpay/api-integration/plan-mdm-integration.mdx +++ b/content/payments/billpay/api-integration/plan-mdm-integration.mdx @@ -324,9 +324,12 @@ POST /api/v2/bbps/bills/fetch/request } `} -> **Note:** If a biller uses a different parameter name for plan ID, check that biller's specification from List Billers API. + +Note: If a biller uses a different parameter name for plan ID, check that biller's specification from List Billers API. + +
-**V1 users:** Use customer.billParameters instead of customer.customerParams. +**V1 users:** Use `customer.billParameters` instead of `customer.customerParams`. **Complete Request Example:** @@ -495,7 +498,10 @@ Process payment for validated plans using the reference ID from validation.
-> **💰 Amount Format:** All amounts must be specified in **paise** (1 Rupee = 100 paise) and must match the selected plan's amount exactly. + + 💰 Amount Format: All amounts must be specified in paise (1 Rupee = 100 paise) and must match the selected plan's amount exactly. + +
**Response:** diff --git a/content/payments/billpay/api-integration/quickstart.mdx b/content/payments/billpay/api-integration/quickstart.mdx index 3edceff0..414fa36a 100644 --- a/content/payments/billpay/api-integration/quickstart.mdx +++ b/content/payments/billpay/api-integration/quickstart.mdx @@ -43,9 +43,9 @@ Each of these steps are described in detail below. ### Step 1 — Get your API keys -You have to use `X-PARTNER-ID` in the auth header and `clientID` and `secret` as the bearer token. Get these values by reaching out to the Setu team at onboarding@setu.co. +You have to use `X-PARTNER-ID` in the auth header and `clientID` and `secret` as the bearer token. Get these values by reaching out to the Setu team at onboarding@setu.co. -Once you have the credentials, get the token by making a `POST` request to `https://sandbox-coudc.setu.co/api/v1/auth/token`. +Once you have the credentials, get the token by making a `POST` request to `https://sandbox-coudc.setu.co/api/v2/auth/token`. {` { @@ -77,7 +77,7 @@ To reiterate, an agent is an entity on BBPS, that enables its customers to pay a ###### Share business details -Reach out to onboarding@setu.co to get a list of business details you need to provide to set up your BBPS agent ID(s). +Reach out to onboarding@setu.co to get a list of business details you need to provide to set up your BBPS agent ID(s). ###### Share callback URL diff --git a/content/payments/billpay/api-integration/upms.mdx b/content/payments/billpay/api-integration/upms.mdx index 1a71cfc8..75250db3 100644 --- a/content/payments/billpay/api-integration/upms.mdx +++ b/content/payments/billpay/api-integration/upms.mdx @@ -68,7 +68,7 @@ This document provides comprehensive information on: A UPMS registration represents an end-customer's mandate with a UPMS enabled 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. -UPMS is only available for billers who have the upmsEnabled flag set to true. You can check this flag using the List billers API, which also allows filtering by this flag. Trying to create a UPMS registration for billers without upmsEnabled set to true will fail. +UPMS is only available for billers who have the upmsEnabled flag set to true. You can check this flag using the List billers API, which also allows filtering by this flag. Trying to create a UPMS registration for billers without upmsEnabled set to true will fail. ### 2.2 Registration Lifecycle @@ -127,7 +127,7 @@ You must set up and provide us with a secure HTTPS webhook endpoint URL. This en This process leverages the existing **Bill Fetch API** endpoint. 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 /api/v2/bbps/bills/fetch/request` (See API Reference) +**Endpoint:** `POST /api/v2/bbps/bills/fetch/request` (See API Reference) **Type:** Asynchronous @@ -1096,7 +1096,7 @@ Note the presence of `upmsRegistrationRefId` indicating this is for a registered 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 API Reference) +1. **Invoke Payment API**: Construct and send a request to our BBPS Payment API endpoint. (See API Reference) 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 diff --git a/content/payments/billpay/api-integration/v2-migration.mdx b/content/payments/billpay/api-integration/v2-migration.mdx index b90b45a7..3aaf592f 100644 --- a/content/payments/billpay/api-integration/v2-migration.mdx +++ b/content/payments/billpay/api-integration/v2-migration.mdx @@ -11,7 +11,7 @@ The changes below will help you plan your migration from v1 to v2 specs. ### Bill Fetch Request -Following changes were made to this API +Following changes were made to this API | Type | Old | New | | ---- | ------------------------- | ------------------------- | @@ -49,7 +49,7 @@ Following changes were made to this API +Following changes were made to this API | Type | Old | New | | ---- | -------------------- | -------------- | @@ -92,7 +92,7 @@ Following changes were made to this API +Following changes were made to this API | Type | Old | New | | ---- | ------------------------- | ------------------------- | @@ -156,7 +156,7 @@ Following changes were made to this API +Following changes were made to this API | Type | Old | New | | ---- | ------------------- | --- | @@ -192,7 +192,7 @@ Following changes were made to this API +Following changes were made to this API | Type | Old | New | | ---- | ---------------- | --------------- | @@ -282,7 +282,7 @@ Following changes were made to this API +Following changes were made to this API | Type | Old | New | | --------------- | ---------------------- | --------------- | @@ -328,7 +328,7 @@ Following changes were made to this API +Following changes were made to this API | Type | Old | New | | ---- | ---------------------- | -------------- |