Objects

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

State and City mapping

Click here &#8599 for State and City Biller Coverage Mapping

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
`Error`	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
`Any`	Any exactness

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`	Setu 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

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' Setu 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`	Setu 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`
coverage	`string`	BBPS coverage. Used to search billers having a specific coverage area
country	`string`	BBPS Country Code. Used to search billers operating in a certain country
state	`string`	BBPS state code. Used to search billers operating in a certain state
city	`string`	city name, used to search billers operating in a certain city
updatedSince	`date-time`	Fetch billers updated on or after the provided timestamp
tags	`string`
paymentChannel	Payment Channel`[]`
paymentMode	Payment Mode`[]`

Response

parameter	type	description
categoryName	`string`	Biller Category
city	`string`	Biller City
country	`string`	Biller Country
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 Modified 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.
enforcesSameDayFetchPay	`bool`	Whether the biller requires bill payment to be on the same calendar day as bill fetch.
bbpsUpdateTimestamp	`date-time`	Last updated date-time of the Biller accurate to the nearest day.

Dispute Request

/bills/dispute/request

Request Body

parameter	type	description
txnReferenceId	`string`	Setu 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

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

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`	Setu 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.

On this page