#BBPS BillPay

#What is BBPS?

BBPS, or Bharat Bill Payment System, offers online and offline payments to over 20k businesses, including utilities, loan EMIs, and school fees.

#Who is an agent?

An agent is a registered BBPS entity allowed to collect payments for BBPS billers across all categories.x

You may register as an agent on BBPS, to collect BBPS bill payments with (Website Name) APIs on your supported collection channels (offline or online).

#What can I do with this product?

Our (Website Name) BillPay service lets your customers pay their bills on your app or website - from choosing companies to pay, to retrieving and paying bills. You can even collect payments directly from your business if you are a BBPS biller.

(Website Name) BBPS BillPay connects to NPCI through simple RESTful APIs, some of which are asynchronous. The API can be consumed only or you can subscribe to the webhook notifications (Website Name) provides.

You may integrate with (Website Name) in any of the following ways—

  • (Website Name) API integration -—Register as an agent institution and use the (Website Name) APIs. Use your own payment gateway and build your own screens.
  • Integration with a website—one-line integration with pre-built screens. Inbuilt UPI payment option.
  • App integration—Integrate with pre-built screens, as web views in your app. Support for Android and iOS. Inbuilt UPI payment option.

Pre-built screens from (Website Name) come with an inbuilt UPI payment option. By supporting a few more APIs, you can also use your own payment gateway. a few more APIs.


Was this page helpful?

#API integration

With (Website Name) BillPay, you can easily become an agent on the BBPS network and incorporate BBPS bill payments into your app or website. All necessary approvals are handled by (Website Name) in collaboration with our bank partner and BBPS.

This guide will walk you through the API integration process, help you create user-friendly screen flows, and get you ready to accept BBPS payments seamlessly on your platform.


#How to integrate

Grab your API keys first. Share the nitty-gritty with us to set up your agent. Dive into the API integration process. If you need a hand, hit us up at (Website Name) Support. Here's the breakdown:

A summary of the integration process—

  1. Get your API keys
  2. Provide details to set up agent
  3. Start API integration
  4. Share screens for NPCI approval
  5. Run and submit test cases
  6. Get production credentials and go live

Congratulations, you're live! Any issues? We've got your back at (Website Name) Support.


#Step 1 — Get your API keys

X-PARTNER-ID must be used in the auth header, and clientID and secret must be used for the bearer token. Contact the (Website Name) team at [Insert Contact Details] to learn more about these values .

Once you have the credentials, get the token by making a POST request to https://sandbox-kabini-coudc.(Website Name).co/api/v1/auth/token.

{
"clientID":"james-bond",
"secret":"5ja0077m-55e0-47s9-9bo7-ndaa18a7c0f7"
}

You then get a token which can be used to make Authenticated requests to BillPay APIs.

{
"expiresIn":600,
"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImxEUXBadm5xRmtTdlRaMDV6NFdjTjl0My0zY0JSVWo5di1rYnVNX2dpQkEifQ.eyJleHAiOjE2NTgzMTUwMDcsImlhdCI6MTY1ODMxMjAwNywianRpIjoiMjQzMTAwN2MtODAwNy00MDA3LWI5ZWUtZTQ4MmY2YTU3ZGViIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLWRldi5zZXR1LmNvL2F1dGgvcmVhbG1zL2NvdS1kYy1qYW1lcy1ib25kLXVhdCIsImF1ZCI6WyJqYW1lcy1ib25kIiwiYWNjb3VudCJdLCJzdWIiOiI0ZDhkMDY1Mi1kMmY2LTQyMWYtODNkMi0xYWUxYjc5ZTI1ZGIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJqYW1lcy1ib25kIiwic2Vzc2lvbl9zdGF0ZSI6ImExOThkMDA3LWViOWQtNDAwNy05NGRjLTNlMjJmYTEzYTAwNyIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cHM6Ly9qYW1lcy1ib25kLWNvdWRjLnNldHUuY28iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlNlY3JldF9JbnRlbGxpZ2VuY2VfU2VydmljZSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImphbWVzLWJvbmQiOnsicm9sZXMiOlsiU2VjcmV0X0ludGVsbGlnZW5jZV9TZXJ2aWNlIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbImNvdW50ZXItdGVycm9yaXNtIiwiY291bnRlci1wcm9saWZlcmF0aW9uIl19fSwic2NvcGUiOiJiYnBzOmJvbmQiLCJjbGllbnRJZCI6ImphbWVzLWJvbmQiLCJjbGllbnRIb3N0IjoiMDA3LjAwNy4wMDcuMDA3IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtamFtZXMtYm9uZCIsImNsaWVudEFkZHJlc3MiOiIwMDcuMDA3LjAwNy4wMDcifQ.svjuDXhx71uur_XYDCYLlObPBWctPHCDn1DtAAS-xMvnAvPdgqqVIUbGXdBxePE-blJPUDWH9J4ZXj5-kvi3onGdnmQxZcckW7dmIRrfTtUMCBj_4iefqiDV1D58Fblf9hCGjVGVWL9fuatNFvV46IaVREfaUTKuSbqwzhMpSGICJWhOM1Jt1Z2pB0x3e55dgmqhjeThZrstOwsJ2GTQ5N9gFennpmqmK_HVXU-rFwJzD44EMsN5GeH6Hh8zSC35NYkagrrlOkiuPGukoOMC9xFeGKGMSML3ve8_NmPVdhM6BaOwsau4wEJ-VV4oRY7TEl7d-IXmZqCVE0vyV2GZjQ",
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}


#Step 2 — Set up your BBPS agent

An agent on BBPS is an entity that allows its customers to pay any BBPS-listed business. In order to fetch bills for customers from BBPS-listed businesses, you need to register on BBPS and receive an agent ID.

Share business details

Contact [Insert Contact Detail] for a list of the business details you need to provide to create your BBPS agent ID(s).

Share callback URL

Setting up a callback URL is recommended for receiving notifications for various types of events

  • APIs to fetch bill for a customer
  • APIs to validate customer identifier with a biller
  • APIs to for completing a bill payment
  • APIs to raise disputes against a payment
  • APIs to receive an automatic bill due notification

When this is enabled by you, any successful fetch, validate, payment, dispute or autofetch event gets posted to your callback URL.

You may specify only one callback URL. This should be a valid URI string that starts with either https:// or http:// scheme.. For e.g., https://my-billpay-callback.com.

Website Name will append the following default paths to this callback URL, to alert your on specific events—

Event type Path
fetch a bill /bills/fetch/response
validate bill details /bills/validate/response
payment of bill /bills/payment/response
dispute against bill /bills/dispute/response
autofetch of a bill /bills/autofetch/response


Additionally, you can specify custom paths or URLs for fetch/validate/payment/dispute events too. URLs may be relative (a path without a host) or absolute (starting with a scheme)

 

Other events are not related to the core BillPay APIs, but are updates about BBPS businesses.

A business may be delisted from BBPS or update the type of identifier they accept to retrieve a customer's bill. Such events can be useful if you maintain a database of BBPS businesses. The full list of events can be found here.


#Step 3 — Start API integration

You can begin testing different scenarios for fetching/paying bills or raising disputes and managing their resolution once you receive your APIs keys and agent ID for testing.


#Step 4 — Share screens for NPCI approval

As part of your application development process, it is imperative to ensure that the screens align with the BBPS guidelines. To seek approval from NPCI, you are required to submit a comprehensive document featuring screenshots of the following key screens:

  • Category list screen, Displaying all BBPS categories.
  • Biller list screen, Enlisting all billers under a selected category.
  • Customer Input Screen, Where a customer inputs biller-specific identifiers before retrieving their bill.
  • Payment confirmation screen, Where the customer verifies the bill amount and proceeds with the payment.
  • Payment status screen, Reflecting the processing status of the payment, indicating whether it was successful or failed.
  • Confirmation SMS, The text message sent to customers after a payment, specifying its success or failure.
  • Bill receipt screen, Allowing customers to view and download receipts for successful transactions.
  • Raise complaint screen, Enabling customers to raise complaints, with specific transaction IDs associated.
  • Complaint status screen, Where customers can track the latest status of their registered complaints.

You may use the BBPS logo and branding guidelines provided here.


Throughout this submission, it is crucial to adhere to the BBPS guidelines and incorporate the provided logo and branding elements. The following points summarize the essential aspects to consider:

  • The application or website UI must feature a "Pay Bills" button prominently displaying the BBPS logo.
  • The BBPS logo should consistently appear in the top right corner of all screens utilized by customers during biller or bill searches, as well as on screens related to payment processes.
  • The BBPS Assured logo is mandatory on pages confirming payment success and providing payment receipts. However, the regular BBPS logo can be omitted from these specific pages.

#Step 5 — Execute and Document Test Cases

Follow the outlined test cases in this document and provide detailed documentation of the results using a copy of the specified file.

Please note that Postman logs will not be accepted as valid evidence.

Ensure that you share the results only after the screen integration is fully completed.


#Step 6 — Obtain Production Credentials and Launch

