Skip to content

Update BBPS API documentation and remove deprecated content #333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tanmay-dixit merged 3 commits into from
Sep 16, 2025
Merged

Update BBPS API documentation and remove deprecated content #333

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66c0453
Update BBPS API documentation and remove deprecated content
Sreejit7 Sep 10, 2025
2aee767
Update API references and remove deprecated content
Sreejit7 Sep 12, 2025
320a48e
Add scenario based responses for multiple APIs, add Auth headers for all
Sreejit7 Sep 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15,807 changes: 10,111 additions & 5,696 deletions api-references/payments/billpay/api-integration.json
View file
Open in desktop

Large diffs are not rendered by default.

56 changes: 17 additions & 39 deletions content/payments/billpay/api-integration/apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ For this, the core `fetch`, `pay` and `dispute` APIs are asynchronous. Each API

### Fetch bill

The <a href="/payments/billpay/api-integration/api-reference#/category~Fetch_bill/operation~FetchRequest">Fetch bill API</a> 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 <a href="/payments/billpay/api-integration/api-reference#/category~Fetch/operation~FetchRequest">Fetch bill API</a> 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—

Expand All @@ -30,7 +30,7 @@ For e.g., if your customer wants to pay their phone bill for Vodafone Postpaid,
</li>
</ul>

Optionally, you can also register the customer with this biller simultaneously to receive future bills as and when they are generated (See [UPMS Integration Guide](upms.mdx)).
Optionally, you can also register the customer with this biller simultaneously to receive future bills as and when they are generated (See [UPMS Integration Guide](payments/billpay/api-integration/upms)).
If you include the `mandate` object in the request, a registration will be initiated for the customer with the biller.


