#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 ↗ 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 |
| selectedPaymentOptions | Selected Payment Option[] | Array of selected payment options |
#Payment Bill
The Payment Bill object contains information about a specific bill to be paid.
| Parameter | Type | Description |
|---|
billNumber | string | Unique identifier for the bill |
amount | integer | Amount to be paid for the bill in paise |
#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 |
#Biller Selection Type
| type | description |
|---|
SINGLE | User can pay only one bill from the fetch response |
MULTIPLE | User can pay any combination of bills from the fetch response |
ALL | User must pay all bills in the fetch response |
#Biller Response Type
| type | description |
|---|
SINGLE | Biller returns a single bill in the fetch response |
LIST | Biller returns multiple bills in the fetch response |
SELECTIVE | Biller returns bills based on specific criteria |
#Fetched Bill
| 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. |
| label | string | Additional label for the bill |
| minAmount | integer | Minimum amount that can be paid for this bill in paise |
| maxAmount | integer | Maximum amount that can be paid for this bill in paise |
| amountMultiple | integer | Bill payment amount should be multiple of this value in paise |
| paymentOptions | Payment Option[] | Array of payment options available for this bill |
#Payment Option
| Parameter | Type | Description |
|---|
| name | string | The display name of the option |
| amount | integer | The amount that can be paid for this option in paise |
| minAmount | integer | The minimum amount that can be paid for this option in paise |
| maxAmount | integer | The maximum amount that can be paid for this option in paise |
| amountMultiple | integer | The payment amount should be a multiple of this value in paise |
#Selected Payment Option
| Parameter | Type | Description |
|---|
| name | string | The display name of the option from bill fetch |
| amount | integer | The amount being paid for this option in paise |
#Exactness
Limits on acceptable payment amounts set by the biller.
| type | description |
|---|
Exact | Only the exact amount specified in fetched bill can be paid |
Exact and below | Amount specified in fetched bill or less can be paid |
Exact and above | Amount specified in fetched bill or more can be paid |
Any | Any amount can be paid |
RANGE | Amount within specified minAmount and maxAmount specified in fetched bill can be paid |
#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 |
| 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 |
| bills | Payment Bill[] | Details of bills paid |
| 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. |
| responseType | Biller Response Type | Indicates how the biller provides bill information in the fetch response |
| selectionType | Biller Selection Type | Specifies how users can select bills for payment (only applicable for LIST response type) |
#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 | Fetched Bill | Single fetched bill. Used when billerResponseType is 'SINGLE'. |
| bills | Fetched Bill[] | Array of fetched bills. Used when billerResponseType is 'LIST'. |
| 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 |
| billerResponseType | Biller Response Type | Indicates whether the biller provides a single bill ('SINGLE') or multiple bills ('LIST') |
| billerSelectionType | Biller Selection Type | Specifies how users can select bills for payment (only applicable for LIST response type) |
Note: The billerResponseType field indicates which bill data field to use. For 'SINGLE' type, use the bill field (contains zero or one bill). For 'LIST' type, use the bills field (contains one or more bills in an array).
#Payment Request
/bills/payment/request
#Request Body
| parameter | type | description |
|---|
| refId | string | BBPS Reference ID from previous bill fetch request. Mandatory for non-adhoc payments. |
| agent | Agent | Details of agent processing the payment. Mandatory for adhoc payments. |
| biller | Biller | Details of biller receiving the payment. Mandatory for adhoc payments. |
| customer | Customer | Details of the customer making the payment. Mandatory for adhoc payments. |
| bills | Payment Bill[] | Details of bills to be paid. Mandatory for LIST billers only. |
| paymentDetails | Payment Details | Details specific to the payment being made. Mandatory for all payments. |
Note:
- For non-adhoc payments, only
refId, paymentDetails, and potentially bills (for LIST billers) are required. - For adhoc payments,
agent, biller, customer, and paymentDetails are mandatory. refId and bills are not applicable.
#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. |
| bills | Payment Bill[] | Details of bills paid. Present for LIST billers only. |