Upon successful completion of all required approvals and agreements, you will be issued production credentials. Once you receive these credentials, it is essential to verify the integration thoroughly. Subsequently, you are authorized to proceed with the deployment and officially launch your application or website.


Was this page helpful?

#Quickstart—API integration

Here is a concise overview of the APIs essential for initiating integration with the BBPS COU product for testing purposes.

As a representative of the BBPS system, your primary responsibilities involve facilitating customers in retrieving bills from any business listed on BBPS and enabling them to make payments to these businesses.

To achieve this, the fundamental fetch, pay and dispute APIs are asynchronous. Each API has a request endpoint and a response endpoint. The request endpoint registers the call and the response endpoint is used to retrieve the status of the registered call.


#Fetch bill

The utilization of the Fetch bill API with endpoint /bbps/bills/fetch/request is imperative for obtaining detailed bill information on behalf of a customer. It necessitates the submission of both the customer's particulars and the specific business from which they intend to retrieve their bill.

For instance, when facilitating the payment of a Vodafone Postpaid phone bill for a customer, it is essential to provide:

  • The customer's identifier, which, in this case, is the mobile number.

  • The business's identifier, denoted by the BBPS ID assigned to Vodafone in this context

Detailed sample request body
{
"customer":{
"mobile":"9505987798",
"billParameters":[
{
"name":"Parameter 1",
"value":"Value 1"
},
{
"name":"Parameter 2",
"value":"Value 2"
},
{
"name":"Parameter 3",
"value":"Value 3"
}
]
},
"agent":{
"app":"SmartPay",
"channel":"INT",
"geocode":"19.0139,72.8254",
"id":"AX01AI06512391457204",
"ifsc":"ICIC0000152",
"imei":"123456789012345",
"ip":"124.170.23.24",
"mac":"48-4D-7E-CB-DB-6F",
"mobile":"9481773011",
"os":"iOS",
"postalCode":"600001",
"terminalId":"6000011234"
},
"biller":{
"id":"VODA00000MUM03"
}
}

You get a refId in the response, a unique identifier that can be further used to check the status of the bill fetch.

{
"data":{
"refId":"LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689",
},
"success":true,
"error":null
}

You may also use the /bbps/bills/fetch/response endpoint with above refId to check status of the bill fetch—

{
"refId":"LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}

In the response you either get the bill details, or “Processing” status if the bill fetch is still in progress.

Sample response
{
"data":{
"additionalInfo":[
{
"name":"Distributor Contact",
"value":"Cockatoojelly"
},
{
"name":"Distributor Name",
"value":"Frightstripe"
},
{
"name":"Consumer Number",
"value":"105"
},
{
"name":"Consumer Address",
"value":"Samuraipsychadelic"
}
],
"bill":{// optional - not present if biller does not support it
"amount":301500,
"billDate":"2021-09-13",
"billNumber":"8394852342371080869",
"billPeriod":"Monthly",
"customerName":"William Miller",
"dueDate":"2021-09-26"
},
"billerRefId":"4047076513",
"exactness":"ANY",
"paymentLimits":[
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"Internet Banking",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"Debit Card",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"Credit Card",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"Prepaid Card",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"IMPS",
"supportsPendingStatus":false
},
{
"maxLimit":4999900,
"minLimit":100,
"paymentMode":"Cash",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"UPI",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"Wallet",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"NEFT",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"AEPS",
"supportsPendingStatus":false
},
{
"maxLimit":20000000,
"minLimit":100,
"paymentMode":"Account Transfer",
"supportsPendingStatus":false
}
],
"refId":"C51JQ9ED608P36RN28GGM9L63RN12591837",
"status":"Success"
},
"success":true,
"traceId":"C51JQCUD608P36RN28H0"
}

Auto-fetch bills

Alternatively, you have the option to activate automatic bill fetches for customer bills. By supplying the customer identifier and the BBPS identifier for the relevant business, (Website Name) obtains the necessary information to automatically retrieve bill details for each subsequent payment cycle. Upon successful automatic bill retrieval, the response is directed to the specified callback URL.

To initiate auto-fetch for a bill, you can activate the autoFetch field to true, when making a Fetch Bill API request to /bbps/bills/fetch/request. The system will recognize and adhere to this flag value once the bill fetch operation is successfully executed.

{
+ "autoFetch": true,
"customer": { ... },
"agent": { ... },
"biller": { ... }
}

Please be aware that it is essential to communicate your intention to enable automatic bill fetches for customers during the agent (Website Name)p process with (Website Name). This ensures that (Website Name) activates this feature for your account.


The response structure remains unchanged, accompanied by an additional field known as autoFetchHash. This hash serves as a unique identifier for the bill fetch and can be utilized to ascertain the last auto-fetched date, verify the ongoing status of auto-fetch, or disable auto-fetch for the bill in theManage auto-fetch for bills section.

{
+ "autofetchHash": "d28ca210e0267a13fa0db18ee96a349dc4578f032e5902192af762763224204a",
"data": { ... },
"success": true,
"traceId": "C51JQCUD608P36RN28H0"
}

When you set autoFetch flag to true, the response for Fetch bill will contain a autofetchHash. You can use this to—

  • Hit the /list endpoint to check if the bill autofetch is active, along with last date for bill fetch
  • Disable auto fetch by hitting the /delete endpoint

Note that you can also create an auto-fetch request for multiple bills at a time, using the /bbps/autofetches endpoint>.


Specify auto-fetch for multiple bills——A POST request to /bbps/autofetches lets you register multiple bills to be fetched automatically, at their respective payment cycles.


List auto-fetch details for multiple bills—A GET request to /bbps/autofetches returns list of bills registered for autofetch. Each entry has

  • lastFetchDate which is the date of the last bill fetch
  • isActive which specifies if bill has auto fetch enabled

Disable auto-fetch—A DELETE request to /bbps/autofetches/{autofetchHash} disable auto fetch for a bill on your app/website


#Pay bill

The Pay bill API serves the purpose of transmitting payment details executed by a user on your application or website to (Website Name). This information is utilized by (Website Name) to validate the payment with the respective biller.


#Raise dispute

The Raise Dispute API is employed to formally raise a complaint for a payment conducted by a user on your application or website. (Website Name) processes this information and initiates a complaint on the BBPS Platform.


#List data in bulk

To keep your systems updated with the latest data, (Website Name) also provides actions to list data in bulk. The following APIs are available—


#Check server health

The health check API tells you the health of the (Website Name) BillPay server.

Aside from the above, there are other APIs which are also vital for a complete customer payment experience. See the full API reference for more details.

#Payment Channel

This is the initiating payment channel.

type description
INT Internet Portal
INTB Internet Banking
MOB Mobile Application
BNKBRNCH Bank Branch
BSC Business correspondent
AGT Offline Agent
KIOSK KIOSK
ATM ATM
MOBB Mobile Banking
POS POS
MPOS MPOS

#Payment Mode

Payment modes supported by a biller.

type
Cash
Internet Banking
Credit Card
Debit Card
Prepaid Card
IMPS
NEFT
UPI
Wallet
AEPS
Account Transfer
Bharat QR
USSD

#Customer

Customer object holds the customer mobile number and the customer bill parameters.

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.

#Biller

Biller object holds the biller ID.

parameter type description
id string The Biller ID on BBPS

#Agent

Details pertaining to the Agent which initiates the transaction. Values of the field if provided to NPCI has to be matched against it.

parameter type description
id string The Agent ID on BBPS
channel PaymentChannel Payment Channel used by Agent.
ip string,ipv4 Agent server IP address
mac string,mac Server MAC address
mobile string Agent Mobile number
geocode string Agent Geocode
postalCode string Agent Pincode
terminalId string Agent terminal ID
imei string Agent IMEI
ifsc string Agent IFSC
os iOS or Android Initiating device OS
app string Initiating app name

#Initiating Channel & Required Agent parameters

Channel Agent parameters
BNKBRNCH ifsc,mobile,geocode,postalCode
MOB ip,imei,os,app
MOBB ip,imei,os,app
INT ip,mac
INTB ip,mac
ATM terminalId
KIOSK terminalId
AGT terminalId,mobile,geocode,postalCode
BSC terminalId,mobile,geocode,postalCode

#Initiating Channel & Eligible Payment modes

Payment Mode INT INTB MOB MOBB ATM BNKBRNCH KIOSK AGT BSC
Cash N N N N N Y Y Y Y
Internet Banking Y Y Y Y Y N N N N
Credit Card Y Y Y Y Y Y Y Y Y
Debit Card Y Y Y Y Y Y Y Y Y
Prepaid Card Y Y Y Y Y Y Y Y Y
IMPS Y Y Y Y N Y N Y Y
NEFT Y Y Y Y Y Y N Y Y
UPI Y Y Y Y N Y N Y Y
Wallet Y Y Y Y N Y Y Y Y
AEPS N N Y N N Y N Y Y
Account Transfer N N N N N Y N N Y
Bharat QR N N Y Y N Y N Y Y
USSD N N Y Y N N N N N

#Failure Reason