Expand Down Expand Up @@ -77,6 +77,7 @@ If you include the `mandate` object in the request, a registration will be initi
"biller": {
"id": "VODA00000MUM03"
},
// optional - include to register customer with biller using UPMS
"mandate": {
"registrationType": "VIEW_N_PAY",
"billPeriod": "ASPRESENTED"
Expand Down Expand Up @@ -270,20 +271,17 @@ In the response you either get the bill details, or "Processing" status if the b
</details>
</Card>

<hr class="tertiary" />


<hr class="primary" />

### Pay bill

The <a href="/payments/billpay/api-integration/api-reference#/category~Pay_bill/operation~PaymentRequest" target="_blank">Pay bill API</a> is used to send details of a payment done by a user on your app/website to Setu. Setu uses this information to confirm payment with the biller.
The <a href="/payments/billpay/api-integration/api-reference#/category~Pay/operation~PaymentRequest" target="_blank">Pay bill API</a> 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.

<hr class="primary" />

### Raise dispute

The <a href="/payments/billpay/api-integration/api-reference#/category~Manage_Dispute/operation~DisputeRequest" target="_blank">Raise Dispute API</a> 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 <a href="/payments/billpay/api-integration/api-reference#/category~Dispute/operation~DisputeRequest" target="_blank">Raise Dispute API</a> 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.

<hr class="primary" />

Expand All @@ -295,7 +293,7 @@ For your convenience, Setu also provides actions to list data in bulk, that can
<li>
<a
target="_blank"
href="/payments/billpay/api-integration/api-reference#/category~Take_bulk_actions/operation~getCategories"
href="/payments/billpay/api-integration/api-reference#/category~List/path~/api/v2/bbps/categories/get"
>
List categories
</a>
Expand All @@ -304,7 +302,7 @@ For your convenience, Setu also provides actions to list data in bulk, that can
<li>
<a
target="_blank"
href="/payments/billpay/api-integration/api-reference#/category~Take_bulk_actions/operation~getBillers"
href="/payments/billpay/api-integration/api-reference#/category~List/path~/api/v2/bbps/billers/get"
>
List billers
</a>
Expand All @@ -313,7 +311,7 @@ For your convenience, Setu also provides actions to list data in bulk, that can
<li>
<a
target="_blank"
href="/payments/billpay/api-integration/api-reference#/category~List/path~/api/v2/bbps/bills/plans/get"
href="/payments/billpay/api-integration/api-reference#/category~List/operation~getBillerPlans"
>
List plans
</a>
Expand All @@ -322,47 +320,25 @@ For your convenience, Setu also provides actions to list data in bulk, that can
<li>
<a
target="_blank"
href="/payments/billpay/api-integration/api-reference#/category~Take_bulk_actions/operation~getDisputes"
href="/payments/billpay/api-integration/api-reference#/category~List/path~/api/v2/bbps/disputes/get"
>
List disputes
</a>
—lists all the raised disputes using the <a target="_blank" href="/payments/billpay/api-integration/api-reference#/category~Manage_Dispute/operation~DisputeRequest">Dispute API</a>.
</li>
<li>
<a
target="_blank"
href="/payments/billpay/api-integration/api-reference#/category~Take_bulk_actions/operation~getFetchedBills"
>
List fetched Bills
</a>
—lists all the fetched bills that were fetched using <a target="_blank" href="/payments/billpay/api-integration/api-reference#/category~Fetch_bill/operation~FetchRequest">
Fetch API
</a>.
</li>
<li>
<a
target="_blank"
href="/payments/billpay/api-integration/api-reference#/category~Take_bulk_actions/operation~getTxns"
>
List paid bills
</a>
—lists all the bill pay transactions paid using <a target="_blank" href="/payments/billpay/api-integration/api-reference#/category~Pay_bill/operation~PaymentRequest">
Pay API
</a>.
—lists all the raised disputes using the <a target="_blank" href="/payments/billpay/api-integration/api-reference#/category~Dispute/operation~DisputeRequest">Dispute API</a>.
</li>
</ul>

<hr class="primary" />

### Managing Customer Registrations
### Managing Customer Registrations via UPMS

These APIs allow you to manage the lifecycle of UPMS (Unified Presentment Management Service) registrations for your customers. Refer to the [UPMS Integration Guide](upms.mdx) for detailed flows and callback handling.
These APIs allow you to manage the lifecycle of UPMS (Unified Presentment Management Service) registrations for your customers. Refer to the [UPMS Integration Guide](/payments/billpay/api-integration/upms) for detailed flows and callback handling.

#### Viewing Registration Details

To retrieve the current status and details of a specific, existing UPMS registration.

**API Reference:** <a href="/payments/billpay/api-integration/api-reference#/category~UPMS_Registrations/operation~GetUPMSRegistrationDetails" target="_blank">GET /api/v2/upms/registrations/{upmsRegistrationRefID}</a>
**API Reference:** <a href="/payments/billpay/api-integration/api-reference#/category~UPMS/operation~ViewUPMSRegistration" target="_blank">GET /api/v2/upms/registrations/{upmsRegistrationRefID}</a>

<Card padding="nano" shape="rounded">
<details>
Expand Down Expand Up @@ -424,7 +400,7 @@ To retrieve the current status and details of a specific, existing UPMS registra

To modify specific details of an existing, active UPMS registration. This is an asynchronous operation; the final result is delivered via the [Update UPMS Registration webhook](/content/payments/billpay/api-integration/webhooks.mdx#update-upms-registration-webhook).

**API Reference:** <a href="/payments/billpay/api-integration/api-reference#/category~UPMS_Registrations/operation~UpdateUPMSRegistration" target="_blank">PATCH /api/v2/upms/registrations/{upmsRegistrationRefID}</a>
**API Reference:** <a href="/payments/billpay/api-integration/api-reference#/category~UPMS/operation~UpdateUPMSRegistration" target="_blank">PATCH /api/v2/upms/registrations/{upmsRegistrationRefID}</a>

<Card padding="nano" shape="rounded">
<details>
Expand Down Expand Up @@ -468,7 +444,7 @@ To modify specific details of an existing, active UPMS registration. This is an

To permanently cancel an existing UPMS registration. This is an asynchronous operation; confirmation comes via the [Cancel UPMS Registration webhook](/content/payments/billpay/api-integration/webhooks.mdx#cancel-upms-registration-webhook).

**API Reference:** <a href="/payments/billpay/api-integration/api-reference#/category~UPMS_Registrations/operation~CancelUPMSRegistration" target="_blank">DELETE /api/v2/upms/registrations/{upmsRegistrationRefID}</a>
**API Reference:** <a href="/payments/billpay/api-integration/api-reference#/category~UPMS/operation~CancelUPMSRegistration" target="_blank">DELETE /api/v2/upms/registrations/{upmsRegistrationRefID}</a>

<Card padding="nano" shape="rounded">
<details>
Expand All @@ -493,3 +469,5 @@ To permanently cancel an existing UPMS registration. This is an asynchronous ope
The <a href="/payments/billpay/api-integration/api-reference#/category~Health/operation~getHealth">health check API</a> tells you the health of the Setu BillPay server.

Aside from the above, there are other APIs which are also vital for a complete customer payment experience. See the <a href="/payments/billpay/api-integration/api-reference" target="_blank">full API reference</a> for more details.

<WasPageHelpful />
95 changes: 1 addition & 94 deletions content/payments/billpay/api-integration/bbps-v1_1-features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1140,97 +1140,4 @@ Only one of the payment options specified in the fetch response can be selected:
</Card>
<br />


<br/>


## Getting details of paid bills

The List Transactions API response now includes a new `bills` array element, providing detailed information about the bills involved in each transaction.

### Response

The `bills` array in the List Transactions API response contains objects with `billNumber` and `amount` for each bill involved in the transaction.

### Examples

#### LIST Transactions

1. The `bills` array in the response matches the `bills` array from the payment request.
2. It includes bills paid in the transaction (as present in payment request), regardless of the selection type.

<Card padding="nano" shape="rounded">
<details>
<summary>
<Text as="h6" marginBottom="none" marginTop="none">
Sample Response
</Text>
</summary>
<CodeBlockWithCopy language="json">{`
{
"transactions": [
{
// ... other transaction details ...
"bills": [
{ "billNumber": "BILL001", "amount": 100000 },
{ "billNumber": "BILL002", "amount": 150000 }
]
}
]
}
`}</CodeBlockWithCopy>
</details>
</Card>
<br />

### SINGLE Billers (Bill Present in Fetch Response)

The `bills` array contains one object with the `billNumber` and `amount` of the bill paid.

<Card padding="nano" shape="rounded">
<details>
<summary>
<Text as="h6" marginBottom="none" marginTop="none">
Sample Response
</Text>
</summary>
<CodeBlockWithCopy language="json">{`
{
"transactions": [
{
// ... other transaction details ...
"bills": [
{ "billNumber": "BILL001", "amount": 100000 }
]
}
]
}
`}</CodeBlockWithCopy>
</details>
</Card>
<br />

### SINGLE Billers (No Bill in Fetch Response)

An empty `bills` array is returned.

<Card padding="nano" shape="rounded">
<details>
<summary>
<Text as="h6" marginBottom="none" marginTop="none">
Sample Response
</Text>
</summary>
<CodeBlockWithCopy language="json">{`
{
"transactions": [
{
// ... other transaction details ...
"bills": []
}
]
}
`}</CodeBlockWithCopy>
</details>
</Card>
<br />
<WasPageHelpful />
Loading