parameter type description
code string Error codes includes Application, Banking and BBPS error codes
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.

#Payment Details

parameter type description
mode Payment Mode Payment Mode
paymentRefId string (6 - 35 characters) Payment Reference ID tagged by agent
amount integer Amount in paise
timestamp date-time Timestamp

#Bill Status

type description
Processing Fetching a bill (or) Paying a bill is in progress
Success Successfully fetched a bill (or) paid a bill
Failure Unable to fetch a bill or pay a bill

#Transaction Status

type description
Processing Transaction is in progress
Success Transaction is successful
Failure Transaction has failed

#Dispute Status

type description
INITIALIZED Initialized
ASSIGNED Complaint has been accepted.
RE_ASSIGNED When Customer BBPOU re assigned the complaint to the Biller BBPOU.
ASSIGNED_TO_BOU When BBPCU assign the complaint to BBPOU. If the COU and BOU are same for a transaction, then the status of complaint will be changed to Assigned to OU
ASSIGNED_TO_COU When BBPCU assign the complaint to BBPOU. If the COU and BOU are same for a transaction, then the status of complaint will be changed to Assigned to OU
ASSIGNED_TO_OU When BBPCU assign the complaint to BBPOU. If the COU and BOU are same for a transaction, then the status of complaint will be changed to Assigned to OU
RESOLVED Once the BBPOU resolves the customer related complaint, the BBPOU updates the system.
UNRESOLVED If the BBPOU does not respond to the complaint within the specified TAT (Super escalation), the complaint status changed to unresolved.

#Bill Period

type
ONETIME
DAILY
WEEKLY
BIMONTHLY
MONTHLY
QUARTERLY
HALFYEARLY
YEARLY
ASPRESENTED
NA

#Bill Data

parameter type description
customerName string Bill owner
amount integer Bill amount in paise
dueDate date Bill due date
billDate date Bill date
billNumber string Bill number
billPeriod Bill Period Bill period of the bill fetch / payment requested. NA when bill period is unavailable.

#Exactness

Amount acceptance by the biller.

type description
Exact Exact amount
Exact and below Exact amount or below
Exact and above Exact amount or above

#Refund Status

type description
Required Refund will be processed for the transaction.
Requested Refund is requested for the transaction.
Processed Refund is processed.

#Payment Limit

parameter type description
paymentMode Payment Mode payment mode
supportsPendingStatus bool Whether payment mode for biller supports pending status
minLimit integer or null Minimum acceptable amount in paise
maxLimit integer or null Maximum acceptable amount in paise

#Dispute Type

type description
account-not-updated Transaction Successful, account not updated
double-payment Double payment updated
paid-to-wrong-account Erroneously paid in wrong account
amount-deducted-biller-credited-no-transaction-id Amount deducted, biller account credited but transaction ID not received
amount-deducted-biller-not-credited-no-transaction-id Amount deducted, biller account not credited & transaction ID not received
amount-deducted-multiple-times Amount deducted multiple times
others Other reason

#Biller Customer Params

parameter type description
dataType NUMERIC or ALPHANUMERIC Value format
maxLength integer or null Value's max length
minLength integer or null Value's min length
optional bool Is the parameter optional
paramName string Parameter name
regex string (Regex) Value Regex
values string Possible default values
visibility bool Visibility of the customer parameter in COU/AIs front-end screen

#Fetch API Type

type description
BILL_FETCH Biller can accept a Bill Fetch request.
BILL_VALIDATE Biller can accept a Bill Validate request.
BILL_DIRECT Biller can accept direct payment without a Bill Fetch or Bill Validate.

#Biller Payment Channel

Maxium amount accepted by the biller for the Payment Channel.

parameter type description
paymentChannel Payment Channel Payment Channel
supportsPendingStatus bool Whether payment channel for biller supports pending status
minLimit integer or null Minimum acceptable amount in paise
maxLimit integer or null Maximum acceptable amount in paise

#Biller Plan Information

parameter type description
amount integer Plan amount in paise
id string Plan ID
categoryType string Plan Category defined by the biller.
categorySubType string Plan Sub-Category defined by the biller.
description string Plan description
effectiveFrom date Plan effective from
effectiveTo date Plan effective to
status ACTIVE or DEACTIVE Plan status

#Transaction

/transactions

#Query Parameters

parameter type description
limit integer Default: 250, Maximum: 1000, Minimum: 1
after string
startDate date start date of the timestamp provided by the partner while making the request. Full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
endDate date end date of the timestamp provided by the partner while making the request. Full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
billerId string Transaction's Biller ID
status Transaction Status Transaction Status
mobile string (6, 10 and 20 digits) Customer Mobile Number

#Response

parameter type description
refId string BBPS Reference ID
status Transaction Status Transaction Status
transactionId string Website Name Transaction ID
partnerRefId string (6 - 35 characters) Payment Reference ID tagged by agent
billerId string BBPS Biller ID
amount integer Amount in paise
customerMobileNumber string (6, 10 and 20 digits) Customer Mobile Number
timestamp date-time Transaction timestamp
refundStatus Refund Status Refund status if the payment failed and the amount was debited.

#Dispute

/disputes

#Query Parameters

parameter type description
status Dispute Status Dispute status
limit integer Default: 250, Maximum: 1000, Minimum: 1
after string
transactionIds string[] Disputes' Website Name Transaction IDs
partnerRefIds string[] Disputes' Partner Transaction IDs
billerIds string[] DIsputes' Biller ID
customerMobileNumber string (6, 10 and 20 digits) Customer Mobile Number

#Response

parameter type description
assigned string BBPOU to which the complaint is assigned
billerId string Dispute's Transaction Biller ID
complaintId string Complaint ID for the dispute provided by BBPS
complaintStatus Dispute Status BBPS Complaint status
customerMobileNumber string (6, 10 and 20 digits) Customer Mobile Number
partnerRefId string (6 - 35 characters) Payment Reference ID tagged by agent
refId string BBPS reference ID for the dispute request
remarks string BBPS Remarks for the complaint
responseCode string BBPS Response code for the dispute request
responseReason string BBPS Response reason for the dispute request
transactionId string Website Name Transaction ID

#Biller MDM

/billers

#Query Parameters

parameter type description
categoryName string[] Category of the biller
ids string[] biller Ids
limit integer Default: 250, Maximum: 1000, Minimum: 1
after string Billers are sorted via the Biller ID. Providing a biller Id fetches billers right after this biller in a paginated way.
search string searches the provided text over biller name and biller alias
pincode string
state string
city string
tags string
paymentChannel Payment Channel[]
paymentMode Payment Mode[]

#Response

parameter type description
categoryName string Biller Category
city string Biller City
coverage string Biller coverage
createdAt date-time Biller Created At
customerParams Biller Customer Params[] Customer Parameter format descrption
exactness Exactness Biller Exactness
fetchApiType Fetch API Type Biller Fetch API Type
id string Biller ID
logo string Biller logo
modifiedAt date-time Biller Created At
name string Biller Name
payWithoutFetchAllowed bool Whether biller allows bill payment without a fetch or not. Even in case of BILL_FETCH API type, certain bills make the fetch optional
paymentChannels Biller Payment Channel[] Payment Channel limits set by the biller.
paymentModes Payment Limit[] Payment mode limits set by the biller.
pincode string Biller Pincode
supportsPendingStatus bool Whether the biller supports pending status. In this case, a payment can be in progress for up to 2 days.
tags string Additional Tags of the biller.
state string Biller State
plans Biller-Plan-Information[] Plans provided by the biller.

#Dispute Request

/bills/dispute/request

#Request Body

parameter type description
txnReferenceId string Website Name Transaction ID
disputeType Dispute Type Dispute type
description string (100 characters) Dispute description

#Dispute Response

/bills/dispute/response

#Response Body

parameter type description
refId string BBPS Reference ID
disputeId string Dispute ID used for the complaint
status Dispute Status Dispute Status
assignedTo string The entity who has this complaint assigned to.
remarks string Remarks of the complaint

#Fetch Request

/bills/fetch/request

#Request Body

parameter type description
customer Customer Customer Object
biller Biller Biller Object
Agent Agent Agent Object
autoFetch bool On true, enables auto-fetch for the bill on successful bill fetch

#Fetch Response

/bills/fetch/response

#Response Body

parameter type description
refId string BBPS reference ID for the fetch request.
status Bill Status Bill fetch request status.
failureReason Failure Reason Failure reason on status Failure
bill Bill Data Bill
additionalInfo {"name":"value"}[] Additional information of the bill sent by the biller
billerRefId string Biller reference ID used by the biller for the request.
exactness Exactness Biller Exactness
paymentLimits Payment Limit[] Payment limits
autoFetchHash string Auto fetch identifier for the bill.

#Payment Request

/bills/payment/request

#Request Body

parameter type description
customer Customer Customer Object
Biller Biller Biller Object
Agent Agent Agent Object
refId string BBPS Reference ID of Fetch Request for non-adhoc billers
paymentDetails Payment Details Payment information for paying the bill

#Payment Response

/bills/payment/response

#Response Body

parameter type description
refId string BBPS Reference ID
status Bill Status Transaction Status
failureReason Failure Reason Failure information in case of Transaction failure
transactionId string Website Name Transaction ID
billerRefId string Internal reference number used by the Biller for a transaction.
billerId string BBPS Biller ID
paymentDetails Payment Details Payment Details for the transaction
additionalInfo {"name":"value"}[] Additional information of the bill sent by the biller
refundStatus Refund Status Refund status if the payment failed and the amount was debited.

Was this page helpful?

#Webhooks

Here is the general structure of any webhook—

"traceId":"C3SFG0O6N88R6UI7EQ",
"timeStamp":"2021-11-12T00:12:29+05:30",
"event":"BILLER_UPDATES",
"data":{...}
  1. traceId is a unique ID assigned to the error and used by (Website Name) 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

#Bill fetch webhook

You can use this webhook to get information about outstanding bills on BBPS. When the Fetch bill API is used, it will be triggered. An error message will be displayed if the bill does not exist.

Method : POST
URL : To be provided by partner
Bill fetch sample request
{
"event":"BILL_FETCH",
"timeStamp":"2023-08-27T17:09:24.566+05:30",
"data":{
"bill":{
"amount":60500,
"billDate":"2023-06-02",
"billNumber":"3749280326878517751",
"billPeriod":"Monthly",
"customerName":"Elijah White",
"dueDate":"2023-06-02"
},
"billerRefId":"9540207519",
"exactness":"Exact",
"paymentLimits":[
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"Internet Banking",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"Debit Card",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"Prepaid Card",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"IMPS",
"supportsPendingStatus":false
},
{
"maxLimit":4999900,
"minLimit":100,
"paymentMode":"Cash",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"UPI",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"Wallet",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"NEFT",
"supportsPendingStatus":false
},
{
"maxLimit":99999900,
"minLimit":100,
"paymentMode":"AEPS",
"supportsPendingStatus":false
}
],
"refId":"CJLJBQK91PA0FD9MPMK0W75BD9M32391709",
"status":"Success"
}
}

#Bill payment webhook

A payment request for a particular bill has been received by NPCI. It will also pass on relevant errors and messages.

Method : POST
URL : To be provided by partner
Bill payment sample request
{
"event":"BILL_PAY",
"data":{
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status":"PROCESSING/SUCCESS/FAILURE",
"billerRefId":"ABC1235",
"transactionId":"AX01122999900001",
"failureReason":{
"code":"BRR005",
"message":"Biller not accepting payments at the moment"
},
"paymentDetails":{
"mode":"Internet Banking/Debit Card/Credit Card/IMPS/Cash/UPI/Wallet/NEFT/Prepaid Card/AEPS/Account Transfer/Bharat QR/USSD",
"paymentRefId":"N2001121212344",
"amount":10000,
"timestamp":"2020-12-12T13:12:00+05:30"
},
"billerId":"VODA00000MUM03"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ",
"error":null
}

#Dispute webhook

View the status update for a customer dispute using this webhook.

Method : POST
URL : To be provided by partner
Dispute sample request
{
"event":"BILL_DISPUTE",
"data":{
"refId":"JPMRPBOGGDTP1EFRZVXVESQVQIS10461642",
"complaintId":"OP0121046567755",
"status":"PROCESSING / OPEN / CLOSED",
"assignedTo":"AX39",
"remarks":"Resolved in favour of customer"
},
"success":true,
"error":null
}

#Autofetch bill webhook

This informs you that a new bill is due for a particular bill.

Method : POST
URL : To be provided by partner
Autofetch bill sample response
{
"event":"AUTOFETCH",
"data":{
"bill":{
"amount":324600,
"billDate":"2023-06-02",
"billNumber":"5085594745324366399",
"billPeriod":"Monthly",
"customerName":"Matthew Garcia",
"dueDate":"2023-06-02"
},
"billerRefId":"4096245202",
"customer":{
"billParameters":[
{
"name":"Application ID",
"value":"41116419"
}
],
"mobile":"9002198485"
},
"hash":"3ad9934ba90a1d0fd0fed3a3738dd74886240a1bb55575d18e07f063a10cc593",
"isActive":true,
"lastFetchDate":"2023-08-27",
"billerId":"AADH00000NATPT"
},
"timeStamp":"2023-08-27T17:09:26.405+05:30"
}

#Biller updates webhook

This is used to notify you about updates on any BBPS biller—including biller being added to or modified on the BBPS platform. In case of a biller gets modified, the request contains the biller with the new modification.

Method : POST
URL : To be provided by partner
Biller updates sample request
{
"event":"BILLER_UPDATES",
"traceId":"C6I7O22PC5TNLVD7QSKG",
"timeStamp":"2021-11-29T12:36:48.910+05:30",
"data":[
{
"ID":699158487875191900,
"Status":"ACTIVE",
"BillerAcceptsAdhoc":"F",
"BillerAdditionalInfo":[
{
"DataType":"ALPHANUMERIC",
"Optional":true,
"ParamName":"URL"
},
{
"DataType":"ALPHANUMERIC",
"Optional":true,
"ParamName":"Early Payment Date"
}
],
"BillerAdditionalInfoPayment":null,
"BillerAliasName":"TATA PWR - MUM",
"BillerCategoryName":"DTH",
"BillerCoverage":"IND",
"BillerCustomerParams":[
{
"dataType":"NUMERIC",
"maxLength":12,
"minLength":12,
"paramName":"Consumer Number"
}
],
"BillerDescription":"",
"BillerEffctvFrom":"2017-10-31",
"BillerEffctvTo":"2025-12-31",
"BillerID":"ZEE500000NAT01",
"BillerMode":"ONLINE",
"BillerName":"ZEE TV",
"BillerOwnerShp":"Private",
"BillerPaymentChannels":[
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"INT"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"INTB"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"MOB"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"MOBB"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"POS"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"MPOS"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"ATM"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"BNKBRNCH"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"KIOSK"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"AGT"
},
{
"minLimit":100,
"maxLimit":500000000,
"paymentChannel":"BSC"
}
],
"BillerPaymentModes":[
{
"minLimit":1,
"paymentMode":"Internet Banking"
},
{
"minLimit":1,
"paymentMode":"Debit Card"
},
{
"minLimit":1,
"paymentMode":"Credit Card"
},
{
"minLimit":1,
"paymentMode":"Prepaid Card"
},
{
"minLimit":1,
"paymentMode":"IMPS"
},
{
"minLimit":1,
"paymentMode":"Cash"
},
{
"minLimit":1,
"paymentMode":"UPI"
},
{
"minLimit":1,
"paymentMode":"Wallet"
},
{
"minLimit":1,
"paymentMode":"NEFT"
},
{
"minLimit":1,
"paymentMode":"AEPS"
},
{
"minLimit":1,
"paymentMode":"Account Transfer"
}
],
"BillerResponseParams":{
"amountOptions":[
{
"amountBreakupSet":[
"BASE_BILL_AMOUNT"
]
},
{
"amountBreakupSet":[
"Early Payment Amount"
]
}
]
},
"BillerTempDeactivationEnd":"",
"BillerTempDeactivationStart":"",
"BillerTimeOut":"",
"CustomerParamGroups":{
"groups":null
},
"FetchRequirement":"MANDATORY",
"InterchangeFee":null,
"ParentBiller":"",
"PaymentAmountExactness":"EXACT",
"PlanAdditionalInfo":null,
"PlanMdmRequirement":"",
"SupportBillValidation":"",
"SupportDeemed":"",
"SupportPendingStatus":"",
"NameVector":"'mum':3 'pwr':2 'tata':1 'tv':5 'zee':4",
"Plans":[
{
"ID":773944272117303200,
"PlanID":"1",
"AmountInRupees":"99.0",
"BillerID":"ZEE500000NAT01",
"CategorySubType":{
"subType":"1 Month"
},
"CategoryType":"Premium",
"EffctvFrom":"2021-01-01",
"EffctvTo":"2021-12-31",
"PlanAdditionalInfo":[],
"PlanDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,
Kids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"Status":"ACTIVE"
},
{
"ID":773944272134080400,
"PlanID":"2",
"AmountInRupees":"299.0",
"BillerID":"ZEE500000NAT01",
"CategorySubType":{
"subType":"2 Months"
},
"CategoryType":"Premium",
"EffctvFrom":"2021-01-01",
"EffctvTo":"2021-12-31",
"PlanAdditionalInfo":[],
"PlanDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,
Kids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"Status":"ACTIVE"
},
{
"ID":773944272142469000,
"PlanID":"3",
"AmountInRupees":"599.0",
"BillerID":"ZEE500000NAT01",
"CategorySubType":{
"subType":"6 Months"
},
"CategoryType":"Premium",
"EffctvFrom":"2021-01-01",
"EffctvTo":"2021-12-31",
"PlanAdditionalInfo":[],
"PlanDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,
Kids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"Status":"ACTIVE"
},
{
"ID":773944272159246300,
"PlanID":"4",
"AmountInRupees":"999.0",
"BillerID":"ZEE500000NAT01",
"CategorySubType":{
"subType":"12 Months"
},
"CategoryType":"Premium",
"EffctvFrom":"2021-01-01",
"EffctvTo":"2021-12-31",
"PlanAdditionalInfo":[],
"PlanDescription": "All ZEE5 Originals and Exclusives, Blockbuster Movies, All ALT Balaji Shows, Zindagi TV Shows,
Kids, Live TV, TV shows before telecast. Watch on 5 devices at a time",
"Status":"ACTIVE"
},
{
"ID":773944272167635000,
"PlanID":"5",
"AmountInRupees":"365.0",
"BillerID":"ZEE500000NAT01",
"CategorySubType":{
"subType":"12 Months"
},
"CategoryType":"Club",
"EffctvFrom":"2021-01-01",
"EffctvTo":"2021-12-31",
"PlanAdditionalInfo":[],
"PlanDescription": "TV shows before telecast, Select ZEE5 Originals, Select ALT Balaji Shows, Select Movies, Zindagi
TV Shows, Kids, Live TV. Watch on 2 devices at a time",
"Status":"ACTIVE"
}
]
}
]
}

Fetch bill

https://sandbox-coudc.(website name).co/api/v1/bbps/bills/fetch/request


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

agent

object

Required

autoFetch

boolean

When true, enables autofetch on successful bill.

biller

object

Required

customer

object

Required

Response

Body

data

object

Required

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/bills/fetch/request \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE' \
--header 'content-type: application/json' \
--data '{
"agent": {
"app": "SmartPay",
"channel": "INT",
"geocode": "19.0139,72.8254",
"id": "AX01AI06512391457204",
"ifsc": "ICIC0000152",
"imei": "123456789012345",
"ip": "124.170.23.24",
"mac": "48-4D-7E-CB-DB-6F",
"mobile": "9481773053",
"os": "iOS",
"postalCode": "600001",
"terminalId": "6000011234"
},
"autoFetch": true,
"biller": {
"id": "MAHI00000NATIC"
},
"customer": {
"billParameters": [
{
"name": "Loan Number",
"value": "1895159"
}
],
"mobile": "9481773053"
}
}'
200 OK

Response sample


{
"data": {
"refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
},
"success": true,
"traceId": "HENSVVR4QOS7X1UGPY7JGUV444P10461713"
}

Get fetched bill

https://sandbox-coudc.(website name).co/api/v1/bbps/bills/fetch/response


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

refId

string

Required

Response

Body

data

object

Required

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/bills/fetch/response \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE' \
--header 'content-type: application/json' \
--data '{
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}'
200 OK

Response sample


{
"data": {
"additionalInfo": [
{
"name": "Line item 1",
"value": "Value 1"
}
],
"autoFetchHash": "d28ca210e0267a13fa0db18ee96a349dc4578f032e5902192af762763224204a",
"bill": {
"amount": 120000,
"billDate": "2021-01-02",
"billNumber": "1232332",
"billPeriod": "Onetime",
"customerName": "Manoj Chekuri",
"dueDate": "2021-09-24"
},
"billerRefId": "7f16a032e514",
"exactness": "EXACT/EXACT_UP/EXACT_DOWN/ADHOC",
"failureReason": {
"code": "ERR004",
"message": "customer not found",
"type": "FUND_TRANSFER"
},
"paymentLimits": [
{
"maxLimit": 500000000,
"minLimit": 10100,
"paymentMode": "Internet Banking",
"supportsPendingStatus": true
}
],
"refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status": "Success"
},
"success": true,
"traceId": "C3SFG0O6N88R6UI7EQ"
}

Check health

https://sandbox-coudc.(Website Name).co/api/v1/health


Response

Body

environment

string

Required

server

string

Required

version

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url https://sandbox-coudc.(website name).co/api/v1/health
200 Ok

Response sample


{
"environment":"PROD",
"server":"mistborn",
"version":"db42717a829da9d3061e4f409f3c0ee9935b72a5"
}

Raise dispute

https://sandbox-coudc.(Website Name).co/api/v1/bbps/bills/complaint/request


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

description

string

Required

disputeType

string

Required

Valid values:

account-not-updateddouble-paymentpaid-to-wrong-accountothersamount-deducted-biller-credited-no-transaction-idamount-deducted-biller-not-credited-no-transaction-idamount-deducted-multiple-times

txnReferenceId

string

Required

Response

Body

data

object

Required

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/bills/complaint/request \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'\
--header 'content-type: application/json'\
--data '{
"description": "Amount deducted multiple times.",
"disputeType": "account-not-updated",
"txnReferenceId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
}'
200 OK

Response sample


{
"data":{
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202"
},
"success":true,
"traceId":"HENSVVR4QOS7X1UGPY7JGUV444P10461713"
}

Check dispute status

https://sandbox-kabini-coudc.(Website Name).co/api/v1/auth/token


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

refId

string

Required

Response

Body

data

object

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/bills/complaint/response \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'\
--header 'content-type: application/json'\
--data '{
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}'
200 OK

Response sample


{
"data":{
"assignedTo":"ICICI BOU",
"disputeId":"OP0121046567755",
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"remarks":"Resolved in favour of Biller",
"status":"ASSIGNED"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

List auto-fetched bills

https://sandbox-coudc.(Website Name).co/api/v1/bbps/autofetches


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner Id


Response

Body

data

object

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/autofetches \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 OK

Response sample


{
"data":{
"subscriptions":[
{
"biller":{
"id":"MAHI00000NATIC"
},
"customer":{
"billParameters":[
{
"name":"Loan Number",
"value":"1895159"
}
],
"mobile":"9481773053"
},
"hash":"d28ca210e0267a13fa0db18ee96a349dc4578f032e5902192af762763224204a",
"isActive":true,
"lastFetchDate":"2017-07-21"
}
]
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

Enable auto-fetch

https://sandbox-coudc.(Website Name).co/api/v1/bbps/autofetches


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner Id


Body

data

array

Response

Body

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/autofetches \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'\
--header 'content-type: application/json'\
--data '{
"data": [
{
"agent": {
"app": "SmartPay",
"channel": "INT",
"geocode": "19.0139,72.8254",
"id": "AX01AI06512391457204",
"ifsc": "ICIC0000152",
"imei": "123456789012345",
"ip": "124.170.23.24",
"mac": "48-4D-7E-CB-DB-6F",
"mobile": "9481773053",
"os": "iOS",
"postalCode": "600001",
"terminalId": "6000011234"
},
"biller": {
"id": "MAHI00000NATIC"
},
"customer": {
"billParameters": [
{
"name": "Loan Number",
"value": "1895159"
}
],
"mobile": "9481773053"
},
"hash": "d28ca210e0267a13fa0db18ee96a349dc4578f032e5902192af762763224204a",
"isActive": true,
"nextFetchDate": "2017-07-21"
}
]
}'
200 OK

Response sample


{
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

Disable auto-fetch

https://sandbox-coudc.(Website Name).co/api/v1/bbps/autofetches/{autofetchHash}


Request

Security

OAuth 2.0 - bbps

Path parameters

autofetchHash

string

Required


Header parameters

X-PARTNER-ID

integer

Required

Partner Id


Response

Body

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request DELETE \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/autofetches/{autofetchHash}\
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 OK

Response sample


{
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

Post payment details

https://sandbox-coudc.(Website Name).co/api/v1/bbps/bills/payment/request


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

agent

object

biller

object

customer

object

paymentDetails

object

Required

refId

string

BBPS Reference ID

Response

Body

data

object

Required

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/bills/payment/request \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'\
--header 'content-type: application/json'\
--data '{
"agent": {
"app": "SmartPay",
"channel": "INT",
"geocode": "19.0139,72.8254",
"id": "AX01AI06512391457204",
"ifsc": "ICIC0000152",
"imei": "123456789012345",
"ip": "124.170.23.24",
"mac": "48-4D-7E-CB-DB-6F",
"mobile": "9481773053",
"os": "iOS",
"postalCode": "600001",
"terminalId": "6000011234"
},
"biller": {
"id": "MAHI00000NATIC"
},
"customer": {
"billParameters": [
{
"name": "Loan Number",
"value": "1895159"
}
],
"mobile": "9481773053"
},
"paymentDetails": {
"amount": 10000,
"mode": "Internet Banking",
"paymentParams": [
{
"name": "Early Payment Amount",
"value": "100"
}
],
"paymentRefId": "BD019181220291",
"timestamp": "2020-12-12T13:12:00+05:30"
},
"refId": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
}'
200 OK

Response sample


{
"data":{
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202"
},
"success":true,
"traceId":"HENSVVR4QOS7X1UGPY7JGUV444P10461713"
}

Check payment status

https://sandbox-coudc.(Website Name).co/api/v1/bbps/bills/payment/response


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

refId

string

Required

Response

Body

data

object

Required

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/bills/payment/response \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'\
--header 'content-type: application/json'\
--data '{
"refId": "LNMSQQR4RKT7X1UGPY7JGUV454PL9T2C689"
}'
200 OK

Response sample


{
"data":{
"billerId":"MAHI00000NATIC",
"billerRefId":"ZA6291A177",
"failureReason":{
"code":"ERR004",
"message":"customer not found",
"type":"FUND_TRANSFER"
},
"paymentDetails":{
"amount":10000,
"mode":"Internet Banking",
"paymentParams":[
{
"name":"Early Payment Amount",
"value":"100"
}
],
"paymentRefId":"BD019181220291",
"timestamp":"2020-12-12T13:12:00+05:30"
},
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"refundDetails":{
"error":{
"code":"validation-error",
"message":"Input is invalid"
},
"status":"Success",
"transactionId":"AX30910192192192192"
},
"status":"Success",
"transactionId":"AX30910192192192192"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

List billers for category

https://sandbox-coudc.(Website Name).co/api/v1/bbps/billers


Request

Security

OAuth 2.0 - bbps

Query parameters

categoryName

array [string]

Category of the biller

ids

array [string]

Billers to search

limit

integer

Limit

Default:

250

Maximum:

1000

Minimum:

1

after

string

Billers are sorted via the Biller ID. Providing a biller Id fetches billers right after this biller in a paginated way.

search

string

Searches the provided text over Biller name and Biller Alias

pincode

string

state

string

city

string

tags

string

paymentChannel

array [string]

Valid values:

INTINTBMOBBNKBRNCHBSCAGTKIOSKATMMOBBPOSMPOS

paymentMode

array [string]

Valid values:

Internet BankingDebit CardCredit CardPrepaid CardIMPSCashUPIWalletNEFTAEPSAccount TransferBharat QRUSSD

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Response

Body

data

object

error

object

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url 'https://sandbox-coudc.(website name).co/api/v1/bbps/billers?categoryName=SOME_ARRAY_VALUE&ids=SOME_ARRAY_VALUE&limit=SOME_INTEGER_VALUE&after=SOME_STRING_VALUE&search=SOME_STRING_VALUE&pincode=SOME_STRING_VALUE&state=SOME_STRING_VALUE&city=SOME_STRING_VALUE&tags=SOME_STRING_VALUE&paymentChannel=SOME_ARRAY_VALUE&paymentMode=SOME_ARRAY_VALUE'\
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 List of billers

Response sample


{
"data":{
"billers":[
{
"categoryName":"loan-repayment",
"city":"city",
"coverage":"IND",
"createdAt":"2020-12-12T13:12:00+05:30",
"customerParams":[
{
"dataType":"ALPHANUMERIC",
"maxLength":15,
"minLength":7,
"optional":true,
"paramName":"Loan Account Number",
"regex":"^[a-zA-Z0-9]{7,15}",
"values":"values",
"visibility":true
}
],
"customerParamsGroups":[
[
"Param 1"
]
],
"exactness":"Exact",
"fetchApiType":"BILL_FETCH",
"id":"ADIT00000NAT0T",
"logo":"logo",
"modifiedAt":"2020-12-12T13:12:00+05:30",
"name":"Aditya Birla Sun Life Insurance",
"payWithoutFetchAllowed":true,
"paymentChannels":[
{
"maxLimit":500000000,
"minLimit":10100,
"paymentChannel":"INT",
"supportsPendingStatus":true
}
],
"paymentModes":[
{
"maxLimit":500000000,
"minLimit":10100,
"paymentMode":"Internet Banking",
"supportsPendingStatus":true
}
],
"pincode":"pincode",
"plans":[
{
"additionalInfo":[
{
"paramName":"Mobile Number",
"paramValue":"Text"
}
],
"amount":"22",
"categorySubType":{
"subType":"1 Month"
},
"categoryType":"VIP",
"description":"Unlimited Live Sports",
"effectiveFrom":"2017-07-21",
"effectiveTo":"2020-08-21",
"id":"1",
"status":"ACTIVE"
}
],
"state":"state",
"supportsPendingStatus":true,
"tags":"tags"
}
],
"nextPage":"/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS",
"total":3000
},
"error":{
"code":"validation-error",
"message":"Input is invalid"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

List all categories

https://sandbox-coudc.(Website Name).co/api/v1/bbps/categories


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Response

Body

data

object

error

object

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url https://sandbox-coudc.(website name).co/api/v1/bbps/categories \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 List of categories

Response sample


{
"data":{
"categories":[
{
"billerCount":10,
"name":"Loan Repayment"
}
]
},
"error":{
"code":"validation-error",
"message":"Input is invalid"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

List disputes

https://sandbox-coudc.(Website Name).co/api/v1/bbps/disputes


Request

Security

OAuth 2.0 - bbps

Query parameters

status

array [string]

Valid values:

INITIALIZEDASSIGNEDRE_ASSIGNEDASSIGNED_TO_BOUASSIGNED_TO_COUASSIGNED_TO_OUESCALATEDRESOLVEDUNRESOLVED

limit

integer

Limit

Default:

250

Maximum:

1000

Minimum:

1

after

string

mobile

string

Mobile number with 6, 10 and 20 digits are valid.

transactionIds

array [string]

Transaction IDs

partnerRefIds

array [string]

Partner provided transaction Ids

billerIds

array [string]

The biller ID on BBPS

customerMobileNumber

string

Mobile number with 6, 10 and 20 digits are valid.


Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Response

Body

data

object

error

object

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url 'https://sandbox-coudc.(website name).co/api/v1/bbps/disputes?status=SOME_ARRAY_VALUE&limit=SOME_INTEGER_VALUE&after=SOME_STRING_VALUE&mobile=SOME_STRING_VALUE&transactionIds=SOME_ARRAY_VALUE&partnerRefIds=SOME_ARRAY_VALUE&billerIds=SOME_ARRAY_VALUE&customerMobileNumber=SOME_STRING_VALUE'\
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 List of disputes

Response sample


{
"data":{
"disputes":[
{
"assigned":"OU Four",
"billerId":"MAHI00000NATIC",
"complaintId":"OP0121046567755",
"complaintStatus":"ASSIGNED",
"customerMobileNumber":"9481773053",
"partnerRefId":"AX30910192192192192",
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10461713",
"remarks":"Payment Pending",
"responseCode":"0",
"responseReason":"SUCCESS",
"transactionId":"AX30910192192192192"
}
],
"nextPage":"/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS",
"total":3000
},
"error":{
"code":"validation-error",
"message":"Input is invalid"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

List fetched bills

https://sandbox-coudc.(Website Name).co/api/v1/bbps/fetched-bills


Request

Security

OAuth 2.0 - bbps

Query parameters

autoFetchHash

array [string]

Autofetch hash if present

limit

integer

Limit

Default:

250

Maximum:

1000

Minimum:

1

after

string

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Response

Body

data

object

error

object

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url 'https://sandbox-coudc.(website name).co/api/v1/bbps/fetched-bills?autoFetchHash=SOME_ARRAY_VALUE&limit=SOME_INTEGER_VALUE&after=SOME_STRING_VALUE'\
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 List of fetched bills

Response sample


{
"data":{
"bills":[
{
"additionalInfo":[
{
"name":"Line item 1",
"value":"Value 1"
}
],
"autoFetchHash":"d28ca210e0267a13fa0db18ee96a349dc4578f032e5902192af762763224204a",
"bill":{
"amount":120000,
"billDate":"2021-01-02",
"billNumber":"1232332",
"billPeriod":"Onetime",
"customerName":"Manoj Chekuri",
"dueDate":"2021-09-24"
},
"billerRefId":"7f16a032e514",
"exactness":"EXACT/EXACT_UP/EXACT_DOWN/ADHOC",
"failureReason":{
"code":"ERR004",
"message":"customer not found",
"type":"FUND_TRANSFER"
},
"paymentLimits":[
{
"maxLimit":500000000,
"minLimit":10100,
"paymentMode":"Internet Banking",
"supportsPendingStatus":true
}
],
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status":"Success"
}
],
"nextPage":"/api/v1/bbps/fetched-bills?autoFetchHash=xyz&after=ABCC00000PTNNS&limit=5",
"total":3000
},
"error":{
"code":"validation-error",
"message":"Input is invalid"
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

List paid bills

https://sandbox-coudc.(Website Name).co/api/v1/bbps/transactions


Request

Security

OAuth 2.0 - bbps

Query parameters

limit

integer

after

string

startDate

string

start date of the timestamp provided by the partner while making the request. Full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

endDate

string

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

billerId

string

Transaction BillerId

ids

array [string]

Transaction Reference Ids

status

string

Transaction Status

Valid values:

ProcessingSuccessErrorRefunded

mobile

string

Mobile number with 6, 10 and 20 digits are valid.


Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Response

Body

data

object

Required

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url 'https://sandbox-coudc.(website name).co/api/v1/bbps/transactions?limit=SOME_INTEGER_VALUE&after=SOME_STRING_VALUE&startDate=2022-07-19&endDate=2022-07-19&billerId=SOME_STRING_VALUE&ids=SOME_ARRAY_VALUE&status=SOME_STRING_VALUE&mobile=SOME_STRING_VALUE'\
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'
200 List of Txns

Response sample


{
"data":{
"nextPage":"/api/bbps/billers?search=Aditya&CategoryCode=Loan+Repayment&CategoryCode=Insurance&after=ABCC00000PTNNS",
"transactions":[
{
"amount":120000,
"billerId":"MAHI00000NATIC",
"customerMobileNumber":"9481773053",
"partnerRefId":"AX30910192192192192",
"refId":"HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status":"Success",
"timestamp":"2020-12-12T13:12:00+05:30",
"transactionId":"AX30910192192192192"
}
]
},
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}

This section's documentation is being revamped. Visit the API Reference. for more information. For more information, please contact (Website Name) Support.

#User events

A webhook can be configured to listen to users’ events and log them for analytics and re-engagement purposes.

This feature is opt-in and is configured only when a partner requests for it to be enabled. This supports use cases like getting real-time payment status and related details after bill payment is done by customer.



#Pre-requisites

You need to do the following to configure a Website Name provided webhook—

  1. Share the webhook URL. A URL that can accept JSON data over POST.
  2. API Key (optional)—It can also be generated by (website name), for you.
  3. Take steps to handle the notification

Share the webhook URL

This step requires setting up and sharing a webhook URL to (website name) which is capable of receiving the transaction notifications. The URL to setup this webhook must be shared with (website name) via email to billpay.support@(website name).co.


Handle the notification

The notification consists of body an authentication header as well as a body/payload. The authentication header will be sent as X-BILL-WEBHOOK-API-KEY. The value for the same shall be communicated over email.


#List of notifications

The following events are supported in the bill payment journey—

  • bill_fetch_success
  • bill_fetch_failure
  • bill_payment_success
  • bill_payment_failure
  • bill_collection_failure
  • bill_payment_refunded
  • dispute_raised
  • dispute_status_change

Below are the parameter tables and sample payloads for the listed events. Note that we may add additional parameters at a later stage. However, we will ensure backwards compatibility and no keys will be removed.


All the values in the response payload are strings



bill_fetch_success — Notification when bill-fetch request is successful

Sample payload
{
"mobileNumber":"9481773053",
"status":"FETCH_SUCCESS",
"billId":"490a8940-886e-45ed-bfd1-21dbed064373",
"billerId":"MAHI00000NATIC",
"billerName":"Mahindra Rural Housing Finance Ltd",
"billerCategory":"Loan-Repayment",
"billAmount":"101.0",
"dueDate":"2021-05-23",
"sessionId":"7f6de02a-0061-403f-bd65-47d4b5f72c87",
"event":"bill_fetch_success",
"additionalInfo":[
{
"name":"example",
"value":"ABC"
}
]
}

Parameter Data Type Description Example
mobileNumber String (Number) Mobile number used to generate the bill-fetch request 9481773053
status String Status of the bill-fetch request FETCH_SUCCESS
billId String Unique identifier for the bill. It is generated by the biller. Also called as billNumber. Not applicable where there is no bill. 490a8940-886e-45ed-bfd1-21dbed064373
billerId String Unique identifier (Biller ID in BBPS) allocated to the Biller MAHI00000NATIC
billerName String Name of the biller as registered with BBPS Mahindra Rural Housing Finance Ltd
billerCategory String Category of the biller as registered with BBPS. There are more than 25 biller categories. Loan-Repayment; Electricity; Landline-Postpaid etc.
billAmount String (Number) Amount of the bill in rupees (INR) 101.55
dueDate String (Date) Due date of the bill. Format is YYYY-MM-DD.
sessionId String Unique identifier for the session used for this request 7f6de02a-0061-403f-bd65-47d4b5f72c87
event String Name of the event to identify this user event bill_fetch_success
additionalInfo String Additional info available to Agent Institutions basis the additional info passed by the biller. name:"example" value:"ABC"

bill_fetch_failure — Notification when bill-fetch request is not successful

Sample payload
{
"mobileNumber":"9481773053",
"status":"FETCH_FAILURE",
"billId":"69a1fbc0-b5d1-4cbf-ac6d-c4244e3e7e0c",
"billerId":"MAHI00000NATIC",
"billerName":"Mahindra Rural Housing Finance Ltd",
"billerCategory":"Loan-Repayment",
"sessionId":"7f6de02a-0061-403f-bd65-47d4b5f72c87",
"event":"bill_fetch_failure",
"fetchErrorCode":"ERR001",
"error":{
"code":"ERR001",
"message":"Unable to get details"
}
}

Parameter Data Type Description Example
mobileNumber String (Number) Mobile number used to generate the bill-fetch request 9481773053
status String Status of the bill-fetch request FETCH_FAILURE
billId String Unique identifier for the bill. It is generated by the biller. Also called as billNumber. Not applicable where there is no bill. 69a1fbc0-b5d1-4cbf-ac6d-c4244e3e7e0c
billerId String Unique identifier (Biller ID in BBPS) allocated to the Biller MAHI00000NATIC
billerName String Name of the biller as registered with BBPS Mahindra Rural Housing Finance Ltd
billerCategory String Category of the biller as registered with BBPS. There are more than 25 biller categories. Loan-Repayment
sessionId String Unique identifier for the session used for this request 7f6de02a-0061-403f-bd65-47d4b5f72c87
event String Name of the event to identify this user event bill_fetch_failure
fetchErrorCode String Error codes for the failure ERR001
error Error array containing details of the error
code String Error code ERR001
message String Error description Unable to get details

bill_payment_success — Notification when bill-payment request is successful

Sample payload
{
"txnId":"AXO101557980",
"mobileNumber":"9481773053",
"status":"PAYMENT_SUCCESS",
"billId":"dfeeaf14-e43a-4196-90d0-41089e979ad5",
"billerId":"MAHI00000NATIC",
"billerName":"Mahindra Rural Housing Finance Ltd",
"billerCategory":"Loan-Repayment",
"sessionId":"7f6de02a-0061-403f-bd65-47d4b5f72c87",
"billAmount":"105.0",
"dueDate":"2021-05-23",
"amountPaid":"601.00",
"orderId":"H001234566666",
"event":"bill_payment_success",
"paidOn":"02-01-2006 15:04:05",
}

Parameter Data Type Description Example
txnId String Unique identifier for the transaction generated by COU, here (website name). Also known as BBPS transaction ID. AXO101557980
mobileNumber String (Number) Mobile number used to generate the bill-payment request 9481773053
status String Status of the bill-payment request PAYMENT_SUCCESS
billId String Unique identifier for the bill. It is generated by the biller. Also called as billNumber. Not applicable where there is no bill. dfeeaf14-e43a-4196-90d0-41089e979ad5
billerId String Unique identifier (Biller ID in BBPS) allocated to the Biller MAHI00000NATIC
billerName String Name of the biller as registered with BBPS Mahindra Rural Housing Finance Ltd
billerCategory String Category of the biller as registered with BBPS. There are more than 25 biller categories. Loan-Repayment
sessionId String Unique identifier for the session used for this request 7f6de02a-0061-403f-bd65-47d4b5f72c87
billAmount String (Number) Amount of the bill in rupees (INR) 601.75
dueDate String (Date) Due date of the bill. Format is YYYY-MM-DD. 44339
amountPaid String (Number) Amount paid by the user in rupees (INR). This is especially applicable for billers where there is no billAmount, eg. Fastag 2022-01-03
orderId String Unique identifier for a payment request. Generated by (website name). H001234566666
event String Name of the event to identify this user event bill_payment_success
paidOn String (DateTime) Time of transaction 02-01-2006 15:04:05"

bill_payment_failure — Notification when bill-payment request is not successful

Sample payload
{
"txnId":"AXO101557980",
"mobileNumber":"9481773053",
"status":"PAYMENT_FAILED",
"billId":"dfeeaf14-e43a-4196-90d0-41089e979ad5",
"billerId":"MAHI00000NATIC",
"billerName":"Mahindra Rural Housing Finance Ltd",
"billerCategory":"Loan-Repayment",
"sessionId":"7f6de02a-0061-403f-bd65-47d4b5f72c87",
"orderId":"Q00ABCDEFGHZOQ",
"billAmount":"105.0",
"dueDate":"2021-05-23",
"amountPaid":"601.00",
"event":"bill_payment_failure"
}

Parameter Data Type Description Example
txnId String Unique identifier for the transaction generated by COU, here (website name). Also known as BBPS transaction ID. AX0101557980
mobileNumber String (Number) Mobile number used to generate the bill-payment request 9481773053
status String Status of the bill-payment request PAYMENT_FAILED
billId String Unique identifier for the bill. It is generated by the biller. Also called as billNumber. Not applicable where there is no bill. dfeeaf14-e43a-4196-90d0-41089e979ad5
billerId String Unique identifier (Biller ID in BBPS) allocated to the Biller MAHI00000NATIC
billerName String Name of the biller as registered with BBPS Mahindra Rural Housing Finance Ltd
billerCategory String Category of the biller as registered with BBPS. There are more than 25 biller categories. Loan-Repayment
sessionId String Unique identifier for the session used for this request 7f6de02a-0061-403f-bd65-47d4b5f72c87
orderId String Unique identifier for a payment request. Generated by (website name). Q00ABCDEFGHZOQ
billAmount String (Number) Amount of the bill in rupees (INR) 101.55
dueDate String (Date) Due date of the bill. Format is YYYY-MM-DD. 44339
amountPaid String (Number) Amount paid by the user in rupees (INR). This is applicable for billers where there is no bill generated, eg. Fastag 601.75
event String Name of the event to identify this user event bill_payment_failure

bill_collection_failure — Notification when bill-collection from the user's account is not successful

Sample payload
{
"txnId":null,
"mobileNumber":"9481773053",
"status":"COLLECTION_FAILURE",
"billId":"dfeeaf14-e43a-4196-90d0-41089e979ad5",
"billerId":"MAHI00000NATIC",
"billerName":"Mahindra Rural Housing Finance Ltd",
"billerCategory":"Loan-Repayment",
"customerId":"9CBV4C9MSURWXRM54Q3DY8WEE",
"billAmount":"105.0",
"dueDate":"2021-05-23",
"sessionId":"7f6de02a-0061-403f-bd65-47d4b5f72c87",
"amountPaid":601.00,
"amount":null,
"event":"bill_collection_failure"
}

Parameter Data Type Description Example
txnId Unique identifier for the transaction generated by COU. Not generated here because Website Name does not post the bill-payment request to BBPS. null
mobileNumber String (Number) Mobile number used to generate the bill-payment request 9481773053
status String Status of the bill-payment request COLLECTION_FAILURE
billId String Unique identifier for the bill. It is generated by the biller. Also called as billNumber. Not applicable where there is no bill. dfeeaf14-e43a-4196-90d0-41089e979ad5
billerId String Unique identifier (Biller ID in BBPS) allocated to the Biller MAHI00000NATIC
billerName String Name of the biller as registered with BBPS Mahindra Rural Housing Finance Ltd
billerCategory String Category of the biller as registered with BBPS. There are more than 25 biller categories. Loan-Repayment
customerId String (website name)'s customer reference ID 9CBV4C9MSURWXRM54Q3DY8WEE
billAmount String (Number) Amount of the bill in rupees (INR) 101.55
dueDate String (Date) Due date of the bill. Format is YYYY-MM-DD. 44339
sessionId String Unique identifier for the session used for this request 7f6de02a-0061-403f-bd65-47d4b5f72c87
amountPaid String (Number) Amount paid by the user in rupees (INR). This is applicable for billers where there is no bill generated, eg. Fastag. Will be null for this event. 601.75
amount null
event String Name of the event to identify this user event bill_collection_failure

bill_payment_refunded — Notification when bill-payment has to be refunded.

This event is invoked when bill-payment request to BBPS has failed, after collection of funds from the user.

Sample payload
{
"txnId":"AXO101557980",
"mobileNumber":"9481773053",
"status":"PAYMENT_REFUNDED",
"billId":"dfeeaf14-e43a-4196-90d0-41089e979ad5",
"billerId":"MAHI00000NATIC",
"billerName":"Mahindra Rural Housing Finance Ltd",
"billerCategory":"Loan-Repayment",
"sessionId":"7f6de02a-0061-403f-bd65-47d4b5f72c87",
"billAmount":"105.0",
"dueDate":"2021-05-23",
"orderId":"H001234566666",
"amountPaid":"601.00",
"event":"bill_payment_refunded"
}

Parameter Data Type Description Example
txnId String Unique identifier for the transaction generated by COU. AX0101557980
mobileNumber String (Number) Mobile number used to generate the bill-payment request 9481773053
status String Status of the bill-payment request PAYMENT_REFUNDED
billId String Unique identifier for the bill. It is generated by the biller. Also called as billNumber dfeeaf14-e43a-4196-90d0-41089e979ad5
billerId String Unique identifier (Biller ID in BBPS) allocated to the Biller MAHI00000NATIC
billerName String Name of the biller as registered with BBPS Mahindra Rural Housing Finance Ltd
billerCategory String Category of the biller as registered with BBPS. There are more than 25 biller categories. Loan-Repayment
sessionId String Unique identifier for the session used for this request 7f6de02a-0061-403f-bd65-47d4b5f72c87
billAmount String (Number) Amount of the bill in rupees (INR) 601.75
dueDate String (Date) Due date of the bill. Format is YYYY-MM-DD. 44339
orderId String Unique identifier for a payment request. Generated by (website name). H001234566666
amountPaid String (Number) Amount paid by the user in rupees (INR). This is applicable for billers where there is no bill generated, eg. Fastag 601.75
event String Status to identify this user event bill_payment_refunded

dispute_raised — Notification when dispute/complaint is raised from the user

Sample payload
{
"txnId":"AXO198058515",
"txnDate":"2021-06-24",
"issueType":"1",
"description":"What the customer tells the issue is",
"mobileNumber":"8971302465",
"referenceId":"ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24",
"status":"submitted",
"event":"dispute_raised"
}

Parameter Data Type Description Example
txnId String Unique identifier for the transaction generated by COU, here (website name). Also known as BBPS transaction ID. AX0198058515
txnDate String (Date) Date of the transaction. Format is YYYY-MM-DD. 44371
issueType String 1
description String Description as entered by the user. Message entered by the user
mobileNumber String (Number) Mobile number used to generate the dispute 8971302465
referenceId String Unique identifer for the dispute raised, generated by (website name). ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24
status String Status of the dispute submitted
event String Status to identify this user event dispute_raised

dispute_status_change — Notification when the status of a dispute has changed

Sample payload
{
"txnId":"AXO198058515",
"txnDate":"2021-06-24",
"issueType":"1",
"description":"What the customer tells the issue is",
"mobileNumber":"8971302465",
"referenceId":"ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24",
"status":"closed/unknown",
"event":"dispute_status_change"
}

Parameter Data Type Description Example
txnId String Unique identifier for the transaction generated by COU, here (website name). Also known as BBPS transaction ID. AX0198058515
txnDate String (Date) Date of the transaction. Format is YYYY-MM-DD. 44371
issueType String 1
description String Description as entered by the user. Message entered by the user
mobileNumber String (Number) Mobile number used to generate the dispute 8971302465
referenceId String Unique identifer for the dispute raised, generated by (website name). ksyTnYVLor/YQ6IRBxzbYp88LuknxVT/2021-06-24
status String Status of the dispute closed/unknown
event String Status to identify this user event dispute_status_change

Was this page helpful?

(Website Name) Collect for Business - White label solution


Base URL

https://qa-coudc.(Website Name).co/api/v1

Authentication

OAuth 2.0 - bbps

Description

Enable easy BBPS bill payments in your App

Request

https://qa-coudc.(Website Name).co/api/v1/customPaymentResponse

Custom payment webhook API


Request

Body

paymentStatus

string

Required

transactionId

string

Required

amount

string

Required

orderId

string

Required

paymentDateTime

string

Required

paymentMode

string

Required

Response

Body

200 OK

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://qa-coudc.(Website Name).co/api/v1/customPaymentResponse \
--header 'content-type: application/json'\
--data '{
"paymentStatus": "SUCCESS",
"transactionId": "ORDID12345",
"amount": "SUCCESS",
"orderId": "ORDID12345",
"paymentDateTime": "ORDID12345",
"paymentMode": "ORDID12345"
}'
200 OK

Response sample


{}

Request

https://qa-coudc.(website name).co/api/v1/health

Health check


Request

Header parameters

maintaince

boolean

Response

Body

version

string

Required

environment

string

Required

server

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request GET \
--url https://qa-coudc.(website name).co/api/v1/health \
--header 'maintaince: SOME_BOOLEAN_VALUE'
200 Ok

Response sample


{
"version":"db42717a829da9d3061e4f409f3c0ee9935b72a5",
"environment":"PROD",
"server":"mistborn"
}

Request

https://qa-coudc.(website name).co/api/v1/ethereal/link

WL link create request API


Request

Security

OAuth 2.0 - bbps

Header parameters

X-PARTNER-ID

integer

Required

Partner ID


Body

categoryName

string

mobileNumber

string

orgId

string

Required

redirectTo

string

billParams

array

billerId

string

Response

Body

link

string

sessionId

string

success

boolean

Required

traceId

string

Required

Language

curl

Node

Python

Go

Request sample


curl --request POST \
--url https://qa-coudc.*(website name).co/api/v1/ethereal/link \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'\
--header 'X-PARTNER-ID: SOME_INTEGER_VALUE'\
--header 'content-type: application/json'\
--data '{
"categoryName": "9082718673",
"mobileNumber": "9082718673",
"orgId": 122337203685477,
"redirectTo": "9082718673",
"billParams": [
{
"name": "Loan Number",
"value": "1895159"
}
],
"billerId": "9082718673"
}'
200 OK

Response sample


{
"link":"link",
"sessionId":"sessionId",
"success":true,
"traceId":"C3SFG0O6N88R6UI7EQ"
}