BBPS API SPECIFICATIONS Version 13.0 Date: 05.11.2019 Abstract This document contains information pertaining to different APIs used in BBPS and some considerations which will be beneficial while designing the same. 1 Table of Contents Document History ............................................................................................................................................................. 5 1 2 3 4 Bill Fetch Request & Response .................................................................................................................................. 6 1.1 Sample Fetch Request API: Customer BBPOU to BBPCU .................................................................................. 6 1.2 Sample Fetch Request API: BBPCU to Biller BBPOU.......................................................................................... 7 1.3 Sample Fetch Response API: Biller BBPOU to BBPCU ....................................................................................... 7 1.4 Sample Fetch Response API: BBPCU to Customer BBPOU ................................................................................ 8 1.5 Bill Fetch Request Tag Details ........................................................................................................................... 9 1.6 Bill Fetch Request XSD..................................................................................................................................... 10 1.7 Bill Fetch Response Tag Details ....................................................................................................................... 10 1.8 Bill Fetch Response XSD .................................................................................................................................. 11 Bill Payment Request & Response .......................................................................................................................... 12 2.1 Sample Payment Request API: Customer BBPOU to BBPCU........................................................................... 12 2.2 Sample Payment Request API: BBPCU to Biller BBPOU .................................................................................. 13 2.3 Sample Payment Response API: Biller BBPOU to BBPCU ................................................................................ 15 2.4 Sample Payment Response API: BBPCU to Customer BBPOU ........................................................................ 15 2.5 Sample Reversal Request API: BBPCU to Biller BBPOU ................................................................................... 15 2.6 Sample Reversal Response API: Biller BBPOU to BBPCU ................................................................................ 16 2.7 Sample Reversal Response API: BBPCU to Customer BBPOU ......................................................................... 16 2.8 Bill Payment Request Tag Details .................................................................................................................... 16 2.9 Bill Payment Request XSD ............................................................................................................................... 18 2.10 Bill Payment Response Tag Details.................................................................................................................. 19 2.11 Bill Payment Response XSD ............................................................................................................................. 20 Transaction Status Check (402) API Request & Response (for Pending Transactions) ........................................... 21 3.1 402 API Request: BBPCU to Biller BBPOU ....................................................................................................... 21 3.2 402 API Response: Biller BBPOU to BBPCU ..................................................................................................... 21 3.3 402 API Request Tag Details ............................................................................................................................ 21 3.4 402 API Request XSD ....................................................................................................................................... 22 3.5 402 API Response Tag Details ......................................................................................................................... 22 3.6 402 API Response XSD ..................................................................................................................................... 23 Bill Validation Request & Response ........................................................................................................................ 24 4.1 Sample Validation Request API: Customer BBPOU to BBPCU......................................................................... 24 4.2 Sample Validation Request API: BBPCU to Biller BBPOU ................................................................................ 24 4.3 Sample Validation Response API: Biller BBPOU to BBPCU .............................................................................. 24 4.4 Sample Validation Response API: BBPCU to Customer BBPOU ...................................................................... 25 BBPS API SPECIFICATIONS | Version 13.0 2 5 6 7 4.5 Bill Validation Request Tag Details .................................................................................................................. 25 4.6 Bill Validation Request XSD ............................................................................................................................. 26 4.7 Bill Validation Response Tag Details ............................................................................................................... 26 4.8 Bill Validation Response XSD ........................................................................................................................... 27 Diagnostic Request & Response .............................................................................................................................. 28 5.1 Sample Request API: BBPOU to BBPCU........................................................................................................... 28 5.2 Sample Response API: BBPCU to BBPOU ........................................................................................................ 28 5.3 Diagnostic Request Tag Details ....................................................................................................................... 28 5.4 Diagnostic Request XSD................................................................................................................................... 28 5.5 Diagnostic Response Tag Details ..................................................................................................................... 29 5.6 Diagnostic Response XSD ................................................................................................................................ 29 Transaction Status and Complaint Related API Request & Response..................................................................... 30 6.1 Sample Transaction Status (401) Request API – Using Mobile Number & Date Range: BBPOU to BBPCU .... 30 6.2 Sample Transaction Status (401) Response API – Using Mobile Number & Date Range: BBPCU to BBPOU .. 30 6.3 Sample Transaction Status (401) Request API – Using Transaction Ref ID: BBPOU to BBPCU ....................... 30 6.4 Sample Transaction Status (401) Response API – Using Transaction Ref ID: BBPCU to BBPOU ..................... 31 6.5 Sample Complaint Raise (501) Request API – Transaction Based: BBPOU to BBPCU ..................................... 31 6.6 Sample Complaint Raise (501) Response API – Transaction Based: BBPCU to BBPOU................................... 31 6.7 Sample Complaint Raise (501) Request API – Service Based against Agent: BBPOU to BBPCU ..................... 32 6.8 Sample Complaint Raise (501) Response API – Service Based against Agent: BBPCU to BBPOU ................... 32 6.9 Sample Complaint Raise (501) Request API – Service Based against Biller: BBPOU to BBPCU ...................... 32 6.10 Sample Complaint Raise (501) Response API – Service Based against Biller: BBPCU to BBPOU .................... 32 6.11 Sample Transaction Based Complaint Re-assignment (502) Request API: Customer BBPOU to BBPCU ........ 33 6.12 Sample Transaction Based Complaint Re-assignment (502) Response API: BBPCU to Customer BBPOU ..... 33 6.13 Sample Complaint Status (506) Request API: BBPOU to BBPCU ..................................................................... 33 6.14 Sample Complaint Status (506) Response API: BBPCU to BBPOU .................................................................. 33 6.15 Sample Complaint Closure (507) Request API: BBPOU to BBPCU................................................................... 34 6.16 Sample Complaint Closure (507) Response API: BBPCU to BBPOU ................................................................ 34 6.17 Transaction Status and Complaint Related API Request Tag Details .............................................................. 34 6.18 Transaction Status and Complaint Related API Request XSD ......................................................................... 35 6.19 Transaction Status and Complaint Related API Response Tag Details ............................................................ 36 6.20 Transaction Status and Complaint Related API Response XSD ....................................................................... 37 Biller MDM Fetch Request & Response .................................................................................................................. 39 7.1 Sample Request API: BBPOU to BBPCU........................................................................................................... 39 7.2 Sample Response API: BBPCU to BBPOU ........................................................................................................ 39 7.3 Biller MDM Fetch Request Tag Details ............................................................................................................ 45 BBPS API SPECIFICATIONS | Version 13.0 3 7.4 Biller MDM Fetch Request XSD ....................................................................................................................... 45 7.5 Biller MDM Fetch Response Tag Details ......................................................................................................... 46 7.6 Biller MDM Fetch Response XSD ..................................................................................................................... 49 8 Agent MDM Fetch Request & Response ................................................................................................................. 53 8.1 Sample Request API: BBPOU to BBPCU........................................................................................................... 53 8.2 Sample Response API: BBPCU to BBPOU ........................................................................................................ 53 8.3 Agent MDM Fetch Request Tag Details .......................................................................................................... 55 8.4 Agent MDM Fetch Request XSD ...................................................................................................................... 55 8.5 Agent MDM Fetch Response Tag Details ........................................................................................................ 56 8.6 Agent MDM Fetch Response XSD ................................................................................................................... 57 9 Acknowledgment .................................................................................................................................................... 59 9.1 Sample ACK for Fetch & Payment APIs ........................................................................................................... 59 9.2 Sample ACK for Other APIs.............................................................................................................................. 59 9.3 Acknowledgment Tag Details .......................................................................................................................... 59 9.4 Acknowledgment XSD ..................................................................................................................................... 59 10 10.1 BBPS Common ..................................................................................................................................................... 61 BBPS Common XSD.......................................................................................................................................... 61 11 Key Exchange / XML signing ................................................................................................................................ 66 12 URLs for Different API Messages ......................................................................................................................... 67 12.1 Request URL format (Customer BBPOU to BBPCU): ....................................................................................... 67 12.2 Request URL format (BBPCU to Biller BBPOU): ............................................................................................... 67 12.3 Response URL format (Biller BBPOU to BBPCU): ............................................................................................ 67 12.4 Response URL format (BBPCU to Customer BBPOU): ..................................................................................... 67 12.5 Request URL format (BBPOU to BBPCU): ........................................................................................................ 67 12.6 Response URL format (BBPCU to BBPOU):...................................................................................................... 68 13 Error Codes and Declines .................................................................................................................................... 69 13.1 BBPCU Declines ............................................................................................................................................... 69 13.2 Biller BBPOU Declines ..................................................................................................................................... 74 13.3 Customer BBPOU Declines .............................................................................................................................. 75 13.4 Forced Closure of Transactions by CU............................................................................................................. 76 14 Re-utilization of Fetch / Validation for Registered Customers ........................................................................... 78 14.1 Considerations for Customer OUs................................................................................................................... 78 14.2 Considerations for Biller OUs .......................................................................................................................... 79 15 CMS Response Scenarios..................................................................................................................................... 80 16 Biller Types in BBPS ............................................................................................................................................. 82 17 Amount Block Configuration in Bill Fetch & Bill Payment Messages .................................................................. 83 BBPS API SPECIFICATIONS | Version 13.0 4 18 Fee Configuration ................................................................................................................................................ 87 18.1 Interchange Fee............................................................................................................................................... 87 18.2 Interchange Fee Config ................................................................................................................................... 88 19 BBPS IDs............................................................................................................................................................... 90 19.1 ID Generation Stages....................................................................................................................................... 90 19.2 Generation Logic ............................................................................................................................................. 91 20 Payment Mode & Channel Details ...................................................................................................................... 92 20.1 Initiating Channel Vs Device Block Parameters............................................................................................... 92 20.2 Payment Mode Vs Payment Info Parameters ................................................................................................. 92 20.3 Initiating Channel Vs Payment Mode Combinations ...................................................................................... 93 21 Settlement File Transfer Mechanism .................................................................................................................. 94 22 Elements Description .......................................................................................................................................... 95 23 Appendix ........................................................................................................................................................... 133 23.1 List of Error Messages ................................................................................................................................... 133 23.2 File Naming Convention for Settlement Files ............................................................................................... 133 BBPS API SPECIFICATIONS | Version 13.0 5 Document History Date Version 29.12.2016 08.02.2018 11.0 12.0 Section Number - 05.11.2019 13.0 - Description Base version of API Specifications  Merging of API Request and Response pairs  Split of Bill Fetch and Bill Payment Request messages from Customer BBPOU to BBPCU to Biller BBPOU  Split of Bill Fetch and Bill Payment Response messages from Biller BBPOU to BBPCU to Customer BBPOU  Separate Reversal Request and Reversal Response sample messages  Addition of Bill Validation API  Addition of Complaint Re-assignment (502) and Complaint Closure (507) APIs  Split of CMS API into Transaction Status (401), Compliant Raise (501), Complaint Re-assignment (502), Complaint Status (506) and Complaint Closure (507) APIs  Modification of Biller MDM Fetch API  Addition of Agent MDM Fetch API  Addition of Error Codes and Declines section  Addition of CMS Response Scenarios section  Addition of Biller Types in BBPS section  Addition of Amount Block Configuration in Bill Fetch & Bill Payment Messages section  Addition of Fee Configuration section  Addition of Settlement File Transfer Mechanism section  Modification of Payment Mode & Channel Details section - Splitting of Mobile and Internet payment channels: Mobile (Pre-login), Mobile Banking (Post-login), Internet (Pre-login), Internet Banking (Postlogin) - Addition of 2 payment channels: Agent and Business Correspondent - Addition of 2 payment mode: AEPS and Account Transfer  Modification of parameter definitions in Elements Description section  Addition of Appendix section  Addition of Transaction Status Check (402) API between BBPCU and Biller BBPOU to check the status of Pending Transactions  Introduction of Fetch / Validation Re-utilization for Registered Customers - Introduction of siTxn and origRefId attributes in Payment Request API - Considerations for Customer and Biller BBPOUs  Modification of Biller MDM Fetch API - Introduction of Either/OR configuration of Customer Parameters - Passing default(possible) values against a Customer Parameter  Modification of BillerResponse block attributes presence in Fetch, Payment and 402 API Responses.  Change in Transaction Reference Id length and generation logic  Change in Customer Mobile Number length  Addition of URLs for Different APIs section  Modification of BBPS Error Codes and Declines - Introduction of Deemed Success and Pending Status - Modification of Forced Closure of Transactions by CU  Modification of Biller Types in BBPS section  Modification of Fee Configuration section  Modification of Payment Mode & Channel Details section - Addition of 2 payment modes: Bharat QR and USSD  Modification of parameter definitions in Elements Description section BBPS API SPECIFICATIONS | Version 13.0 6 1 Bill Fetch Request & Response 1.1 Sample Fetch Request API: Customer BBPOU to BBPCU BBPS API SPECIFICATIONS | Version 13.0 7 1.2 Sample Fetch Request API: BBPCU to Biller BBPOU 1.3 Sample Fetch Response API: Biller BBPOU to BBPCU BBPS API SPECIFICATIONS | Version 13.0 8 1.4 Sample Fetch Response API: BBPCU to Customer BBPOU BBPS API SPECIFICATIONS | Version 13.0 9 1.5 Bill Fetch Request Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 XML Element xmlns ver ts 2.1.3 origInst 2.1.4 refId 3.1 3.2 3.2.1 3.2.2 4.1 name value 4.1.1 ts 4.1.2 msgId 4.2 4.3 4.3.1 4.3.2 4.3.3 provider type value 5.1 5.1.1 5.2 5.2.1 5.2.2 6.1 6.1.1 6.2 6.3 6.3.1 6.3.2 7.1 7.2 7.2.1 7.3 mobile name value Id name value Id name value Name of the reference field as configured for the Biller Value of the reference field which uniquely identifies the customer for the Biller 1..n 1..n 1.6 Bill Fetch Request XSD BBPS Bill Request 1.7 Bill Fetch Response Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 XML Element xmlns Ver ts 2.1.3 origInst 2.1.4 refId 3.1 3.1.1 approvalRefNum 3.1.2 responseCode 3.1.3 responseReason 3.1.4 complianceRespCd 3.1.5 complianceReason Description API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages Response details of the transaction Internal reference number which may be used by the Biller BBPOU for a transaction – default value "AB123456" Carries the response code indicating success or failure of the transaction Description of the response code – possible values are "Successful" or "Failure" Carries the compliance code indicating the reason for a failed transaction – not required for a successful transaction Description of the compliance code – not required for a successful transaction Occurrence 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 0..1 0..1 BBPS API SPECIFICATIONS | Version 13.0 11 4.1 4.1.1 ts 4.1.2 msgId 5.1 5.2 5.3.1 5.3.2 name value 6.1 6.1.1 6.1.2 6.1.3 6.1.4 6.1.5 6.1.6 6.2 customerName amount dueDate billDate billNumber billPeriod 6.2.1 6.2.2 7.1 name value 7.2 7.2.1 7.2.2 name value 5.3 Transaction information, passed throughout the system, visible to all entities of the eco-system Transaction initiation timestamp which will remain constant throughout all legs of the request and response message Unique identification assigned by the initiating BBPOU for chaining a request and response message Bill related details to identify a Customer Customer bill fetch related details 1..1 Customer bill fetch related reference field tag 1..n Name of the reference field as configured for the Biller Value of the reference field which uniquely identifies the Customer for the Biller Response which is sent by the Biller for a successful transaction, i.e., response code is ‘000’ Name of the Customer Amount of the bill Due date of the bill Generation date of the bill Unique identifier of the bill Billing period of the bill Biller response related tag indicating the various amount options provided by the Biller Name of the amount field assigned by the Biller Value of the amount field Additional information parameters provided by the Biller for a successful transaction, i.e., response code is ‘000’ Tag indicating any additional information provided by the Biller Name of the field assigned by the Biller Value of the field 1..n 1..n 1..1 1..1 0..1 1..1 0..1 0..1* 1..1 0..1* 0..1* 0..1* 0..1* 0..n 1..n 1..n 0..1 1..n 1..n 1..n *For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY. 1.8 Bill Fetch Response XSD BBPS Bill Fetch Response BBPS API SPECIFICATIONS | Version 13.0 12 2 Bill Payment Request & Response 2.1 Sample Payment Request API: Customer BBPOU to BBPCU BBPS API SPECIFICATIONS | Version 13.0 13 10000 2.2 Sample Payment Request API: BBPCU to Biller BBPOU BBPS API SPECIFICATIONS | Version 13.0 14 10000 BBPS API SPECIFICATIONS | Version 13.0 15 2.3 Sample Payment Response API: Biller BBPOU to BBPCU 2.4 Sample Payment Response API: BBPCU to Customer BBPOU 2.5 Sample Reversal Request API: BBPCU to Biller BBPOU BBPS API SPECIFICATIONS | Version 13.0 16 2.6 Sample Reversal Response API: Biller BBPOU to BBPCU 2.7 Sample Reversal Response API: BBPCU to Customer BBPOU 2.8 Bill Payment Request Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 XML Element xmlns ver ts 2.1.3 origInst 2.1.4 refId 3.1 3.2 3.2.1 3.2.2 4.1 name value Description Occurrence 1..1 API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages Meta data primarily for analytics Meta data primarily for analytics Name of the tag which is defined Value of the tag Transaction information, passed throughout the system, visible to 1..1 1..1 1..1 1..1 1..1 1..1 0..1 1..n 1..n 1..n 1..1 BBPS API SPECIFICATIONS | Version 13.0 17 4.1.1 ts 4.1.2 msgId 4.1.3 4.1.4 type txnReferenceId 4.2 4.3 4.3.1 4.3.2 4.3.3 provider type value 5.1 5.1.1 5.2 5.2.1 5.2.2 6.1 6.1.1 6.2 6.3 6.3.1 6.3.2 7.1 7.2 7.2.1 7.3 7.4.1 7.4.2 mobile name value id name value id name value 8.1 8.1.1 8.1.2 8.1.3 8.1.4 8.1.5 8.1.6 8.2 customerName amount dueDate billDate billNumber billPeriod 8.2.1 8.2.2 9.1 name value 9.2 9.2.1 9.2.2 name value 7.4 all entities of the eco-system Transaction initiation timestamp which will remain constant throughout all legs of the transaction Unique identification assigned by the initiating BBPOU for chaining a request and response message Type of the message (Forward or Reversal Type) Transaction reference number used by the Customer for referring to a Payment transaction Risk evaluation associated with the transaction and the related parties in the transaction Risk score related to the transaction and the entities Entity providing the risk score Type of risk Value of risk evaluation ranging from "000" (No Risk) to "100" (Maximum Risk) with default score being "030" Details of the Customer viewing / paying the bill Customer mobile number Customer related details Name of the specific data requested from Customer Value of the specific data requested from Customer Agent related data Unique identification code allocated to the Agent Details of Device from which the transaction was initiated Device Tag Name of the device which is used for transaction initiation Unique code or value assigned to the device Biller ID and bill related details to identify a Customer Biller related details Unique identification code allocated to the Biller Customer bill fetch related details 1..1 1..1 1..1 1..1 1..1 1..n 1..n 1..n 1..n 1..1 1..1 0..n 1..n 1..n 1..1 1..1 1..1 1..n 1..n 1..n 1..1 1..1 1..1 1..1 Customer bill fetch related reference field tag 1..n Name of the reference field as configured for the Biller Value of the reference field which uniquely identifies the customer for the Biller Biller response parameters sent by the Biller supporting fetch is copied in the payment request "as-is" – not applicable for payment only Billers Name of the customer Amount of the bill Due date of the bill Generation date of the bill Unique identifier of the bill Billing period of the bill Biller response related tag indicating the various amount options provided by the Biller Name of the amount field assigned by the Biller Value of the amount field Additional information parameters sent by the Biller supporting fetch is copied in the payment request "as-is" – not applicable for payment only Billers Tag indicating any additional information provided by the Biller Name of the field assigned by the Biller Value of the field 1..n 1..n 0..1 0..1* 1..1 0..1* 0..1* 0..1* 0..1* 0..n 1..n 1..n 0..1 1..n 1..n 1..n BBPS API SPECIFICATIONS | Version 13.0 18 10.1 10.1.1 10.1.2 10.1.3 10.1.4 11.1 11.2 11.2.1 11.2.2 quickPay splitPay OFFUSPay paymentMode amount custConvFee 11.2.3 COUcustConvFee 11.2.4 11.3 11.4 currency 11.4.1 11.4.2 12.1 name value 12.2 name value 12.2.1 12.2.2 Payment method opted by the Customer Flag indicating if the payment is initiated without a fetch or not Flag indicating if the bill is paid using two different payment modes Flag indicating if it is an electronic ON-US or OFF-US transaction The payment mode which is accepted from the Customer Amount related details for the payment Details of the bill payment amount made by the Customer Actual amount paid by the Customer for the transaction Customer convenience fee (CCF1) paid by the Customer BBPOU to Biller BBPOU Customer convenience fee (CCF2) paid by the Customer to Customer BBPOU Currency code of the transaction Amount paid through the second payment mode 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 Amount paid by the customer indicating different amount option combinations Name of the amount field assigned by the Biller Value of the amount field Payment information of the instrument which is used for making the bill payment (this block is not passed by BBPCU to Biller BBPOU) Payment instrument details which is used for the bill payment transaction Name of the parameter for the chosen payment instrument Value of the parameter for the chosen payment instrument 0..n 1..1 1..1 0..1 1..n 1..n 1..1 1..n 1..n 1..n *For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY. 2.9 Bill Payment Request XSD BBPS Bill Payment Request BBPS API SPECIFICATIONS | Version 13.0 19 2.10 Bill Payment Response Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 2.1.3 2.1.4 XML Element xmlns ver ts origInst refId 3.1 3.1.1 approvalRefNum 3.1.2 responseCode 3.1.3 responseReason 3.1.4 complianceRespCd 3.1.5 complianceReason 4.1 4.1.1 ts 4.1.2 msgId 5.1 5.2 5.3.1 5.3.2 name value 6.1 6.1.1 6.1.2 customerName amount 6.1.3 6.1.4 6.1.5 6.1.6 6.1.7 dueDate billDate billNumber billPeriod custConvFee 5.3 Description Occurrence 1..1 API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages Response details of the transaction Internal reference number which may be used by the Biller BBPOU for a transaction – default value "AB123456" Carries the response code indicating success or failure of the transaction Description of the response code – possible values are "Successful" or "Failure" Carries the compliance code indicating the reason for a failed transaction – not required for a successful transaction Description of the compliance code – not required for a successful transaction Transaction information, passed throughout the system, visible to all entities of the eco-system Transaction initiation timestamp which will remain constant throughout all legs of the request and response message Unique identification assigned by the initiating BBPOU for chaining a request and response message Bill related details to identify a Customer Customer bill payment related details 1..1 1..1 1..1 1..1 1..1 1..1 Customer bill payment related reference field tag 1..n Name of the reference field as configured for the Biller Value of the reference field which uniquely identifies the Customer for the Biller Response which is sent by the Biller for a successful transaction, i.e., response code is ‘000’ Name of the Customer Amount of the bill – should match with the "amount" attribute value passed in the Payment request Due date of the bill Generation date of the bill Unique identifier of the bill Billing period of the bill Customer convenience fee paid by the Customer BBPOU to Biller BBPOU – should match with the CCF1 value in the Payment request 1..n 1..n 1..1 1..1 1..1 1..1 0..1 0..1 1..1 1..1 1..1 0..1 1..1 0..1 0..1* 1..1 0..1* 0..1* 0..1* 0..1* 0..1* *For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY. BBPS API SPECIFICATIONS | Version 13.0 20 2.11 Bill Payment Response XSD BBPS Bill Fetch Response BBPS API SPECIFICATIONS | Version 13.0 21 3 Transaction Status Check (402) API Request & Response (for Pending Transactions) 3.1 402 API Request: BBPCU to Biller BBPOU 3.2 402 API Response: Biller BBPOU to BBPCU 3.3 402 API Request Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 XML Element Xmlns Ver ts 2.1.3 2.1.4 origInst refId Description Occurrence 1..1 API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, 1..1 1..1 1..1 1..1 1..1 1..1 BBPS API SPECIFICATIONS | Version 13.0 22 3.1 3.1.1 3.1.2 4.1 4.1.1 ts xchangeId msgId 4.1.4 txnReferenceId unchanged, throughout the entire end-to-end chain, binding the Validation and Payment messages Transaction information, passed throughout the system, visible to all entities of the eco-system Transmission date and time of the transaction Identification of the type of the request – transaction status (402) Information pertaining to transaction status request Unique identification assigned by the initiating BBPOU for chaining a request and response message Transaction reference number used by the Customer for referring to a Payment transaction 1..1 1..1 1..1 1..1 1..1 0..1 3.4 402 API Request XSD 402 API Request 3.5 402 API Response Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 2.1.3 2.1.4 XML Element Xmlns Ver ts origInst refId 3.1 3.1.1 approvalRefNum Description API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages Response details of the transaction Internal reference number which may be used by the Biller BBPOU for a Occurrence 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 BBPS API SPECIFICATIONS | Version 13.0 23 3.1.2 3.1.3 responseCode responseReason 3.1.4 complianceRespCd 3.1.5 complianceReason 4.1 4.1.1 ts 4.1.2 msgId 4.1.3 5.1 5.2 5.3.1 5.3.2 xchangeId Name Value 6.1 6.1.1 6.1.2 customerName amount 6.1.3 6.1.4 6.1.5 6.1.6 6.1.7 dueDate billDate billNumber billPeriod custConvFee 5.3 transaction – default value "AB123456" Carries the response code indicating success or failure of the transaction Description of the response code – possible values are "Successful" or "Failure" Carries the compliance code indicating the reason for a failed transaction – not required for a successful transaction Description of the compliance code – not required for a successful transaction Transaction information, passed throughout the system, visible to all entities of the eco-system Transaction initiation timestamp which will remain constant throughout all legs of the request and response message Unique identification assigned by the initiating BBPOU for chaining a request and response message Identification of the type of the response – transaction status (402) Bill related details to identify a Customer Customer bill payment related details 1..1 1..1 0..1 0..1 1..1 1..1 1..1 0..1 0..1 1..1 Customer bill payment related reference field tag 1..n Name of the reference field as configured for the Biller Value of the reference field which uniquely identifies the Customer for the Biller Response which is sent by the Biller for a successful transaction, i.e., response code is ‘000’ Name of the Customer Amount of the bill – should match with the "amount" attribute value passed in the Payment request Due date of the bill Generation date of the bill Unique identifier of the bill Billing period of the bill Customer convenience fee paid by the Customer BBPOU to Biller BBPOU – should match with the CCF1 value in the Payment request 1..n 1..n 0..1 0..1* 1..1 0..1* 0..1* 0..1* 0..1* 0..1* *For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY. 3.6 402 API Response XSD 402 API Response BBPS API SPECIFICATIONS | Version 13.0 24 4 Bill Validation Request & Response 4.1 Sample Validation Request API: Customer BBPOU to BBPCU 4.2 Sample Validation Request API: BBPCU to Biller BBPOU 4.3 Sample Validation Response API: Biller BBPOU to BBPCU BBPS API SPECIFICATIONS | Version 13.0 25 4.4 Sample Validation Response API: BBPCU to Customer BBPOU 4.5 Bill Validation Request Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 XML Element Xmlns Ver ts 2.1.3 origInst 2.1.4 refId 3.1 3.1.1 4.1 4.2 4.2.1 4.3 Id Id name value 4.4 4.4.1 4.4.2 Description Occurrence 1..1 API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Validation and Payment messages Agent related data Unique identification code allocated to the Agent Biller ID and bill related details to identify a Customer Biller related details Unique identification code allocated to the Biller Customer bill validation related details 1..1 1..1 1..1 1..1 Customer bill validation related reference field tag 1..n Name of the reference field as configured for the Biller Value of the reference field which uniquely identifies the customer for the Biller 1..n 1..n 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 BBPS API SPECIFICATIONS | Version 13.0 26 4.6 Bill Validation Request XSD Bill Validation Request 4.7 Bill Validation Response Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 XML Element xmlns Ver ts 2.1.3 origInst 2.1.4 refId 3.1 3.1.1 approvalRefNum 3.1.2 responseCode 3.1.3 responseReason 3.1.4 complianceRespCd 5.1.5 complianceReason 6.1 6.2 6.2.1 6.2.2 name value Description Occurrence 1..1 API Name API schema namespace Header of the message Version of the API Creation timestamp of the message which will be updated at each leg Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain, binding the Fetch and Payment messages Response details of the transaction Internal reference number which may be used by the Biller BBPOU for a transaction – default value "AB123456" Carries the response code indicating success or failure of the transaction Description of the response code – possible values are "Successful" or "Failure" Carries the compliance code indicating the reason for a failed transaction – not required for a successful transaction Description of the compliance code – not required for a successful transaction Validation response parameters sent by the Biller for a successful transaction, i.e., response code is ‘000’ Additional Information related tag indicating the validation identifier provided by the Biller Name of the field assigned by the Biller Value of the field 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 0..1 0..1 0..1 1..n 1..n 1..n BBPS API SPECIFICATIONS | Version 13.0 27 4.8 Bill Validation Response XSD Bill Validation Response BBPS API SPECIFICATIONS | Version 13.0 28 5 Diagnostic Request & Response 5.1 Sample Request API: BBPOU to BBPCU 5.2 Sample Response API: BBPCU to BBPOU HED030 Head Timestamp gap between BBPCU and OU is more than acceptable tolerance. 5.3 Diagnostic Request Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 2.1.3 XML Element xmlns Ver ts origInst 2.1.4 refId Description API Name API schema namespace Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Occurrence 1..1 1..1 1..1 1..1 1..1 1..1 1..1 5.4 Diagnostic Request XSD BBPS Diagnostic Request BBPS API SPECIFICATIONS | Version 13.0 29 5.5 Diagnostic Response Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 2.1.3 XML Element xmlns ver ts origInst 2.1.4 refId 3.1 3.2 3.3 Description API Name API schema namespace Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Error messages in the API message Error Code for API message Occurrence 1..1 1..1 1..1 1..1 1..1 1..1 Error Reason for the API message 1..n 1..1 0..1 1..n 5.6 Diagnostic Response XSD BBPS Diagnostic Response BBPS API SPECIFICATIONS | Version 13.0 30 6 Transaction Status and Complaint Related API Request & Response 6.1 Sample Transaction Status (401) Request API – Using Mobile Number & Date Range: BBPOU to BBPCU 6.2 Sample Transaction Status (401) Response API – Using Mobile Number & Date Range: BBPCU to BBPOU 6.3 Sample Transaction Status (401) Request API – Using Transaction Ref ID: BBPOU to BBPCU BBPS API SPECIFICATIONS | Version 13.0 31 6.4 Sample Transaction Status (401) Response API – Using Transaction Ref ID: BBPCU to BBPOU 6.5 Sample Complaint Raise (501) Request API – Transaction Based: BBPOU to BBPCU 6.6 Sample Complaint Raise (501) Response API – Transaction Based: BBPCU to BBPOU BBPS API SPECIFICATIONS | Version 13.0 32 6.7 Sample Complaint Raise (501) Request API – Service Based against Agent: BBPOU to BBPCU 6.8 Sample Complaint Raise (501) Response API – Service Based against Agent: BBPCU to BBPOU 6.9 Sample Complaint Raise (501) Request API – Service Based against Biller: BBPOU to BBPCU 6.10 Sample Complaint Raise (501) Response API – Service Based against Biller: BBPCU to BBPOU BBPS API SPECIFICATIONS | Version 13.0 33 6.11 Sample Transaction Based Complaint Re-assignment (502) Request API: Customer BBPOU to BBPCU 6.12 Sample Transaction Based Complaint Re-assignment (502) Response API: BBPCU to Customer BBPOU 6.13 Sample Complaint Status (506) Request API: BBPOU to BBPCU 6.14 Sample Complaint Status (506) Response API: BBPCU to BBPOU BBPS API SPECIFICATIONS | Version 13.0 34 6.15 Sample Complaint Closure (507) Request API: BBPOU to BBPCU 6.16 Sample Complaint Closure (507) Response API: BBPCU to BBPOU 6.17 Transaction Status and Complaint Related API Request Tag Details Index 1.1 1.1.1 2.1 2.1.1 2.1.2 2.1.3 XML Element xmlns ver ts origInst 2.1.4 refId 3.1 Description Occurrence 1..1 API Name API schema namespace Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Transaction information, passed throughout the system, visible to 1..1 1..1 1..1 1..1 1..1 1..1 1..1 BBPS API SPECIFICATIONS | Version 13.0 35 3.1.1 3.1.2 ts xchangeId 4.1 4.1.1 msgId 4.1.2 4.1.3 complaintType mobile 4.1.4 txnReferenceId 4.1.5 complaintId 4.1.6 4.1.7 4.1.8 disposition servReason description 4.1.9 4.1.10 participationType agentId 4.1.11 billerId 5.1 5.1.1 5.1.2 fromDate toDate all entities of the eco-system Transmission date and time of the transaction Identification of the type of the request – transaction status (401), complaint registration (501), complaint re-assignment (502), complaint status (506) or complaint closure (507) Information pertaining to transaction status and complaint related requests Unique identification assigned by the initiating BBPOU for chaining a request and response message Type of request – Transaction or Service based Mobile number against which the transaction status is to be searched Transaction reference number used by the Customer for referring to a Payment transaction Complaint ID generated by BBPCU to check the complaint status, re-assign or close a complaint subsequently Pre-defined list of dispositions for transaction based complaints Pre-defined list of dispositions for service based complaints Free text to provide additional information pertaining to the complaint Entity type for the service based complaints (AGENT / BILLER) Unique identifier (Agent ID in BBPS) allocated to the Agent for service based complaints Unique identifier (Biller ID in BBPS) allocated to the Biller for service based complaints Searching the transaction details on the basis of mobile number and date range – optional tag which helps in filtering the search process Start date for transaction search End date for transaction search 1..1 1..1 1..1 1..1 1..1 0..1 0..1 0..1 0..1 0..1 0..1 0..1 0..1 0..1 0..1 1..1 1..1 6.18 Transaction Status and Complaint Related API Request XSD BBPS API request BBPS API SPECIFICATIONS | Version 13.0 36 6.19 Transaction Status and Complaint Related API Response Tag Details Index 1.1 XML Element 1.1.1 2.1 2.1.1 2.1.2 2.1.3 xmlns Ver ts origInst 2.1.4 refId 3.1 3.1.1 3.1.2 ts xchangeId 4.1 4.1.1 msgId 4.1.2 responseCode 4.1.3 responseReason Description Occurrence API Name 1..1 API schema namespace Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Transaction information, passed throughout the system, visible to all entities of the eco-system Transmission date and time of the transaction Identification of the type of the request – transaction status (401), complaint registration (501), complaint re-assignment (502), complaint status (506) or complaint closure (507) Information pertaining to transaction status and complaint related responses Unique identification assigned by the initiating BBPOU for chaining a request and response message 1..1 1..1 1..1 1..1 1..1 Carries the response code indicating success or failure of the transaction Description of the response code 1..1 1..1 1..1 1..1 1..1 1..1 1..1 1..1 BBPS API SPECIFICATIONS | Version 13.0 37 4.1.4 complaintId 4.1.5 assigned 4.1.6 openComplaint 4.1.7 complaintStatus 4.1.8 remarks 4.2 4.3 Complaint ID generated by BBPCU to check the complaint status, re-assign or close a complaint subsequently BBPOU to which the complaint is assigned 0..1 Flag indicating if the transaction based complaint being raised is currently open in the system or not – "Y" will show the details for the complaint raised earlier Complaint status of the transaction 0..1 Last updated additional information provided by the BBPOU pertaining to the complaint and fetched in the complaint status check (506) response List of transactions against a particular search criteria 0..1 Record containing the details of a single transaction 1..n 0..1 0..1 0..1 4.3.1 txnReferenceId Transaction reference number used by the Customer for referring to a Payment transaction 1..1 4.3.2 amount Bill payment amount 1..1 4.3.3 txnDate Date of the transaction 1..1 4.3.4 agentId Agent ID of the Agent involved in the transaction 1..1 4.3.5 billerId Biller ID of the Biller involved in the transaction 1..1 4.3.6 txnStatus Status of the transaction – successful or failure 1..1 4.4 Details of the customer for a successful transaction search (401) response 0..1 4.4.1 mobile Mobile number linked to the transaction(s) 1..1 6.20 Transaction Status and Complaint Related API Response XSD BBPS API response BBPS API SPECIFICATIONS | Version 13.0 38 BBPS API SPECIFICATIONS | Version 13.0 39 7 Biller MDM Fetch Request & Response 7.1 Sample Request API: BBPOU to BBPCU OBNSTNS00NAT01 7.2 Sample Response API: BBPCU to BBPOU OBNSTNS00NAT01 BBPS Biller 1 Biller 1 DTH OFFLINEB true false Government IND NOT_SUPPORTED Exact NOT_SUPPORTED 2018-04-09 2099-12-31 Internet Banking 1 500000000 Yes Debit Card 1 BBPS API SPECIFICATIONS | Version 13.0 40 500000000 Yes Credit Card 1 500000000 Yes Prepaid Card 1 500000000 Yes IMPS 1 500000000 Yes Cash 4999900 1 No UPI 1 500000000 Yes Wallet 1 500000000 Yes NEFT 1 500000000 Yes AEPS 1 500000000 Yes BBPS API SPECIFICATIONS | Version 13.0 41 Account Transfer 1 500000000 Yes INT 1 500000000 Yes INTB 1 500000000 Yes MOB 1 500000000 Yes MOBB 1 500000000 Yes POS 1 500000000 Yes MPOS 1 500000000 Yes ATM 1 500000000 Yes BNKBRNCH 1 BBPS API SPECIFICATIONS | Version 13.0 42 500000000 No KIOSK 1 500000000 Yes AGT 1 500000000 No BSC 1 500000000 No CustParam1 NUMERIC true 3 3 ^[1-9]{3}$ 123,234,345,456,567,678,789 CustParam2 ALPHANUMERIC true 1 20 ^[A-Za-z]{1,20}$ Manoj Kumar,Manoj Chekuri CustParam3 NUMERIC true 1 10 CustParam4 NUMERIC true 1 BBPS API SPECIFICATIONS | Version 13.0 43 8 CustParam5 ALPHANUMERIC true 1 15 CustParam1 CustParam2 CustParam3 CustParam4 CustParam5 BASE_BILL_AMOUNT Early Payment Amount Late Payment Amount Early Payment Date ALPHANUMERIC false PAYMENT AGT 000 PBF CCF false 20180925 PAYMENT BSC 000 BBPS API SPECIFICATIONS | Version 13.0 44 PBF CCF false 20180925 PAYMENT BNKBRNCH 000 PBF CCF false 20180925 PAYMENT 000 EBF CCF true 20180925 PBF Physical Biller Fee B2C 999999999999999999 1 2.50 0 2018-09-25 EBF Electronic Biller Fee B2C 999999999999999999 1 1.50 0 2018-09-25 CCF Customer Convenience Fee BBPS API SPECIFICATIONS | Version 13.0 45 C2B 999999999999999999 1 0.00 0 2018-09-25 ACTIVE It takes 2 days to reflect the payment in your biller account. Yes Yes 120 7.3 Biller MDM Fetch Request Tag Details Index 1.1 XML Element Description Occurrence API Name 1..1 1.1.1 Xmlns API schema namespace 1..1 2.1 2.1.1 2.1.2 2.1.3 Ver ts origInst 1..1 1..1 1..1 1..1 2.1.4 refId 3.1 Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Tag for searching the Biller details associated or non-associated with the BBPOU initiating the request 3.1.1 mybiller Flag indicating request for the Biller details associated or nonassociated with the BBPOU initiating the request 1..1 4.1 Tag for searching the Biller details based on certain parameters 0..1 4.2 Biller ID for which the Biller details are requested 1..n 5.1 Tag for searching the Biller details based on time parameter 0..1 5.2 Request for Biller details for all the Billers updated in the system after the time provided 1..1 1..1 0..1 7.4 Biller MDM Fetch Request XSD BBPS API SPECIFICATIONS | Version 13.0 46 BBPS Biller Fetch Request 7.5 Biller MDM Fetch Response Tag Details Index 1.1 XML Element Description Occurrence API Name 1..1 1.1.1 Xmlns API schema namespace 1..1 2.1 2.1.1 2.1.2 2.1.3 Ver ts origInst 1..1 1..1 1..1 1..1 2.1.4 refId 3.1 Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain MDM details of the Biller 3.2 Identifier of the Biller 1..1 3.3 Name of the Biller 1..1 3.4 Alias name of the Biller 1..1 3.5 Biller category 1..1 Biller mode, i.e., Online, Offline A, Offline B 1..1 3.6 1..1 0..n BBPS API SPECIFICATIONS | Version 13.0 47 3.7 Flag indicating if the Biller accepts adhoc payment 1..1 3.8 Flag indicating if the Biller is a parent Biller 1..1 3.9 Identifier of the parent Biller 0..1 3.10 Biller ownership, i.e., Government, PSU, Private 1..1 3.11 Coverage of the Biller, i.e., National, State/UT, City/District 1..1 3.12 Indicates if the Biller allows Bill Fetch or not – possible values are MANDATORY, OPTIONAL, NOT_SUPPORTED 1..1 3.13 Indicates if the Biller allows Bill Validation or not – possible values are MANDATORY, OPTIONAL, NOT_SUPPORTED 1..1 3.14 0..1 3.15 Indicates if the Biller (having Mandatory Bill Fetch) allows exact payment or not – possible values are Exact, Exact and above, Exact and below Effective from date of the Biller 3.16 Effective to date of the Biller 1..1 3.17 Temporary deactivation start date of the Biller 1..1 3.18 Temporary deactivation end date of the Biller 1..1 3.19 Payment mode details of the Biller 1..n Payment modes supported by the Biller 1..1 3.21 Maximum limit accepted by a Biller for a particular payment mode 0..1 3.22 Minimum limit accepted by a Biller for a particular payment mode 1..1 3.23 Flag indicating whether Pending Status is applicable for the payment mode or not – Yes/No 0..1 Payment channel details of the Biller 1..n Payment channels supported by the Biller 1..1 3.26 Maximum limit accepted by a Biller for a particular payment channel 0..1 3.27 Minimum limit accepted by a Biller for a particular payment channel 1..1 3.28 Flag indicating whether Pending Status is applicable for the payment channel or not – Yes/No 0..1 Customer parameter details of the Biller 1..n Customer parameter name 1..1 Customer parameter data type 1..1 3.20 3.24 3.25 3.29 3.30 3.31 1..1 BBPS API SPECIFICATIONS | Version 13.0 48 3.32 Flag indicating if the Customer parameter is optional 1..1 3.33 Minimum length of the Customer parameter 0..1 3.34 Maximum length of the Customer parameter 0..1 3.35 Regular expression (RegEx) is a string of characters representing permissible values of the customer parameters for a biller. 0..1 3.36 Default (possible) values list against a Customer Parameter 0..1 3.37 Customer Parameter Groups with respect to the various combinations supported 0..1 3.38 Customer Parameter Group 1..n 3.39 Name of the Parent/Sub-Group 1..1 3.40 Flag indicating the required number of tags from the group. 1..1 3.41 Customer parameter name 1..n 3.42 Biller Responses with respect to the various amount combinations supported Amount options supported by the Biller 1..1 Amount combination for a particular amount option 1..n Additional information details provided by the Biller 0..n Additional information parameter name 1..1 3.47 Additional information parameter data type 1..1 3.48 Flag indicating if the additional information parameter is optional 1..1 3.49 Interchange fee configuration details of the Biller 1..n Message Type Indicator for the fee, i.e., fetch, payment, etc. 1..1 Response code associated with the fee 1..1 3.52 Payment mode associated with the fee 0..1 3.53 Payment channel associated with the fee 0..1 3.54 Fee codes for applicable interchange fee 1..n 3.43 3.44 3.45 3.46 3.50 3.51 1..n BBPS API SPECIFICATIONS | Version 13.0 49 3.55 Flag indicating if it is a default fee or not 1..1 3.56 Effective from date for the fee 1..1 3.57 Effective to date for the fee 1..1 3.58 Interchange fee details of the Biller 1..n 3.59 Fee code associated with the Biller 1..1 Description of the corresponding fee code 1..1 Direction of fee movement, i.e., Customer BBPOU to Biller BBPOU or vice-versa 1..1 3.62 Interchange fee details pertaining to range, type and validity 1..n 3.63 Maximum range for a particular fee configuration 1..1 Minimum range for a particular fee configuration 1..1 Percentage fee details 1..1 Flat fee details 1..1 Effective from date for the fee configuration 1..1 Effective to date for the fee configuration 1..1 3.69 Status of the Biller, i.e., active, deactivated, etc. 1..1 3.70 Additional information related to Billers 0..1 3.71 0..1 3.72 Flag indicating whether deemed success is applicable for the biller or not – Yes/No Flag indicating whether pending status is applicable for the biller or not – Yes/No Biller outer limit for providing the response in minutes. This will be applicable only if "Support Pending Status" is Yes. 3.60 3.61 3.64 3.65 3.66 3.67 3.68 3.73 0..1 0..1 7.6 Biller MDM Fetch Response XSD BBPS Biller Fetch Response BBPS API SPECIFICATIONS | Version 13.0 50 BBPS API SPECIFICATIONS | Version 13.0 51 BBPS API SPECIFICATIONS | Version 13.0 52 BBPS API SPECIFICATIONS | Version 13.0 53 8 Agent MDM Fetch Request & Response 8.1 Sample Request API: BBPOU to BBPCU OU21AB21MOB520528256 8.2 Sample Response API: BBPCU to BBPOU OP01OP11AGT000000001 Aggregator Manoj Chekuri Manoj OP11 22.2222,88.8888 OP01 AGT 9505987798 False Internet_Banking 20000000 1 Debit_Card 20000000 1 Credit_Card 20000000 1 Prepaid_Card BBPS API SPECIFICATIONS | Version 13.0 54 20000000 1 IMPS 20000000 1 Cash 4999900 1 UPI 20000000 1 Wallet 20000000 1 NEFT 20000000 1 AEPS 20000000 1 Account_Transfer 20000000 1 Agent 20000000 1 2017-08-30 ACTIVE Physical Agent 1 False 400063 BBPS API SPECIFICATIONS | Version 13.0 55 Mumbai MAHARASHTRA Hub mall India 8.3 Agent MDM Fetch Request Tag Details Index 1.1 XML Element Description Occurrence API Name 1..1 1.1.1 xmlns API schema namespace 1..1 2.1 2.1.1 2.1.2 2.1.3 ver ts origInst 1..1 1..1 1..1 1..1 2.1.4 refId 3.1 Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Tag for searching the Agent details based on certain parameters 3.2 Agent ID for which the Agent details are requested 1..n 4.1 Tag for searching the Agent details based on time parameter 0..1 4.2 Request for Agent details for all the Agents updated in the system after the time provided 1..1 1..1 0..1 8.4 Agent MDM Fetch Request XSD Agent Fetch Request BBPS API SPECIFICATIONS | Version 13.0 56 8.5 Agent MDM Fetch Response Tag Details Index 1.1 XML Element Description Occurrence API Name 1..1 1.1.1 xmlns API schema namespace 1..1 2.1 2.1.1 2.1.2 2.1.3 ver ts origInst 1..1 1..1 1..1 1..1 2.1.4 refId 3.1 Header of the message Version of the API Creation timestamp of the message Code assigned to the BBPOU / BBPCU which forwards the transaction Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain MDM details of the Agent 3.2 Identifier of the Agent 1..1 3.3 Business type of the Agent 1..1 Name of the Agent 1..1 Alias name of the Agent 1..1 Code of the Agent Institution associated with the Agent 1..1 Agent geo-location 1..1 Shop name of the Agent 1..1 Mobile number of the Agent 1..1 Flag indicating if the Agent represents an electronic or physical channel Payment mode details of the Agent 1..1 Payment modes supported by the Agent 1..1 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 1..1 0..n 1..n 3.13 Maximum limit accepted by an Agent for a particular payment mode 0..1 3.14 Minimum limit accepted by an Agent for a particular payment mode 1..1 3.15 Payment channel details of the Agent 1..1 Payment channels supported by the Agent 1..1 Maximum limit accepted by an Agent for a particular payment channel 0..1 3.16 3.17 BBPS API SPECIFICATIONS | Version 13.0 57 3.18 Minimum limit accepted by an Agent for a particular payment channel 1..1 3.19 1..1 3.20 3.21 Flag indicating if the Agent is configured through bulk upload feature in BBPS Canvas (intranet portal). ID used by a BBPOU / Agent Institution to internally identify an Agent PIN Code of the Agent 3.22 Registered city of the Agent 1..1 Registered state of the Agent 1..1 Registered address of the Agent 1..1 Registered country of the Agent 1..1 Effective from date of the Agent 1..1 Effective to date of the Agent 1..1 3.28 Temporary deactivation start date of the Agent 1..1 3.29 Temporary deactivation end date of the Agent 1..1 3.30 Status of the Agent, i.e., active, deactivated, etc. 1..1 3.23 3.24 3.25 3.26 3.27 1..1 1..1 8.6 Agent MDM Fetch Response XSD Agent Fetch Response BBPS API SPECIFICATIONS | Version 13.0 58 BBPS API SPECIFICATIONS | Version 13.0 59 9 Acknowledgment 9.1 Sample ACK for Fetch & Payment APIs CPR001 CustomerParams mandatory 9.2 Sample ACK for Other APIs CMR101 Complaint Management - Exchange Id not supported 9.3 Acknowledgment Tag Details Index XML Element Description Occurrence 1.1 API Name 1..1 1.1.1 xmlns API schema namespace 1..1 1.1.2 api Name of the API for which acknowledgement is given out 1..1 1.1.3 refId Reference ID corresponding to the initiating request or response for which the acknowledgement is sent 1..1 1.1.4 msgId 0..1 1.1.5 RspCd 1.1.6 ts Message ID corresponding to the initiating request or response for which the acknowledgement is sent – only applicable for fetch and payment APIs Denotes success or failure in receiving the original request message Transmission date and time of the transaction 2.1 List of error(s) in the request or response message 0..n 2.2 Code of the error 1..1 2.3 Description of the error 1..1 1..1 1..1 9.4 Acknowledgment XSD BBPS API SPECIFICATIONS | Version 13.0 60 BBPS API SPECIFICATIONS | Version 13.0 61 10 BBPS Common 10.1 BBPS Common XSD BBPS API SPECIFICATIONS | Version 13.0 62 BBPS API SPECIFICATIONS | Version 13.0 63 BBPS API SPECIFICATIONS | Version 13.0 64 BBPS API SPECIFICATIONS | Version 13.0 65 BBPS API SPECIFICATIONS | Version 13.0 66 11 Key Exchange / XML signing All messages exchanged in the BBPS eco-system should use XML signing for all message exchange except acknowledgement. A sample has been mentioned below: kQYYeIFygZzHrwGxxfcah8YNO2QROfW7k85yeSK0YkE= VzOIbjYChpNmoCfq4GmY1w33Vnt2envQNBDUERfQLWXwe/pzNXK6cRQcZONUPi3SBmdu9Iyv8vTx R+rPfNian+wEpuReOm23CuyasgtTGp+uf3QIyqhlCuZlR65ZfUhpFEraShYdRIOzfGFAiyGnG7Fl Ilf4q/7mgCQjOw7/paAFiK0h5ERT909PeArLL4isA6KOkindYpTOkAyAGC3t2AJDVJP4SujHbRwx BmcdPbfvMt6aY3n/u5pL/d6XlebWW2l6DhIGSTSBrwx+S2l9EvkRJvKZncNJDbWdUKy2mM0H4YSD javG0rqE2u5CPftUWvHxiiwwqizyOEKMILMOyg== vCidzRWCs8Mukb1E/R1JGCgexwhiDfQDuO0tPHXgX+SDdBptkr+1ThjSBW2D+kH6ZLc22EAL9o/o zBVIJgWwMw4b0LlsdK0dEYjZiFiwFY1AlO4kLB48J2PwZ5Ly2ADKP+CzpZ7YhPNUz7tGCqiKyM3E IXWqvzS1Yb4+zYardGBtUkLAJDNDltSgyDe/Fb27viTTxsps2rTZ7VZCWRGyCON5F149EVXnVFUt SD1oye1x1IxDcfYEc49OAa+BZiheGMpNpzkCR263CFbe0UnQbuQwz9eaoPuCn5tQBxFv5v4/Ho1W zbTZBSSf2Ow1N6fqXzWLw444Ea5ftyNpDq+HUw== Aw== BBPS API SPECIFICATIONS | Version 13.0 67 12 URLs for Different API Messages 12.1 Request URL format (Customer BBPOU to BBPCU): Request Type Service URL Bill Fetch Request /bbps/BillFetchRequest/1.0/urn:referenceId:{referenceId} Bill Payment Request /bbps/BillPaymentRequest/1.0/urn:referenceId:{referenceId} Bill Validation Request /bbps/BillValidationRequest/1.0/urn:referenceId:{referenceId} 12.2 Request URL format (BBPCU to Biller BBPOU): Request Type Service URL Bill Fetch Request /BillFetchRequest/1.0/urn:referenceId:{referenceId} Bill Payment Request /BillPaymentRequest/1.0/urn:referenceId:{referenceId} Bill Validation Request /BillValidationRequest/1.0/urn:referenceId:{referenceId} Txn Status Request 402 /txnStatusRequest402/1.0/urn:referenceId:{referenceId} 12.3 Response URL format (Biller BBPOU to BBPCU): Response Type Service_url Bill Fetch Response /bbps/BillFetchResponse/1.0/urn:referenceId: Bill Payment Response /bbps/BillPaymentResponse/1.0/urn:referenceId: Bill Validation Response /bbps/BillValidationResponse/1.0/urn:referenceId: Txn Status Response 402 /bbps/txnStatusResponse402/1.0/urn:referenceId: 12.4 Response URL format (BBPCU to Customer BBPOU): Response Type Service_url Bill Fetch Response /BillFetchResponse/1.0/urn:referenceId: Bill Payment Response /BillPaymentResponse/1.0/urn:referenceId: Bill Validation Response /BillValidationResponse/1.0/urn:referenceId: 12.5 Request URL format (BBPOU to BBPCU): Request Type Service URL Diagnostic Request /bbps/ReqHbt/1.0/urn:referenceId: {referenceId} Complaint Request /CMS/TxnStatusComplainRequest Biller MDM /bbps/BillerFetchRequest/1.0/urn:referenceId:{referenceId} Agent MDM /bbps/AgentFetchRequest/1.0/urn:referenceId:{referenceId} BBPS API SPECIFICATIONS | Version 13.0 68 12.6 Response URL format (BBPCU to BBPOU): Response Type Service_url Complaint Response /TxnStatusComplainResponse Biller MDM /BillerFetchResponse/1.0/urn:referenceId: Agent MDM /AgentFetchResponse/1.0/urn:referenceId: BBPS API SPECIFICATIONS | Version 13.0 69 13 Error Codes and Declines The codes for the system can be configured as follows: S. No. 1 2 3 4 5 6 Scenario Forward Request / Response Force Closed Transactions Reversals CU declines BOU Declines COU Declines Response Code Response Reason 000 100 101 – 199 001 – 099 200 – 299 300 – 399 Successful Failure Failure Failure Failure Failure For all the above response codes, there will be corresponding compliance response codes and compliance reasons. Compliance response code will follow the following nomenclature. Compliance Code XXX111 Compliance Reason Explanation Description of the error Where XXX are alpha characters and 111 are numeric characters All the compliance codes and their reasons will be accessible through a table and any modification to the list will be possible. 13.1 BBPCU Declines Under BBPCU declines, there will be list of compliance codes and compliance reasons for each tag / attribute. Please note that the following terms have been used interchangeably in the following table:    BBPCU and CU Customer BBPOU and Customer OU / COU Biller BBPOU and Biller OU / BOU Leg COU  CU CU  BOU Scenario CU receives malformed request from COU. Fetch / Validation CU declines COU request with a negative ACK. Payment CU declines COU request with a negative ACK. CU unable to connect to BOU even after multiple retries. No other response from CU is required as all Error Codes are populated as part of the Negative ACK from CU. CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. No other response from CU is required as all Error Codes are populated as part of the Negative ACK from CU. CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU006 and Compliance Reason will carry "Connect Timeout at BOU". Compliance Response Code will be BOU006 and Compliance Reason will carry "Connect Timeout at BOU". CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. TYPE: FORWARD TYPE RESPONSE CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU007 and Compliance Reason will carry Compliance Response Code will be BOU007 and Compliance Reason will carry CU makes multiple retry attempts without any success in any of the following cases:  No ACK by BOU  Delayed ACK by BOU BBPS API SPECIFICATIONS | Version 13.0 70 (beyond timeout period)  Positive ACK by BOU but not reaching CU "Read Timeout at BOU". Any other generic reason for request failure to BOU, e.g., Connection Reset, Connection Refused, Bad Gateway, Internal Server Error, Null Pointer Exception, etc. CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU008 and Compliance Reason will carry "Unable to Connect to BOU". Compliance Response Code will be BOU008 and Compliance Reason will carry "Unable to Connect to BOU". BOU is temporarily down (BOU is not sending diagnostic request). CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. TYPE: FORWARD TYPE RESPONSE CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU001 and Compliance Reason will carry "Send Failed to BOU". Compliance Response Code will be BOU001 and Compliance Reason will carry "Send Failed to BOU". CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. TYPE: FORWARD TYPE RESPONSE CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU002 and Compliance Reason will carry "". Compliance Response Code will be BOU002 and Compliance Reason will carry "". CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. TYPE: FORWARD TYPE RESPONSE CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU003 and Compliance Reason will carry "Timeout at BOU". Compliance Response Code will be BOU003 and Compliance Reason will carry "Timeout at BOU". CU forwards the request to BOU but BOU declines with a negative ACK. Timeout for request sent to BOU, i.e., Response Timeout by BOU. Pending Transaction Timeout for request sent to BOU, i.e., Response Timeout by BOU. "Read Timeout at BOU". TYPE: FORWARD TYPE RESPONSE NA TYPE: FORWARD TYPE RESPONSE CU initiates a Response Code 001 and Response Reason "Failure" decline to COU. Compliance Response Code will be BOU009 and Compliance Reason will carry "Pending Transaction Timeout at BOU". BOU  CU BOU responds, but with malformed response. CU rejects the BOU response with negative ACK and allows BOU to CU initiates a Response Code 002 and Response Reason "Failure" decline to COU. Compliance Response Code will be TYPE: FORWARD TYPE RESPONSE Pending not applicable: CU initiates a Response Code 002 and Response Reason "Failure" decline to COU. BBPS API SPECIFICATIONS | Version 13.0 71 retry within the timeout period. Yet, there is no proper response from BOU within this timeout period. BOU002 and Compliance Reason will carry "". Compliance Response Code will be BOU002 and Compliance Reason will carry "". TYPE: FORWARD TYPE RESPONSE Pending applicable: CU COU CU unable to connect to COU even after multiple retries. CU makes multiple retry attempts without any success in any of the following cases:  No ACK by COU  Delayed ACK by COU (beyond timeout period)  Positive ACK by COU but not reaching CU For a successful BOU -> CU response: CU declines response given by BOU with a negative ACK and initiate 402 API to BOU to check the status of the transaction at pre-defined interval till Biller Timeout Period. For a successful BOU -> CU response: CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU006 and Compliance Reason will carry "Connect Timeout at COU". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU006 and Compliance Reason will carry "Connect Timeout at COU". For a failed BOU -> CU response: For a failed BOU -> CU response: CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". Compliance Response Code will be COU006 and Compliance Reason will carry ", Connect Timeout at COU". Compliance Response Code will be COU006 and Compliance Reason will carry ", Connect Timeout at COU". For a successful BOU -> CU response: TYPE: FORWARD TYPE RESPONSE For a successful BOU -> CU response: CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU007 and Compliance Reason will carry "Read Timeout at COU". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU007 and Compliance Reason will carry "Read Timeout at COU". For a failed BOU -> CU response: For a failed BOU -> CU response: CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". BBPS API SPECIFICATIONS | Version 13.0 72 Any other generic reason for response failure to COU, e.g., Connection Reset, Connection Refused, Bad Gateway, Internal Server Error, Null Pointer Exception, etc. COU is temporarily down (COU is not sending diagnostic request). CU forwards the response to COU but Compliance Response Code will be COU007 and Compliance Reason will carry ", Read Timeout at COU". Compliance Response Code will be COU007 and Compliance Reason will carry ", Read Timeout at COU". For a successful BOU -> CU response: TYPE: FORWARD TYPE RESPONSE For a successful BOU -> CU response: CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU008 and Compliance Reason will carry "Unable to Connect to COU". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU008 and Compliance Reason will carry "Unable to Connect to COU". For a failed BOU -> CU response: For a failed BOU -> CU response: CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". Compliance Response Code will be COU008 and Compliance Reason will carry ", Unable to Connect to COU". Compliance Response Code will be COU008 and Compliance Reason will carry ", Unable to Connect to COU". For a successful BOU -> CU response: TYPE: FORWARD TYPE RESPONSE For a successful BOU -> CU response: CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU001 and Compliance Reason will carry "Send Failed to COU". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU001 and Compliance Reason will carry "Send Failed to COU". For a failed BOU -> CU response: For a failed BOU -> CU response: CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". Compliance Response Code will be COU001 and Compliance Reason will carry ", Send Failed to COU". Compliance Response Code will be COU001 and Compliance Reason will carry ", Send Failed to COU". No other response from CU is required towards COU. Do away with negative ACK TYPE: FORWARD TYPE RESPONSE No other response from CU is required towards COU. Do away with negative ACK BBPS API SPECIFICATIONS | Version 13.0 73 COU declines with a negative ACK. by COU. by COU. For a successful BOU -> CU response: For a successful BOU -> CU response: CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". CU closes and records the transaction with a Response Code 000 and Response Reason "Successful". As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU002 and Compliance Reason will carry all the Error Codes from Negative ACK. As a distinguishing identifier from successfully acknowledged responses, Compliance Response Code will be COU002 and Compliance Reason will carry all the Error Codes from Negative ACK. Note: COU can raise a complaint for the respective transaction if required. For a failed BOU -> CU response: For a failed BOU -> CU response: CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". CU closes and records the transaction with a Response Code 003 and Response Reason "Failure". Compliance Response Code will be COU002 and Compliance Reason will carry ", ". Compliance Response Code will be COU002 and Compliance Reason will carry ", ". TYPE: FORWARD TYPE RESPONSE For the Billers, which does not support deemed success; the existing response codes and compliance codes will be applicable (as mentioned below). Leg CU COU Scenario Send Failed for response sent to COU. Fetch / Validation CU closes and records the transaction with a Response Code 001 and Response Reason “Failure”. Compliance Response Code will be COU001 and Compliance Reason will carry “Send Failed to COU”. CU forwards the response to COU but COU declines with a negative ACK. No other response from CU is required towards COU. CU closes and records the transaction with a Response Code 301 and Response Reason “Failure”. Compliance Response Code will be COU002 and Compliance Reason will carry "". Payment CU will initiate a Reversal request to BOU. BOU will send a Reversal Response with Response Code 103 and Response Reason “Failure”. On its way back to COU, the CU populates Compliance Response Code as COU001 and Compliance Reason will carry “Send Failed to COU”. If COU is down at that moment, it will be retried till the point it is successfully delivered. Type : REVERSAL TYPE RESPONSE CU will initiate a Reversal request to BOU. BOU will send a Reversal Response with Response Code 103 and Response Reason “Failure”. On its way back to COU, the CU populates Compliance Response Code as COU002 and Compliance Reason will carry "". If COU is down at that moment, it will be retried till the point it is successfully BBPS API SPECIFICATIONS | Version 13.0 74 delivered. Type : REVERSAL TYPE RESPONSE 13.2 Biller BBPOU Declines There are scenarios which can emerge when there are issues between BOU and the Biller. List of Compliance Codes which has to be populated at the time of BOU business rejections are as follows: Response Code Compliance Code Compliance Description 200 BFR001 Incorrect / invalid Customer account 200 BFR002 Invalid combination of Customer parameters 200 BFR003 No bill data available 200 BFR004 Payment received for the billing period - no bill due 200 BFR005 Customer account is blocked / closed 200 BFR006 Customer account is not activated 200 BFR007 Bill due date has expired - bill details are not available 200 BFR008 Unable to get bill details from Biller 200 BFR009 Scheduled downtime taken by biller for maintenance activity. Please try again later 200 BFR010 200 BFR011 Unscheduled downtime taken by biller for maintenance activity. Please try again later Incomplete details in Biller system - update Customer profile 200 BPR001 Incorrect / invalid Customer account 200 BPR002 Invalid combination of Customer parameters 200 BPR003 Customer account is blocked / closed 200 BPR004 Customer account is not activated 200 BPR005 Payment cannot be accepted at this time 200 BPR006 Payment request has been exceeded for the day 200 BPR007 Repeat payment request 200 BPR008 200 200 BPR009 BPR010 200 BVR001 Due date has been expired to pay this amount. Please re-fetch again to get the current outstanding Scheduled downtime taken by biller for maintenance activity. Please try again later Unscheduled downtime taken by biller for maintenance activity. Please try again later Incorrect / invalid Customer account 200 BVR002 Invalid combination of Customer parameters 200 BVR003 Customer account is blocked / closed 200 BVR004 Customer account is not activated 200 BVR005 Invalid Amount 200 BVR006 Customer account deactivated - pay Rs. to activate account 200 BVR007 Incomplete details in Biller system - update Customer profile 200 BVR008 Customer account valid but no bill due 200 BVR009 Technical exception from biller 200 Future Purpose Incorrect / Invalid Plan ID 200 Future Purpose No recharge found for Plan ID and Customer account combination BBPS API SPECIFICATIONS | Version 13.0 75 Some of the Biller BBPOU decline scenarios are as follows: MTI Fetch Scenario Incorrect / invalid customer account Expected Biller Response Parameters Biller Response block not required Expected Reason Block Codes Response Code = 200 Response Reason = Failure Compliance Response Code = BFR001 Compliance Reason = Incorrect / invalid customer account Fetch Customer account is valid & bill data is not available Biller Response block not required Response Code = 200 Response Reason = Failure Compliance Response Code = BFR003 Response Code = No bill data available Fetch Customer account is valid & no bill due Biller Response block not required Response Code = 200 Response Reason = Failure Compliance Response Code = BFR004 Compliance Reason = Payment received for the billing period - no bill due Payment Bill pay without fetch Response Code = 000 Response Reason = Successful Compliance Response Code = Compliance Reason = Payment Customer account not found  Customer Name = As Is (NA if Customer Name in unavailable)  Amount =  Due Date = 0001-01-01  Bill Date = 0001-01-01  Bill Number = NA  Bill Period = NA  Customer Convenience Fee = Biller Response block not required Response Code = 200 Response Reason = Failure Compliance Response Code = BPR001 Compliance Reason = Incorrect / invalid customer account 13.3 Customer BBPOU Declines There are scenarios which can emerge when there are issues between Customer BBPOU and its Frontend. Customer BBPOU can decline certain transactions which then need to be appropriately captured. List of Compliance Codes which has to be populated at the time of Customer BBPOU rejections are as follows: Compliance Code Compliance Description BFS001 Front end channel unavailable BFS002 Customer has initiated reversal BFS003 Receipt not generated BFS004 Unable to process transaction internally BBPS API SPECIFICATIONS | Version 13.0 76 13.4 Forced Closure of Transactions by CU Please refer to the diagram below for Payment leg of a transaction with Legs 1-4 constituting the Payment legs and Legs 5-7 constituting the Reversal legs as per the existing BBPS payment process flow. Figure 1: Payment and its subsequent Reversal The Payment request initiated from Customer OU is processed successfully and a positive response is provided by the Biller OU (Legs 1 – 3). For some reason (COU001 or COU002) when Leg 4 of the transaction fails, CU will generate a Reversal Request and send it to the BOU (Leg 5). BOU then generates a Reversal Response to BOU (Leg 6) which is ultimately forwarded to the COU (Leg 7). All these “open” transactions (both FETCH and PAYMENT) without any assigned Response or Compliance Codes in the transaction table even after a significant period of time. Such transactions need to be force closed by CU (moved from transaction to reporting tables) after a certain interval (say, a configurable value of 4 hours) using the following combination of Response and Compliance Codes. S. No. 1 2 3 4 5 6 7 Description CU is not able to connect to the BOU for forwarding the Reversal Request BOU has not provided an ACK for the Reversal Request BOU has provided a negative ACK for the Reversal Request BOU has acknowledged the Reversal Request, but has not sent or has sent a malformed Reversal Response CU is not able to connect to the COU for forwarding the Reversal Response COU has not provided an ACK for the Reversal Response COU has provided a negative ACK for the Reversal Response Response Code 100 Response Reason Failure Compliance Code BOU004 100 Failure BOU004 100 Failure BOU004 100 Failure BOU005 100 Failure COU003 100 Failure COU003 100 Failure COU003 Compliance Reason* , BOU Reversal Retry Failure , BOU Reversal Retry Failure , BOU Reversal Retry Failure , BOU Reversal Response Timeout , COU Reversal Retry Failure , COU Reversal Retry Failure , COU Reversal Retry Failure For the Billers which does not support Deemed Success The revised CU decline scenarios effectively eliminate the Reversal legs because of the manner in which a failure in Leg 4 of the transaction is handled for the billers which support Deemed Success. Thus, some transactions remaining incomplete in the transaction table (OLTP) if one of Legs 5, 6 or 7 fails will no longer be a possibility and will not require any forced closure by CU. However, there may be exceptional scenarios like some “open” transactions (both FETCH and PAYMENT) without any assigned Response or Compliance Codes in the transaction table even after a significant period of time. Such BBPS API SPECIFICATIONS | Version 13.0 77 transactions need to be force closed by CU (moved from transaction to reporting tables) after a certain interval (say, a configurable value of 4 hours) using the following combination of Response and Compliance Codes. S. No. 1 2 3 Description Leg 2 (CU to BOU) failure Leg 3 (BOU to CU) failure Leg 4 (CU to COU) failure Response Code 100 100 100 Response Reason Failure Failure Failure Compliance Code BOU001 BOU003 COU001 Compliance Reason Send Failed to BOU Timeout at BOU Send Failed to COU For the Billers which support Deemed Success For Leg 4 failure, system has to consider the response given by the BOU as the final status for the biller which support deemed success even for force closure. BBPS API SPECIFICATIONS | Version 13.0 78 14 Re-utilization of Fetch / Validation for Registered Customers In BBPS for billers supporting Fetch/Validation it may be noted that fetch/validation and payment transactions are linked through Reference ID. Currently, if a Reference ID is consumed by COU for making a payment once, it cannot use the same fetch/validation response to initiate another payment using the same Reference ID (unless it is a CU rejected payment transaction where COUs are expected to re-initiate the payment using the same Reference ID). Currently, for re-attempting a payment, in case of non CU rejected payment transactions, COUs are expected to refetch the bill (or re-validate the customer params) and then initiate a payment for the same. Basis the market feedback, we are allowing the Fetch response to be re-utilized only for registered customers, till payment is successfully posted within 2 days of first try of the Payment. However, if COUs intend to reuse the Validation response for making multiple retries till payment is successful, the ageing period will be 24 hrs of successful Validation. In order to reutilize the Fetch/Validation response for multiple payment retries, COUs will be required to pass siTxn attribute value as ‘Yes’ in all the payment requests mandatorily. S. No. 1 2 3 4 5 6 7 8 Activity Bill Fetch Request Bill Fetch Response Bill Payment Request (1st Attempt) Bill Payment Response Bill Payment Request (2nd Attempt) Can be done if previous attempt was FAILED. Bill Payment Response Bill Payment Request (3rd Attempt) Can be done if previous attempts are FAILED. Bill Payment Response (Successful) Sender Receiver Reference ID R1 Message ID M1 Transaction ref ID - Original Reference ID - COU CU CU BOU R1 M1 - - BOU CU R1 M1 - - CU COU R1 M1 - - COU CU R1 M2 T1 - CU BOU R1 M2 T1 - BOU CU R1 M2 T1 - CU COU R1 M2 T1 - COU CU R2 M3 T2 R1 CU BOU R2 M3 T2 R1 BOU CU R2 M3 T2 R1 CU COU R2 M3 T2 R1 COU CU R3 M4 T3 R1 CU BOU R3 M4 T3 R1 BOU CU R3 M4 T3 R1 CU COU R3 M4 T3 R1 14.1 Considerations for Customer OUs 1. Reutilization of Fetch / Validation functionality is only for registered customers. 2. This functionality can be used on Digital Channels Only and will not be available for Physical Channels. 3. CU will allow the payment retry attempt, only if the previous attempt was "FAILED". If the previous attempt is "IN PROGRESS" or "SUCCESSFUL", system will reject the subsequent attempt. BBPS API SPECIFICATIONS | Version 13.0 79 4. If COUs intend to use this feature, they need to pass siTxn value as 'Yes' in all the Payment requests. 5. For first payment request COUs will be required to pass only the ref ID along with siTxn tag value as 'Yes'. In case the payment was failed in BBPS (not CU rejection), COUs can reutilize the fetch/validation response, however, COUs will be required to pass OrigRefId (original Ref ID will be the ref ID of the first attempt) along with unique reference ID for each subsequent payment request. 6. For re-utilization of Fetch, there will be an ageing period of 2 days for reattempting payment using the original reference ID. Ageing period for reutilization of fetch will start from the day of first payment request made and the ageing period is in days. 7. For re-utilization of Validation, the ageing period will be 24 hrs from the Successful Validation done. 8. If COUs are going to retry payment using the origRefId, in case of first or other subsequent payment failure(s), COUs should not send any communication (SMS/Email) to customer regarding the fate of transaction i.e. transaction reference Id. COUs should only provide the information/status of the last legitimate retry. COUs can provide acknowledgement that the transaction is in progress. 9. Once successful payment has been done, COUs has to send the communication (SMS/Email) to customer related to transaction (i.e. transaction reference Id, status, etc.), which can be used for Transaction Status Check, Complaint Registration. 10. If there are multiple payment tries, only the last transaction ref ID will be used for Complaints registration and Disputes. 11. Additional tag origRefId will appear in the RAW file(s). All the entities who have automated their reconciliation process needs to take cognisance of the change and act appropriately. 14.2 Considerations for Biller OUs 1. Currently BOUs are considering the Ref ID to link the Fetch and Payment transactions. In case BOUs receives the Payment transaction with tag siTxn as 'Yes' and resulted as failure, there may be subsequent Payment attempts. So, they have to allow payment to be made for the biller till it is successful using the origRefId till the ageing period and BOUs should establish the same linkage between Fetch Ref ID and origRefId. 2. Additional tag origRefId will appear in the RAW file(s). All the entities who have automated their reconciliation process needs to take cognisance of the change and act appropriately. BBPS API SPECIFICATIONS | Version 13.0 80 15 CMS Response Scenarios The following tables highlight the different scenarios associated with CMS related APIs and their outcomes. S. No. 1 2 3 4 5 Scenario Search transaction - Transaction ID exists - Mobile Number (with / without date range) exists Response Code and Reason  responseCode="000"  responseReason="SUCCESS"  txnStatus="SUCCESS/FAILURE /REVERSAL/IN_PROG/REVERS AL_IN_PROG" Search transaction  responseCode="001" - Valid Transaction ID format  responseReason="No but transaction does not exist Transaction found" - Valid Mobile Number (with / without date range) format but transaction does not exist Search transaction - Invalid Transaction ID format CMR007 - Invalid Mobile Number (with Complaint / without date range) format Management - Transaction Ref Id fixed length 12 or 20 CMR105 Complaint Management - Mobile Number Numeric, Minimum length is 6 and maximum is 20 Raise a complaint on a  responseCode="000" transaction  responseReason="SUCCESS" - Transaction ID exists openComplaint="N/Y" Raise a complaint on a  responseCode="001" transaction  responseReason="No - Valid Transaction ID format Transaction found" but transaction does not exist Comments CU returns a successful response. Transaction status (txnStatus) may be one of the following: - SUCCESS: Successful payment transactions (Payment Response Code was 000). - FAILURE: For failed payment transactions (Payment Response Code was 001 - 099 for CU declines, 200 - 299 for BOU declines and 300 - 399 for COU declines). - REVERSAL: For payment reversal transactions (Payment Response Code was 100 - 199). - IN_PROG: Payment transaction is still being processed - REVERSAL_IN_PROG: Payment transaction is waiting to be reversed CU returns a failure response. CU returns a negative ACK CU returns a successful response. openComplaint attribute indicates the following: - N: Complaint is being raised against a Transaction ID for the first time OR for a Transaction ID against which an earlier lodged complaint is already closed. - Y: Complaint is being raised against a Transaction ID for which an earlier lodged complaint is still open. Thus, complaint details of the earlier open complaint is returned. CU returns a failure response. BBPS API SPECIFICATIONS | Version 13.0 81 6 7 8 9 Raise a complaint on a transaction - Invalid Transaction ID format CMR007 Complaint Management - Transaction Ref Id fixed length 12 Search a complaint  responseCode="000" - Complaint ID exists  responseReason="SUCCESS" Search a complaint  responseCode="001" - Valid Complaint ID format  responseReason="Complaint but transaction does not exist not found" Search a complaint (Does not exist CMR010 - Invalid Complaint ID format Complaint Management - Complaint Id length must be 15 CU returns a negative ACK CU returns a successful response. CU returns a failure response. CU returns a negative ACK BBPS API SPECIFICATIONS | Version 13.0 82 16 Biller Types in BBPS The following table outlines the various Biller integration scenarios in BBPS. These fields are passed on as Biller MDM Response parameters. S. No. 1 2 Type ONLINE ONLINE Accepts Ad-hoc T T Fetch Requirement Support Validation OPTIONAL - QuickPay value in Pay Request  Yes OPTIONAL -  No NOT_SUPPORTED OPTIONAL  Yes NOT_SUPPORTED OPTIONAL  No Transaction  Ad-hoc Payment can be done (for any amount).  Payment against fetch can also be done for any amount.  Ad-hoc Payment can be done (for any amount).  Payment against validation can also be done for any amount. 3 ONLINE T NOT_SUPPORTED MANDATORY  No  Payment against validation can also be done for any amount. 4 ONLINE T NOT_SUPPORTED NOT_SUPPORTED  Yes 5 ONLINE T MANDATORY -  No  Ad-hoc Payment can be done (for any amount).  Ad-hoc Payment cannot be done. Payment against fetch can be done for any amount. 6 ONLINE F MANDATORY -  No  Ad-hoc Payment cannot be done. EXACT, EXACT_UP, EXACT_DOWN can be paid against fetched bill as per configuration. 7 OFFLINE A T OPTIONAL -  Yes OPTIONAL -  No  Ad-hoc Payment can be done (for any amount).  Payment against fetch can also be done for any amount. NOT_SUPPORTED OPTIONAL  Yes NOT_SUPPORTED OPTIONAL  No 8 OFFLINE A T  Ad-hoc Payment can be done (for any amount).  Payment against validation can also be done for any amount. 9 OFFLINE A T NOT_SUPPORTED MANDATORY  No  Payment against validation can also be done for any amount. 10 OFFLINE A T NOT_SUPPORTED NOT_SUPPORTED  Yes 11 OFFLINE A T MANDATORY -  No  Ad-hoc Payment can be done (for any amount).  Ad-hoc Payment cannot be done. Payment against fetch can be done for any amount. 12 OFFLINE A F MANDATORY -  No  Ad-hoc Payment cannot be done. EXACT, EXACT_UP, EXACT_DOWN can be paid against fetched bill as per configuration. 13 OFFLINE B T NOT_SUPPORTED OPTIONAL  Yes NOT_SUPPORTED OPTIONAL  No  Ad-hoc Payment can be done (for any amount).  Payment against validation can also be done for any amount. 14 OFFLINE B T NOT_SUPPORTED MANDATORY  No  Payment against validation can also be done for any amount. 15 OFFLINE B T NOT_SUPPORTED NOT_SUPPORTED  Yes  Ad-hoc Payment can be done (for any amount). BBPS API SPECIFICATIONS | Version 13.0 83 17 Amount Block Configuration in Bill Fetch & Bill Payment Messages The paymentAmountExactness tag in the Biller MDM Response is applicable only when fetchRequirement tag value is MANDATORY and billerAcceptsAdhoc tag value is false. For example, if fetch response amount is Rs. 100 then the payment amount can be the following:    Exact – Only Rs. 100 can be paid Exact and above – Rs. 100 or more can be paid Exact and below – Rs. 100 or less can be paid There might be a scenario where a Biller may pass on various amount values as part of Bill Fetch Response like Early or Late Payment. These values are applicable only when all the conditions below hold true for a Biller: 1. Fetch is MANDATORY 2. Ad-hoc field is false 3. Biller accepts Exact payment Following is an example of a biller response block: The biller configuration for this biller is as follows: paramName:"A","dataType":"NUMERIC","optional":true}, paramName:"B","dataType":"NUMERIC","optional":true}, paramName:"C","dataType":"NUMERIC","optional":true}, "amountOptions":[ {"amountBreakupSet":["BASE_BILL_AMOUNT"]}, {"amountBreakupSet":["A"]}, {"amountBreakupSet":["B"]}, {"amountBreakupSet":["C"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","A"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","B"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","C"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","A","B"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","A","C"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","A","B","C"]}, {"amountBreakupSet":["BASE_BILL_AMOUNT","B","C"]}, {"amountBreakupSet":["A","B"]}, {"amountBreakupSet":["A","C"]}, {"amountBreakupSet":["A","B","C"]}, BBPS API SPECIFICATIONS | Version 13.0 84 {"amountBreakupSet":["B","C"]}] For the given amount breakup set, following calculations are possible. Scenario Combination Calculation 1 {"amountBreakupSet":["BASE_BILL_AMOUNT"]}, 200 2 {"amountBreakupSet":["A"]}, 50 3 {"amountBreakupSet":["B"]}, 75 4 {"amountBreakupSet":["C"]}, 25 5 {"amountBreakupSet":["BASE_BILL_AMOUNT","A"]}, 200+50 = 250 6 {"amountBreakupSet":["BASE_BILL_AMOUNT","B"]}, 200+75 = 275 7 {"amountBreakupSet":["BASE_BILL_AMOUNT","C"]}, 200+25 = 225 8 {"amountBreakupSet":["BASE_BILL_AMOUNT","A","B"]}, 200+50+75 = 325 9 {"amountBreakupSet":["BASE_BILL_AMOUNT","A","C"]}, 200+50+25 = 275 10 {"amountBreakupSet":["BASE_BILL_AMOUNT","A","B","C"]}, 200+50+75+25 = 350 11 {"amountBreakupSet":["BASE_BILL_AMOUNT","B","C"]}, 200+75+25 = 300 12 {"amountBreakupSet":["A","B"]}, 50+75 = 125 13 {"amountBreakupSet":["A","C"]}, 50+25 = 75 14 {"amountBreakupSet":["A","B","C"]}, 50+75+25 = 150 15 {"amountBreakupSet":["B","C"]} 75+25 = 100 Now, for the scenarios mentioned in the table, the amount block varies accordingly as shown below: Scenario 1: Scenario 2: Scenario 3: Scenario 4: BBPS API SPECIFICATIONS | Version 13.0 85 Scenario 5: Scenario 6: Scenario 7: Scenario 8: Scenario 9: Scenario 10: Scenario 11: BBPS API SPECIFICATIONS | Version 13.0 86 Scenario 12: Scenario 13: Scenario 14: Scenario 15: BBPS API SPECIFICATIONS | Version 13.0 87 18 Fee Configuration 18.1 Interchange Fee Generally, it is proposed that Customer Operating Unit (Customer BBPOU) and the Biller Operating Unit (Biller BBPOU) would share a fee that would either be charged to the Biller and / or to the customer for bill payment transactions. An interchange fee code needs to be configured for a Category or Category & Biller. The fee could be slab-based, however, the amount ranges should not overlap and neither should there be any gap between a maximum amount of one slab and a minimum amount of the next higher slab. A flat fee, percent fee or a combination of both may be applicable while configuring these fee codes in a particular direction (C2B or B2C). An illustrative example is provided below. Biller Category Biller ID Fee Code Tran. Amount Range (Min) Tran. Amount Range (Max) Percentage Fee (in percentage) Flat Fee (in Paisa) Fee Direction Mobile Postpaid VODA00000NAT01 CCF 1 1000 0 0 C2B Mobile Postpaid Mobile Postpaid VODA00000NAT01 CCF 1001 9999999999 0 100 C2B VODA00000NAT01 EBF 1 9999999999 1 0 B2C Mobile Postpaid VODA00000NAT01 PBF 1 9999999999 2 200 B2C DTH CCF 1 9999999999 0 0 C2B DTH EBF 1 9999999999 1.5 0 B2C DTH PBF 1 9999999999 2.5 0 B2C The Interchange Fee table comprises of the following major fields: 1. 2. 3. 4. 5. Biller Category: Category of the Biller. Biller ID: The ID of the Biller in BBPS. Fee Code: Code assigned by BBPCU as per fee program. Fee Description: A brief description on type of fee which will be applicable. Percentage Fee: Fee can be charged as a percentage per transaction amount (as applicable). It indicates if percentage fee is applicable for that particular Fee Code / Fee Description. 6. Flat Fee: Fee can be charged as a fixed amount per transaction count (as applicable). It indicates if flat fee is applicable for that particular Fee Code / Fee Description. 7. Fee Direction: The direction of flow of fee, C2B or B2C. When flat fee or percent fee field value is zero for a particular fee code, the system will consider that particular component to be zero while calculating fee. BBPS API SPECIFICATIONS | Version 13.0 88 18.2 Interchange Fee Config Interchange fee will be depending on the following parameters: Biller Category, Biller Id, Payment Channel, MTI, Response Code and several other parameters. For a particular Fee Code, system will ensure only one scenario to be applied to Biller Category, Biller, MTI, Response Code and Channel combination in one direction, i.e., from Customer to Biller BBPOU or vice-versa, in the Interchange Fee Config table. This implies that these fee combinations are mutually exclusive, i.e., only one of these combinations can exist at a time. The table below illustrates the following: Biller Category Biller ID MTI Payment Channel Response Code Fees Default Flag Mobile Postpaid VODA00000NAT01 PAYMENT Bank Branch 000 CCF,PBF f Mobile Postpaid VODA00000NAT01 PAYMENT Agent 000 CCF,PBF f Mobile Postpaid VODA00000NAT01 PAYMENT Business Correspondent 000 CCF,PBF f Mobile Postpaid VODA00000NAT01 PAYMENT 000 CCF,EBF t DTH PAYMENT Bank Branch 000 CCF,PBF f DTH PAYMENT Agent 000 CCF,PBF f DTH PAYMENT Business Correspondent 000 CCF,PBF f DTH PAYMENT 000 CCF,EBF t       A combination of Biller Category, Response Code and MTI are mandatory fields while Biller ID and Channel are optional fields. For a combination of Biller Category (Mobile Postpaid), Biller (VODA00000NAT01), Response Code (000), MTI (PAYMENT), and Channels (Bank Branch, Agent & Business Correspondent) CCF and PBF are applicable. Ceteris paribus, for any other Channel, CCF and EBF are applicable since the default indicator is true. If the system is not able to uniquely identify a combination of Biller Category, Biller, MTI, Response Code and Channel, then it will perform computations based on the condition default flag = TRUE for the Biller Category, Biller, Response Code and MTI combination. Duplicate configuration will not be allowed for any interchange fee. A Response Code ‘000’ identifies a successful transaction. The default flag is true only for one unique combination of Biller Category, Biller, MTI, Response Code and Channel. The Interchange Fee Config table comprises of the following major fields: 1. 2. 3. 4. 5. 6. 7. Biller Category: Category of the Biller. Biller ID: The ID of the Biller in BBPS. MTI: Message type indicator identifying the transaction type, i.e., FETCH or PAYMENT. Payment Channel: Payment channel, i.e., Bank Branch, Mobile, etc. Response code: Required to identify successful transactions (000). Fees: The fee codes assigned to a combination of BBPOU and Biller. Default Flag: Boolean field indicating if the particular combination is default or not. BBPS API SPECIFICATIONS | Version 13.0 89 Interchange fee can be configured and authorized by the authorized BBPCU Admin / User. On the basis of these parameters and the applicable fee rate table items, the interchange fee, along with the fee direction will be computed for the respective BBPOUs. Front end configuration will be given to the authorized Canvas user for adding, modifying or deleting interchange fee structure with maker / checker option. Maker can only configure the interchange fee and once approved by the checker, relevant changes will be reflected in the respective tables. Interchange fee that has been charged during the original transaction will be reversed when any action results in a fund movement in the opposite direction. When a transaction reversal is done, the interchange fee will be taken from the bill payment. This could mean that the interchange fee being reversed will not differ from the original interchange fee charged. In case of disputed transactions, the interchange fee of the originating payment transaction will be referred to and be applied in the opposite direction. Note: In case of Refund Good Faith Partial, only percentage fee will be reversed, flat fee won’t be reversed. BBPS API SPECIFICATIONS | Version 13.0 90 19 BBPS IDs 19.1 ID Generation Stages Online & Offline (A) Online & Offline (A) Offline (B) Identification Generator Bill Fetch Request Bill Fetch Response Payment Request Payment Response Payment Request Payment Response msgID Customer BBPOU Populated by Customer BBPOU Carried From Bill Fetch Request Populated by Customer BBPOU Carried From Bill Payment Request Populated by Customer BBPOU Carried From Bill Payment Request refId Customer BBPOU Populated by Customer BBPOU Carried From Bill Fetch Request Carried From Bill Fetch Request Carried From Bill Fetch Request Populated by Customer BBPOU Carried From Bill Payment Request origRefId Customer BBPOU NA NA Populated by Customer BBPOU Carried From Bill Payment Request Populated by Customer BBPOU Carried From Bill Payment Request txnRefId Customer BBPOU NA NA Populated by Customer BBPOU Carried From Bill Payment Request Populated by Customer BBPOU Carried From Bill Payment Request BBPOU ID BBPCU Populated by Customer BBPOU Populated by Biller BBPOU Carried From Bill Fetch Request Populated by Biller BBPOU Populated by Customer BBPOU Populated by Biller BBPOU AI ID BBPCU Populated by Customer BBPOU NA Carried From Bill Fetch Request NA Populated by Customer BBPOU NA Agent ID Customer BBPOU Populated by Customer BBPOU NA Carried From Bill Fetch Request NA Populated by Customer BBPOU NA Biller ID BBPCU Populated by Customer BBPOU NA Carried From Bill Fetch Request NA Populated by Customer BBPOU NA System User ID (BBPOU / BBPCU) BBPCU NA NA NA NA NA NA BBPS API SPECIFICATIONS | Version 13.0 91 19.2 Generation Logic Identification Messages Length Type Logic Example Code generated by the BBPOU that acquires the customer for every transaction initiated. UUID logic defined by ISO to be used for generation of the reference number and is used for matching with every request and response message. Code generated by the BBPOU that acquires the customer for every transaction initiated and used across all messages. UUID logic defined by ISO to be used for generation of the reference number. Customer BBPOU code - 4; Random alphanumeric – 8 MPPSQRS4 ROT7X1M GPY7JGUV 444PLTU2 C689 Customer BBPOU code - 4; Julian Date - 4 Random alphanumeric - 12 OU019047 ABCD1234 5678 Message ID Unique ID assigned by the initiating BBPOU for chaining a request and response message 35 Alphanumeric Reference ID / Original Reference ID Unique ID assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain Unique ID for all BBPS payment transactions 35 Alphanumeric 12 / 20 Alphanumeric Transaction Reference ID BBPOU ID Applicable to BBPOU Y MPPSQRS4 ROT7X1M GPY7JGUV 444PLTU2 C688 Y OU015678 9123 Y It is a unique code allocated by BBPCU for identifying the institution forwarding a request to BBPCU Unique ID associated with Agent Institution Unique number which identifies the Agent 4 Alphanumeric Alpha - 2; Numeric - 2 OU01 Y 4 Alphanumeric OU02 Y 20 Alphanumeric OU01OU0 2INT12345 6789 Y Biller ID Unique number which identifies the Biller 14 Alphanumeric Alpha - 2; Numeric - 2 Customer BBPOU ID - 4; Agent Institution ID - 4; Agent Payment Channel Code - 3; Random number - 9 Short identifier of the biller 14 VODA0000 0MUM03 Y System User ID – BBPCU Uniquely identifies the BBPCU user 16 Alphanumeric BBCU_Use r1 NA System User ID- BBPOU Uniquely identifies the BBPOU user 16 Alphanumeric OU12_Use r2 Y Complaint ID Complaint ID generated by BBPCU 15 Alphanumeric BBCU(4-character) + '_' + user ID provided by BBPCU (Alphanumeric Must be 6 to 11 characters long) BBPOU ID (4-character) + '_' +user ID provided by BBPOU (Alphanumeric Must be 6 to 11 characters long) Random 15 digit alphanumeric value AN146657 6405897 NA AI ID Agent ID BBPS API SPECIFICATIONS | Version 13.0 92 20 Payment Mode & Channel Details 20.1 Initiating Channel Vs Device Block Parameters S. No. 1 Bank Branch Channel Code in API BNKBRNCH 2 Mobile (Pre-login) MOB MOB IP, IMEI, OS, APP 3 Mobile Banking (Postlogin) Internet (Pre-login) MOBB MBB IP, IMEI, OS, APP INT INT IP, MAC INTB INB IP, MAC 6 Internet Banking (Post-login) ATM ATM ATM TERMINAL_ID 7 Kiosk KIOSK KSK TERMINAL_ID 8 Agent AGT AGT TERMINAL_ID, MOBILE, GEOCODE, POSTAL_CODE 9 Business Correspondent BSC BSC TERMINAL_ID, MOBILE, GEOCODE, POSTAL_CODE 4 5 Initiating Channel Channel Code in Agent ID BNK Device Block Tags IFSC, MOBILE, GEOCODE, POSTAL_CODE 20.2 Payment Mode Vs Payment Info Parameters S. No. Payment Mode Payment Information Tag 1 Cash Remarks 2 Internet Banking IFSC|AccountNo 3 Credit Card CardNum|AuthCode 4 Debit Card CardNum|AuthCode 5 Prepaid Card CardNum|AuthCode 6 IMPS MMID|MobileNo 7 NEFT IFSC|AccountNo 8 UPI VPA 9 Wallet WalletName|MobileNo 10 AEPS Aadhaar|IIN 11 Account Transfer IFSC|AccountNo 12 Bharat QR IFSC|AccountNo 13 USSD Remarks The Customer BBPOU may not be able pass on the payment mode details under certain circumstances. Then it may follow the below format while passing payment information:  For card transaction: value="|" e.g.  For transaction through a payment gateway: value="|" e.g. BBPS API SPECIFICATIONS | Version 13.0 93 20.3 Initiating Channel Vs Payment Mode Combinations S. No. Payment Mode Payment Channels INT INB MOB MBB ATM BNK KSK AGT BSC 1 Cash N N N N N Y Y Y Y 2 Internet Banking Y Y Y Y Y N N N N 3 Credit Card Y Y Y Y Y Y Y Y Y 4 Debit Card Y Y Y Y Y Y Y Y Y 5 Prepaid Card Y Y Y Y Y Y Y Y Y 6 IMPS Y Y Y Y N Y N Y Y 7 NEFT Y Y Y Y Y Y N Y Y 8 UPI Y Y Y Y N Y N Y Y 9 Wallet Y Y Y Y N Y Y Y Y 10 AEPS N N Y N N Y N Y Y 11 Account Transfer N N N N N Y N N Y 12 Bharat QR N N Y Y N Y N Y Y 13 USSD N N Y Y N N N N N BBPS API SPECIFICATIONS | Version 13.0 94 21 Settlement File Transfer Mechanism BBPS clearing and settlement system is a three party module consisting of BBPCOU (Customer BBPOU), BBPCU and BBPBOU (Biller BBPOU). BBPCU clearing and settlement is operational throughout the year. It extracts or collects the authorized transactions from the core application server (transaction server) transmitted by the BBPOUs and based on that, processes the transactions in clearing and settlement module and prepares a settlement file which needs to be uploaded to settlement bank. The BBPCU system sends the following files to BBPOUs as part of every settlement cycle, which typically happens multiple times on every working day: 1. 2. 3. 4. RAW File – Will be generated for OU & Participating AI if transactions available for Settlement (XML format) Daily Settlement Report – Will be generated for OU & Participating AI (CSV & PDF formats) Daily GST Report – Will be generated for OU (CSV & PDF formats) Participating AI wise Aggregated Daily Report – Will be generated for OU (CSV & PDF formats) The BBPCU also shares Monthly reports once a month with the BBPOUs: 1. 2. 3. 4. Account Ledger – Will be generated for OU (CSV & PDF formats) Direct AI wise Aggregated Monthly Report – Will be generated for OU (CSV & PDF formats) Monthly GST Report – Will be generated for OU (CSV & PDF formats) Monthly Invoice Report – Will be generated for OU (CSV & PDF formats) All files are securely shared over HTTPS. To be able to receive these files, BBPOU systems must expose the below APIs. Assuming a BBPOU name as OU12, and base URL of BBPOU system as https://a.b.c.d/context URL https://a.b.c.d/context/csv https://a.b.c.d/context/pdf https://a.b.c.d/context/txt Files Received Settlement Report: Example: 07001OU122016080400.csv Account Ledger: Example: 85201607OU122016080400.csv Settlement Report: Example: 07001OU122016080400.pdf Account Ledger: Example: 85201607OU122016080400.pdf Raw Data File: Example: 00001OU132016080400.xml This file contains all transactions for the settlement cycle in XML format, and the XML is signed MIME Type multipart/for m-data Method POST All APIs are expected to return an OK (200) status on successfully receiving a file. The example mentioned in the file transfer process mentions a nomenclature https://a.b.c.d/context (context is just indicative) and this in its entirety is assumed to be the endpoint URL. This is the same endpoint URL which BBPOUs provide for transmission of online messages but in the form https://:. Also, it is the same location where the BBPOUs have deployed their respective BBPOU application. Note: Please refer to Appendix 22.2 for details on the file naming convention for settlement related files. BBPS API SPECIFICATIONS | Version 13.0 95 22 Elements Description Element: Root Presence Definition Data Type Format Compliance : Mandatory : XML root element representing each API. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: Code BillFetchRequest BillFetchResponse BillPaymentRequest BillPaymentResponse TxnStatusRequest TxnStatusResponse BillValidationRequest BillValidationResponse ReqDiagnostic ResDiagnostic TxnStatusComplainRequest TxnStatusComplainResponse BillerFetchRequest BillerFetchResponse AgentFetchRequest AgentFetchResponse Ack Definition The message is a fetch request The message is a fetch response The message is a payment request The message is a payment response The message is a transaction status request (for pending transactions) The message is a transaction status response (for pending transactions) The message is a validation request The message is a validation response The message is a diagnostic request The message is a diagnostic response The message is transaction status and complaint related requests The message is a transaction status and complaint related responses The message is a Biller MDM request The message is a Biller MDM response The message is an Agent MDM request The message is an Agent MDM response The message is an acknowledgement message Attribute: xmlns Presence Definition Data Type Format Compliance : Mandatory : API Schema namespace. : Alphanumeric : Min Length – 1, Max Length – 255 : Namespace declaration used: xmlns:bbps="http://bbps.org/schema" Element: Presence Definition : Mandatory : Header of the message. Attribute: ver Presence Definition Data Type Format Compliance : Mandatory : Version of the API. This is the API version. NPCI may host multiple versions for supporting gradual migration. : Alphanumeric : Min Length – 3, Max Length – 4 : Data format and type. Currently the default production version is 1.0 with subsequent versions being 2.0, 3.0, etc. BBPS API SPECIFICATIONS | Version 13.0 96 Attribute: ts Presence Definition Data Type Format Compliance : Mandatory : Header timestamp will be populated at the time of creating the message which will be updated at each leg of the transaction. : ISODateTime : Fixed Length – 25 i.e., YYYY-MM-DDThh:mm:ss+hh:mm (e.g. 2017-02-14T13:10:15+05:30) Where, YYYY = four-digit year MM = two-digit month number (01 indicates January, etc.) DD = two-digit day of month (01 through 31) T = separator used between date and time hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) +hh:mm = time zone difference from GMT in hours and minutes. The default value of this attribute is assumed to be IST (+05:30). : Tolerance of +/- 299 seconds from the current BBPCU time for Bill Fetch and Bill Payment messages. Since time stamp plays a critical role, it is highly recommended that BBPOU systems are time synchronized with global NTP server. Attribute: origInst Presence Definition Data Type Format Compliance : Mandatory : It is a unique code allocated by BBPCU for identifying the institution forwarding a message to BBPCU. When BBPCU is the originator, the value is "BBCU". : Alphanumeric : Fixed Length – 4, e.g. OU12 Alpha – 2, Numeric – 2 : BBPOU ID allocated to the provider by BBPCU at the time of on-boarding. Attribute: refId Presence Definition Data Type Format Compliance : Mandatory : Code generated by the BBPOU that acquires the customer for every bill fetch transaction initiated and used across all messages. UUID logic defined by ISO to be used for generation of the reference number. : Alphanumeric : Fixed Length – 35 : Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain. The reference ID should be same for fetch / validation and payment request as well as in response for all transactions including reversals. Attribute: siTxn Presence Definition Data Type Format : Conditional : Flad indicating Payment is for registered customers or not. : Code Set : Min Length – 2, Max Length – 3 (Yes / No) BBPS API SPECIFICATIONS | Version 13.0 97 Compliance : If Customer OUs intend to re-utilize the Fetch / Validaation, they need to pass siTxn attribute value as 'Yes' in all the Payment requests. Attribute: origRefId Presence Definition Data Type Format Compliance : Conditional : Code generated by the BBPOU that acquires the customer for a bill payment transaction initiated in-case previous attempt was failed for a registered customer. UUID logic defined by ISO to be used for generation of the reference number. : Alphanumeric : Fixed Length – 35 : Unique identification assigned by the initiating BBPOU to unambiguously identify the transaction which is passed on, unchanged, throughout the entire end-to-end chain. For first payment request COUs will be required to pass only the refId along with siTxn value as 'Yes'. In case the payment was failed in BBPS (not CU rejection), COUs can reutilize the fetch/validation response, however, COUs will be required to pass origRefId (original Ref ID will be the refId of the first attempt) along with unique reference ID for each subsequent payment request. Element: Presence Definition : Optional : The data provided in the Meta element will be used for MIS and analytics purpose. Element: Presence Definition : Conditional : The tag is defined in name value pairs to accommodate the MIS related parameters. It is mandatory to have the following name-value pairs mentioned below. Attribute: name Presence Definition Data Type Format Compliance : Conditional : The name attribute will have the values as defined in the code table. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: Code FETCHREQUESTSTART FETCHREQUESTEND PAYREQUESTSTART PAYREQUESTEND Definition The time at which the fetch request was initiated in the BBPOU system The time at which the fetch request was sent out from the BBPOU system The time at which the payment request was initiated in the BBPOU system The time at which the payment request was sent out from the BBPOU system Attribute: value Presence Definition Data Type Format : Conditional : Details of transaction initiated time and end time in the BBPOU system. : ISODateTime : Fixed Length – 25, i.e., YYYY-MM-DDThh:mm:ss+hh:mm (e.g. 2017-02-14T13:10:15+05:30) Where, YYYY = four-digit year BBPS API SPECIFICATIONS | Version 13.0 98 MM DD T hh mm ss +hh:mm Compliance = two-digit month number (01 indicates January, etc.) = two-digit day of month (01 through 31) = separator used between date and time = two digits of hour (00 through 23) (am/pm NOT allowed) = two digits of minute (00 through 59) = two digits of second (00 through 59) = time zone difference from GMT in hours and minutes. The default value of this attribute is assumed to be IST (+05:30). : Data format and type. Element: Presence Definition : Mandatory : This element contains the transaction details and is passed to all parties involved in the transaction processing. This element is populated by the originator of the transaction and the same must be passed across all the entities. Attribute: ts Presence Definition Data Type Format Compliance : Mandatory : Transaction timestamp created by the initiating BBPOU which will remain constant throughout all legs of the transaction. : ISODateTime : Fixed Length – 25 i.e., YYYY-MM-DDThh:mm:ss+hh:mm (e.g. 2017-02-14T13:10:15+05:30) Where, YYYY = four-digit year MM = two-digit month number (01 indicates January, etc.) DD = two-digit day of month (01 through 31) T = separator used between date and time hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) +hh:mm = time zone difference from GMT in hours and minutes. The default value of this attribute is assumed to be IST (+05:30). : Tolerance of +/- 299 seconds from the current BBPCU time for Bill Fetch and Bill Payment messages. Since time stamp plays a critical role, it is highly recommended that devices are time synchronized with global NTP server. Attribute: msgId Presence Definition Data Type Format Compliance : Mandatory : Code generated by the BBPOU that acquires the customer for every transaction initiated. UUID logic defined by ISO to be used for generation of the reference number and is used for matching with every request and response message. : Alphanumeric : Fixed Length – 35 : Unique identification assigned by the initiating BBPOU for chaining a request and response message. The ID should be same for request and response message. BBPS API SPECIFICATIONS | Version 13.0 99 Attribute: txnReferenceId Presence Definition Data Type Format Compliance : Conditional : This data element will contain a unique reference ID for all BBPS payment transactions. This will be used by the Customer for referring to a payment transaction. : Alphanumeric : Fixed Length – 12 or 20 i) Originating Institution ID (Customer OU Id or Participating AI Id) - 04, Random alphanumeric - 08 ii) Originating Institution ID (Customer OU Id or Participating AI Id) - 04, Julian Date - 04 and Random alphanumeric - 12 : This field is applicable for all payment transactions. COUs are expected to ensure that the Julian date used is of Current Date. Attribute: type Presence Definition Data Type Format Compliance : Conditional : This attribute describes the transaction type for a bill payment transaction. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: Code FORWARD TYPE REQUEST REVERSAL TYPE REQUEST FORWARD TYPE RESPONSE REVERSAL TYPE RESPONSE Definition Payment request transaction is in forward nature Payment request transaction is in reversal nature Response is sent to the forward type request Response is sent to the reversal type response Attribute: xchangeId Presence Definition Data Type Format Compliance Code 401 402 501 502 503 506 507 : Conditional : Identification of the type of the request as listed in the following table. : Code Set : Fixed Length – 3 : Data format and type as follows: Definition Transaction status (OU/AI to CU) Transaction status (CU to BOU) Complaint registration Complaint re-assignment Complaint re-open Complaint status Complaint closure Currently Implemented Yes Yes Yes Yes No Yes Yes Element: Presence Definition : Mandatory : This element defines the risk evaluation associated with the transaction and the related parties in the transaction. BBPS API SPECIFICATIONS | Version 13.0 100 Element: Presence Definition : Mandatory : Risk score related to the transaction and the entities. Attribute: provider Presence Definition Data Type Format Compliance : Mandatory : Entity providing the risk scores. This is the entity which evaluates the risk associated with the transaction. When BBPCU is the provider, the value is "BBPS". : Code Set : Fixed Length – 4 : The provider ID should be same as the originating institution ID used for initiating the fetch or payment request. Attribute: type Presence Definition Data Type Format Compliance : Mandatory : This attribute describes the type of risk. : Code Set : Min Length – 1, Max Length – 50 : Pre-defined values, e.g. TXNRISK Attribute: value Presence Definition Data Type Format Compliance : Mandatory : Code Set : Numeric : Fixed Length – 3 : Value of risk evaluation ranging from "000" (No Risk) to "100" (Maximum Risk) with default score being "030". Element: Presence Definition : Mandatory : Customer related details who initiate the transaction, i.e. details of the customer viewing / paying the bill. Attribute: mobile Presence Definition Data Type Format Compliance : Mandatory : Mobile number of customer who initiates the bill fetch / payment. : Numeric : Minimum Length – 6, Maximum Length - 20 : Data format and type should be for a valid mobile number. Element: Presence : Conditional BBPS API SPECIFICATIONS | Version 13.0 101 Definition : The tag is defined in name value pairs to accommodate the parameters for the Customer initiating the fetch / payment transaction. It is mandatory to have the following name-value pairs mentioned below. Attribute: name Presence Definition Data Type Format Compliance Code EMAIL AADHAAR PAN : Conditional : The name attribute will have the values as defined in the code table. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: Definition Email ID of the customer Aadhaar number of the customer PAN of the customer Attribute: value Presence Definition Data Type Format Compliance Code EMAIL AADHAAR PAN : Conditional : Valid values pertaining to Email, Aadhaar and PAN details provided by the customer initiating the fetch / payment transaction. : Alphanumeric Special : Min Length – 1, Max Length – 50 : Data format and type as follows: Value manoj.chekuri@npci.org.in 123123123200 BXXPC4454Q Element: Presence Definition : Mandatory : Details pertaining to the Agent which initiates the transaction. Attribute: id Presence Definition Data Type Format Compliance : Mandatory : Agent ID is the unique number which identifies the agent. : Alphanumeric : Fixed Length – 20, e.g. OU01OU02INT000000001 Where,  Customer BBPOU ID – 4  Agent Institution ID – 4  Agent Payment Channel Code – 3  Random number – 9 : The Agent ID should be active in BBPCU system. Agent Payment Channel Code is as follows: Initiating Channel Bank Branch Mobile (Pre-login) Channel Code in Agent ID BNK MOB BBPS API SPECIFICATIONS | Version 13.0 102 Mobile Banking (Post-login) Internet (Pre-login) Internet Banking (Post-login) ATM Kiosk Agent Business Correspondent MBB INT INB ATM KSK AGT BSC Element: Presence Definition : Mandatory : Details of the device from which the transaction was initiated. Element: Presence Definition : Conditional : This tag captures the device details in name value pair. Attribute: name Presence Definition Data Type Format Compliance : Conditional : The name attribute will have the values as defined in the code table. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: Code INITIATING_CHANNEL MOBILE GEOCODE POSTAL_CODE IP TERMINAL_ID IMEI IFSC MAC OS APP Definition Initiating channel of the transaction Mobile number of the agent Latitude and longitude of the device – Represented in degrees with 4 digits after decimal Postal code of the agent IP address of the device Terminal ID of the device IMEI number of the mobile IFSC of the branch from which the transaction is initiated MAC ID of the terminal Operating system used in the device Application used in the device Presence Mandatory Conditional Conditional Conditional Conditional Conditional Conditional Conditional Conditional Conditional Conditional Attribute: value Presence Definition Data Type Format Compliance Code MOBILE GEOCODE : Conditional : Specified value as defined : Alphanumeric Special : Min Length – 1, Max Length – 50 : Data format and type as follows: Format nnnnnnnnnn Fixed Length – 10 nn.nnnn,nn.nnnn Example 9505987798 12.9667,77.5667 BBPS API SPECIFICATIONS | Version 13.0 103 IP INITIATING_CHANNEL Min Length – 13, Max Length – 15 Valid IP address format(v4,v6) Max Length – 15 Initiating channel of the transaction Code Set Min Length – 1, Max Length – 20 9.1234,82.5643 123.456.121.121          TERMINAL_ID IMEI IFSC MAC OS APP Terminal ID of the initiating transaction (numeric) Min Length – 1, Max Length – 10 IMEI address of the device IFSC of the bank branch Fixed Length – 11 MAC ID of the device Fixed Length – 17 Operating system used in the device Min Length – 1, Max Length – 20 Application used in the device Min Length – 1, Max Length – 20 Bank Branch – BNKBRNCH Mobile (Pre-login) – MOB Mobile Banking (Post-login) – MOBB Internet (Pre-login) – INT Internet Banking (Post-login) – INTB ATM – ATM Kiosk – KIOSK Agent – AGT Business Correspondent – BSC 123456 123456789012345 ABCD0001152 00-0D-60-07-2A-FO iOS 8.1 SB 1.0 Element: Presence Definition : Mandatory : This tag captures the Biller ID and bill related details to identify a Customer. Element: Presence Definition : Mandatory : Biller related details for which the transaction is initiated. Attribute: id Presence Definition Data Type Format Compliance : Mandatory : Biller ID is the unique number which identifies the Biller. : Alphanumeric : Fixed Length – 14, e.g. TATAPWR00DEL01 Where,  Short identifier of the biller (may be augmented with trailing zeroes) - 9  Coverage - 3  Random number - 2 : The Biller ID should be active in BBPCU system. Element: Presence : Mandatory BBPS API SPECIFICATIONS | Version 13.0 104 Definition : This tag captures the customer parameters. Element: Presence Definition : Conditional : This tag captures the biller’s reference fields in name value pair. Attribute: name Presence Definition Data Type Format Compliance Code RefFld1 RefFld2 RefFld3 : Conditional : Name of the reference field as configured for the Biller in BBPCU system. These data elements would be conditional, i.e., they would be mandatory for specific billers only. : Code Set : Min Length – 1, Max Length – 100 : Data format and type as follows: Definition Reference fields that may be customised according to the requirements of specific Billers at the time of on-boarding a Biller. Sample values include Consumer Number (Electricity billers), Subscriber ID (DTH operators), etc. Attribute: value Presence Definition Data Type Format Compliance Code RefFld1 RefFld2 RefFld3 : Conditional : Value of the reference field which uniquely identifies the Customer for the Biller. : Alphanumeric Special : Min Length – 1, Max Length – 100 : Data format and type as follows: Format As defined at the time of on-boarding by the Biller BBPOU. Example  Consumer No: 210000055001  Mobile No: 9830098300 Element: Presence Definition : Mandatory : This tag captures the response details of the transaction. Attribute: approvalRefNum Presence Definition Data Type Format Compliance : Mandatory : Internal reference number which may be used by the Biller BBPOU for a transaction. : Alphanumeric Special : Min Length – 8, Max Length – 100 : Default value to be "AB123456". Attribute: responseCode Presence Definition : Mandatory : Carries the response code indicating success or failure of the transaction. BBPS API SPECIFICATIONS | Version 13.0 105 Data Type Format Compliance : Code Set : Fixed Length – 3 : Response code should be sent per the response code list shown below. Scenario Forward Request / Response Force Closed Transactions Reversals CU declines BOU Declines COU Declines Response Code 000 100 100 – 199 001 – 099 200 – 299 300 – 399 Response Reason Successful Failure Failure Failure Failure Failure Attribute: responseReason Presence Definition Data Type Format Compliance : Mandatory : Description of the response code sent by the Biller BBPOU. : Code Set : Min Length – 1, Max Length – 50 : Response reason should be sent per the response code list shown below. Scenario Forward Request / Response Force Closed Transactions Reversals CU declines BOU Declines COU Declines Response Code 000 100 100 – 199 001 – 099 200 – 299 300 – 399 Response Reason Successful Failure Failure Failure Failure Failure Attribute: complianceRespCd Presence Definition Data Type Format Compliance : Conditional : The compliance response code for the compliance violation of the specific rule-set by BBPCU. It indicates the reason for a failed transaction and is not required for a successful transaction. : Code Set : Fixed Length – 6, e.g. HED001 Alpha – 3, Numeric – 3 : Compliance code should be sent per the compliance code list. Data format and type as follows: Compliance Code XXX111 Compliance Reason Description of the error Explanation Where XXX are alpha characters and 111 are numeric characters Attribute: complianceReason Presence Definition Data Type Format Compliance : Conditional : The compliance response description for the compliance violation of the specific rule-set by BBPCU. It indicates the reason for a failed transaction and is not required for a successful transaction. : Code Set : Min Length – 1, Max Length – 100 : Compliance reason should be sent per the compliance code list. Data format and type as follows: Compliance Code Compliance Reason Explanation BBPS API SPECIFICATIONS | Version 13.0 106 XXX111 Description of the error Where XXX are alpha characters and 111 are numeric characters Element: Presence Definition : Conditional : This tag captures the bill responses provided by the biller for a successful transaction, i.e., response code is '000'. Attribute: customerName Presence Definition Data Type Format Compliance : Conditional : Customer name as registered with the Biller. : Alphanumeric Special : Min Length – 1, Max Length – 100 : Data format and type. i) To be populated as "NA" where customer name is unavailable ii) For a payment transaction without a fetch, the customer name value should be "NA". iii) For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY Attribute: amount Presence Definition Data Type Format Compliance : Conditional : Actual bill amount inclusive of all charges (in paise). : Numeric : Min Length – 1, Max Length – 18 : Data format and type. For a payment transaction without a fetch, the amount value should be same as the amount passed as payment request. For a reversal transaction, the amount should be same as per the original request. Attribute: dueDate Presence Definition Data Type Format Compliance : Conditional : This field denotes due date of the bill. : ISO Date : Fixed Length – 10, e.g. 2016-01-01 : Data format and type. i) To be populated as "9999-01-01" where due date is unavailable. ii) For a payment transaction without a fetch, the due date value should be current date. iii) For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY Attribute: billDate Presence Definition Data Type Format Compliance : Conditional : This field denotes generation date of the bill. : ISO Date : Fixed Length – 10, e.g. 2016-01-01 : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 107 i) To be populated as "0001-01-01" where bill generation date is unavailable. ii) For a payment transaction without a fetch, the bill date value should be current date. iii) For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY Attribute: billNumber Presence Definition Data Type Format Compliance : Conditional : This field denotes the bill number of the bill fetch / payment message requested. : Alphanumeric Special : Min Length – 1, Max Length – 100 : Data format and type. i) To be populated as "NA" where bill number is unavailable ii) For a payment transaction without a fetch, the bill number value should be "NA". iii) For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY Attribute: billPeriod Presence Definition Data Type Format Compliance : Conditional : The bill period of the bill fetch / payment requested. : Alphanumeric Special : Min Length – 1, Max Length – 50 : Data format and type. i) Possible values are: ONETIME, DAILY, WEEKLY, BIMONTHLY, MONTHLY, QUARTERLY, HALFYEARLY, YEARLY and ASPRESENTED. ii) To be populated as "NA" where bill period is unavailable iii) For a payment transaction without a fetch, the bill period value should be "NA". iv) For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY Attribute: custConvFee Presence Definition Data Type Format Compliance : Conditional : Customer convenience fee (CCF1) paid by the Customer BBPOU to Biller BBPOU. This value is copied from the convenience fee attribute in the amount tag for the payment transaction. : Numeric : Min Length – 1, Max Length – 18 : Data format and type. i) For Biller Categories Mobile Postpaid, Gas, Water, Landline Postpaid, DTH, Broadband Postpaid and Electricity all the attributes are MANDATORY, for others only "amount" is MANDATORY Element: Presence Definition : Conditional : This tag captures the biller’s amount fields in name value pair. It indicates the various amount options provided by the Biller. Attribute: name Presence : Conditional BBPS API SPECIFICATIONS | Version 13.0 108 Definition Data Type Format Compliance Code Amount 1 Amount 2 Amount 3 : Name of the amount field as configured for the Biller in BBPCU system. These data elements would be conditional, i.e., they would be mandatory for specific billers only. : Code Set : Min Length – 1, Max Length – 100 : Data format and type as follows: Definition Amount fields that may be customised according to the requirements of specific Billers at the time of on-boarding a Biller. Sample values include Late Fee, Discount, etc. Attribute: value Presence Definition Data Type Format Compliance : Conditional : Specified value as defined (in paise). : Numeric : Min Length – 1, Max Length – 18 : Data format and type as follows: Code Amount 1 Amount 2 Amount 3 Format As provided by the Biller BBPOU while giving the response. Example  Late Fee: 32000  Discount: 2000 Element: Presence Definition : Conditional : This tag captures the additional information provided by the Biller as part of response for a successful transaction, i.e., response code is ‘000’. Element: Presence Definition : Conditional : This tag captures the biller’s response fields in name value pair. Attribute: name Presence Definition Data Type Format Compliance Code BlRspFld1 BlRspFld2 BlRspFld3 : Conditional : Name of the additional information field as configured for the Biller in BBPCU system. These data elements would be conditional, i.e., they would be mandatory for specific billers only. : Code Set : Min Length – 1, Max Length – 100 : Data format and type as follows: Definition Additional information fields that may be customised according to the requirements of specific Billers at the time of on-boarding a Biller. Sample values include Early Payment Date, Status, etc. BBPS API SPECIFICATIONS | Version 13.0 109 Attribute: value Presence Definition Data Type Format Compliance : Conditional : Specified value as defined. : Alphanumeric Special : Min Length – 1, Max Length – 255 : Data format and type as follows: Code BlRspFld1 BlRspFld2 BlRspFld3 Format As provided by the Biller BBPOU while giving the response. Example  Early Payment Date: 2016-05-01  Status: Active Element: Presence Definition : Mandatory : This tag captures the payment method used for the transaction. Attribute: quickPay Presence Definition Data Type Format Compliance : Mandatory : Flag indicating if the payment is initiated without a fetch or not. : Code Set : Min Length – 2, Max Length – 3 : Accepted values are "Yes" or "No". Attribute: splitPay Presence Definition Data Type Format Compliance : Mandatory : Flag indicating if the bill is paid using two different payment modes. : Code Set : Min Length – 2, Max Length – 3 : Accepted values are "Yes" or "No". Attribute: OFFUSPay Presence Definition Data Type Format Compliance : Optional : Flag indicating if it is an electronic ON-US or OFF-US transaction. : Code Set : Min Length – 2, Max Length – 3 : Accepted values are "Yes" or "No". Attribute: paymentMode Presence Definition Data Type Format Compliance : Mandatory : Defines the payment mode which is used for the bill payment transaction : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: BBPS API SPECIFICATIONS | Version 13.0 110 Payment Mode Internet Banking Debit Card Credit Card IMPS Cash UPI Wallet NEFT Prepaid Card AEPS Account Transfer Bharat QR USSD Code Internet_Banking Debit_Card Credit_Card IMPS Cash UPI Wallet NEFT Prepaid_Card AEPS Account_Transfer Bharat_QR USSD Element: Presence Definition : Mandatory : Block containing different amount related details for the payment transaction. Element: Presence Definition : Mandatory : Details of the bill payment amount made by the Customer. Attribute: amount Presence Definition Data Type Format Compliance : Mandatory : Actual amount paid by the Customer for the transaction (in paise). : Numeric : Min Length – 1, Max Length – 18 : Data format and type. Attribute: custConvFee Presence Definition Data Type Format Compliance : Mandatory : Customer convenience fee (CCF1) paid by the Customer BBPOU to Biller BBPOU. This flows from the Customer BBPOU to the Biller BBPOU. : Numeric : Min Length – 1, Max Length – 18 : Data format and type. Attribute: COUcustConvFee Presence Definition Data Type Format Compliance : Optional : Customer convenience fee (CCF2), paid by the Customer to Customer BBPOU. This value should be within the prescribed limits set for a Biller and the transaction amount and will flow from Customer BBPOU to BBPCU but will not be forwarded to Biller BBPOU. : Numeric : Min Length – 1, Max Length – 18 : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 111 Attribute: currency Presence Definition Data Type Format Compliance : Mandatory : Defines the currency in which the payment is initiated. : Code set (ISO 4217) : Fixed Length – 3 : Data format and type. Accepted value is "356". Element: Presence Definition Data Type Format Compliance : Conditional : This data element will carry the bill payment amount which is paid in the mode other than the primary mode of payment (in paise). : Numeric : Min Length – 1, Max Length – 18 : Data format and type. Element: Presence Definition : Conditional : It indicates the amount paid by the customer for any amount other than the base bill amount. This is applicable only when all the conditions below hold true for a Biller:  Fetch is Mandatory  Biller does not accept ad-hoc payment  Biller accepts exact payment Attribute: name Presence Definition Data Type Format Compliance Code Amount 1 Amount 2 Amount 3 : Conditional : Name of the amount field other than the base bill amount as configured for the Biller in BBPCU system. : Code Set : Min Length – 1, Max Length – 100 : Data format and type as follows: Definition Valid amount combination(s) selected from the Biller response other than the base bill amount. Sample values include Late Fee, Discount, etc. Attribute: value Presence Definition Data Type Format Compliance : Conditional : Specified value as defined (in paise). : Numeric : Min Length – 1, Max Length – 18 : Data format and type as follows: Code Amount 1 Format Selected from the Biller response other than Example  Late Fee: 32000 BBPS API SPECIFICATIONS | Version 13.0 112 Amount 2 Amount 3 the base bill amount.  Discount: 2000 Element: Presence Definition : Conditional : Details of the payment instrument used for the payment. This tag will flow from Customer BBPOU to BBPCU but will not be forwarded to Biller BBPOU. Element: Presence Definition : Conditional : Payment instrument details which is used for the bill payment transaction. Attribute: name Presence Definition Data Type Format Compliance : Conditional : The name attribute will have the values as defined in the code table. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: Code Remarks CardNum|AuthCode IFSC|AccountNo MMID|MobileNo WalletName|MobileNo VPA Aadhaar|IIN Description Remarks when the mode of payment is cash Card number and authorization code used for the payment IFSC and account number used for the payment MMID and mobile number used for the payment Wallet name and mobile number used for the payment Virtual Provider Address used for the payment Aadhaar number and IIN used for the payment Attribute: value Presence Definition Data Type Format Compliance : Conditional : Specified value as defined. : Alphanumeric Special : Min Length – 1, Max Length – 50 : Data format and type as follows: Code Remarks CardNum|AuthCode IFSC|AccountNo MMID|MobileNo WalletName|MobileNo VPA Format Alphanumeric Special Min Length – 1, Max Length – 50 Alphanumeric with characters on either side of ‘|’ separator Min Length – 3, Max Length – 50 Alphanumeric with characters on either side of ‘|’ separator Min Length – 3, Max Length – 50 Numeric with characters on either side of ‘|’ separator Fixed Length – 18 Alphanumeric with characters on either side of ‘|’ separator Min Length – 12, Max Length – 50 Alphanumeric Special Min Length – 3, Max Length – 50 Example UNI000 1234567890123456|123456 SRAN0000341|0123456 9240111|9004644121 TA Wallet|9004644121 manoj@icici BBPS API SPECIFICATIONS | Version 13.0 113 Aadhaar|IIN Alphanumeric with characters on either side of ‘|’ separator Min Length – 3, Max Length – 50 123456789012|1234567 Element: Presence Definition : Conditional : Error messages in the API message. Element: Presence Definition : Conditional : Error Code for API message. Element: Presence Definition : Conditional : Error Reason for the API message. Attribute: api Presence Definition Data Type Format Compliance : Mandatory : Name of the API for which acknowledgement is given out. : Code Set : Min Length – 1, Max Length – 50 : Data format and type as follows: API Name BillFetchRequest BillFetchResponse BillPaymentRequest BillPaymentResponse TxnStatusRequest TxnStatusResponse BillValidationRequest BillValidationResponse TxnStatusComplainRequest TxnStatusComplainResponse BillerFetchRequest BillerFetchResponse AgentFetchRequest AgentFetchResponse Code FETCH_REQUEST FETCH _RESPONSE PAYMENT_REQUEST PAYMENT_RESPONSE FOUR_ZERO_TWO_REQUEST FOUR_ZERO_TWO_RESPONSE VALIDATION_REQUEST VALIDATION_RESPONSE CMS_REQUEST CMS_RESPONSE BILLER_REQUEST BILLER_RESPONSE AGENT_REQUEST AGENT_RESPONSE Attribute: refId Presence Definition Data Type Format Compliance : Mandatory : Reference ID corresponding to the initiating request or response for which the acknowledgement is sent. : Alphanumeric : Fixed Length – 35 : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 114 Attribute: msgId Presence Definition Data Type Format Compliance : Conditional : Message ID corresponding to the initiating request or response for which the acknowledgement is sent – only applicable for fetch and payment APIs. : Alphanumeric : Fixed Length – 35 : Data format and type. Attribute: RspCd Presence Definition Data Type Format Compliance : Mandatory : Denotes success or failure in receiving the original request message. : Code Set : Min Length – 1, Max Length – 50 : Data format and type. Possible values are Successful, VALIDATION_ERR, DUPLICATE_REQ, etc. Attribute: ts Presence Definition Data Type Format Compliance : Mandatory : Transmission date and time of the transaction. : ISODateTime : Fixed Length – 25 i.e., YYYY-MM-DDThh:mm:ss+hh:mm (e.g. 2017-02-14T13:10:15+05:30) Where, YYYY = four-digit year MM = two-digit month number (01 indicates January, etc.) DD = two-digit day of month (01 through 31) T = separator used between date and time hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) +hh:mm = time zone difference from GMT in hours and minutes. The default value of this attribute is assumed to be IST (+05:30). : Data format and type. Element: Presence Definition : Mandatory : Information pertaining to transaction status and complaint related requests. Attribute: msgId Presence Definition Data Type Format Compliance : Mandatory : Code generated by the BBPOU that acquires the customer for every transaction initiated. UUID logic defined by ISO to be used for generation of the reference number and is used for matching with every request and response message. : Alphanumeric : Fixed Length – 35 : Unique identification assigned by the initiating BBPOU for chaining a request and response message. The ID should be same for request and response message. BBPS API SPECIFICATIONS | Version 13.0 115 Attribute: complaintType Presence Definition Data Type Format Compliance : Mandatory : Type of complaint – Transaction or Service based complaint. : Code Set : Min Length – 1, Max Length – 11 : Accepted values are "Transaction" or "Service". Attribute: mobile Presence Definition Data Type Format Compliance : Conditional : Mobile number against which the transaction status is to be searched. : Numeric : Fixed Length – 10 : Data format and type. Attribute: txnReferenceId Presence Definition Data Type Format Compliance : Conditional : Transaction reference number used by the Customer for referring to a payment transaction. : Alphanumeric : Fixed Length – 12 or 20 i) Originating Institution ID (Customer OU Id or Participating AI Id) - 04, Random alphanumeric - 08 ii) Originating Institution ID (Customer OU Id or Participating AI Id) - 04, Julian Date - 04 and Random alphanumeric - 12 : Data format and type. Attribute: complaintId Presence Definition Data Type Format Compliance : Conditional : Complaint ID generated by BBPCU to check the complaint status, re-assign or close a complaint subsequently. : Alphanumeric : Fixed Length – 15 : Data format and type. Attribute: disposition Presence Definition Data Type Format Compliance Issue Related To Transaction Transaction Transaction Transaction Transaction Transaction : Conditional : Disposition for transaction based complaints. : Code Set : Min Length – 1, Max Length – 100 : Disposition details should be sent per the list shown below. Master Disposition List Transaction Successful, account not updated Amount deducted, biller account credited but transaction ID not received Amount deducted, biller account not credited & transaction ID not received Amount deducted multiple times Double payment updated Erroneously paid in wrong account BBPS API SPECIFICATIONS | Version 13.0 116 Transaction Others, provide details in description Attribute: servReason Presence Definition Data Type Format Compliance Issue Related To Agent Agent Agent Agent Agent Agent Biller Biller Biller Biller Biller : Conditional : Disposition for service based complaints. : Code Set : Min Length – 1, Max Length – 100 : Disposition details should be sent per the list shown below. Master Disposition List Agent not willing to print receipt Agent misbehaved Agent outlet closed Agent denying registration of complaint Agent not accepting certain bills Agent overcharging Biller available. Unable to transact Multiple failure for same biller Denomination not available Incorrect bill details displayed Incomplete / No details reflecting Attribute: description Presence Definition Data Type Format Compliance : Conditional : Description of the complaint where the customer may provide some additional information on the reason for raising the complaint. : Alphanumeric Special : Min Length – 1, Max Length – 100 : Data format and type. Attribute: participationType Presence Definition Data Type Format Compliance : Conditional : Entity type for service based complaints. : Code Set : Min Length – 1, Max Length – 6 : Accepted values are "AGENT" or "BILLER". Attribute: agentId Presence Definition Data Type Format Compliance : Conditional : Unique identification code (Agent ID) allocated to the agent for service based complaints. : Alphanumeric : Fixed Length – 20, e.g. OU01OU02INT000000001 Where,  Customer BBPOU ID – 4  Agent Institution ID – 4  Agent Payment Channel Code – 3  Random number – 9 : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 117 Attribute: billerId Presence Definition Data Type Format Compliance : Conditional : Unique identification code (Biller ID) allocated to the biller for service based complaints. : Alphanumeric : Fixed Length – 14, e.g. TATAPWR00DEL01 Where,  Short identifier of the biller (may be augmented with trailing zeroes) - 9  Coverage - 3  Random number - 2 : Data format and type. Element: Presence Definition : Conditional : Searching the transaction details on the basis of date range. Attribute: fromDate Presence Definition Data Type Format Compliance : Conditional : This field denotes the start date for transaction search. : ISO Date : Fixed Length – 10, e.g. 2016-01-01 : Data format and type. Attribute: toDate Presence Definition Data Type Format Compliance : Conditional : This field denotes the end date for transaction search. : ISO Date : Fixed Length – 10, e.g. 2016-01-01 : Data format and type. TxnStatusComplainReq attribute details: Attribute Presence Required in Xchange ID msgId Mandatory 401, 501, 502, 506 and 507 Requests complaintType Mandatory 401, 501, 502, 506 and 507 Requests mobile Conditional 401 Request fromDate Conditional 401 Request toDate Conditional 401 Request txnReferenceId Conditional 401 and 501 Requests complaintId Conditional 502, 506 and 507 Requests disposition Conditional 501 Request servReason Conditional 501 Request description Conditional 501, 502 and 507 Requests participationType Conditional 501 Request BBPS API SPECIFICATIONS | Version 13.0 118 agentId Conditional 501 Request billerId Conditional 501 Request Element: Presence Definition : Mandatory : Information pertaining to transaction status and complaint related responses. Attribute: msgId Presence Definition Data Type Format Compliance : Mandatory : Code generated by the BBPOU that acquires the customer for every transaction initiated. UUID logic defined by ISO to be used for generation of the reference number and is used for matching with every request and response message. : Alphanumeric : Fixed Length – 35 : Unique identification assigned by the initiating BBPOU for chaining a request and response message. The ID should be same for request and response message. Attribute: responseCode Presence Definition Data Type Format Compliance : Mandatory : Carries the response code indicating success or failure of CMS API request. : Code Set : Fixed Length – 3 : Response code should be sent per the response code list shown below. Response Code 000 001 Response Reason SUCCESS No Transaction found / Complaint not found Attribute: responseReason Presence Definition Data Type Format Compliance : Mandatory : Description of the response code sent by the Biller BBPOU. : Code Set : Min Length – 1, Max Length – 50 : Response reason should be sent per the response code list shown below. Response Code 000 001 Response Reason SUCCESS No Transaction found / Complaint not found Attribute: complaintId Presence Definition Data Type Format Compliance : Conditional : Complaint ID generated by BBPCU to check the complaint status, re-assign or close a complaint subsequently. : Alphanumeric : Fixed Length – 15 : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 119 Attribute: assigned Presence Definition Data Type Format Compliance : Conditional : Name of BBPOU to which the complaint is assigned. : Alphanumeric Special : Min Length – 1, Max Length – 100 : The BBPOU should present in the BBPCU system. Attribute: openComplaint Presence Definition Data Type Format Compliance : Conditional : Flag indicating if the transaction based complaint being raised is currently open in the system or not – "Y" will show the details for the complaint raised earlier. : Code Set : Fixed Length – 1 : Accepted values are "Y" or "N". Attribute: complaintStatus Presence Definition Data Type Format Compliance : Conditional : It denotes the complaint status of the transaction. : Code Set : Min Length – 1, Max Length – 50 : Complaint status should be sent per the below mentioned table. Code Assigned Escalated Re Assigned Assigned to COU / Assigned to BOU / Assigned to OU Resolved Unresolved Definition A customer has raised a complaint at an agent outlet or on the BBPS website, and a Complaint ID has been assigned to it. By default, it is assigned to the Customer BBPOU. At this stage, the Customer BBPOU may assign the complaint to the Biller BBPOU depending on the details of the complaint. If the BBPOU does not respond to the complaint within the specified TAT, the complaint gets escalated. When Customer BBPOU re assigned the complaint to the Biller BBPOU. 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. Once the BBPOU resolves the customer related complaint, the BBPOU updates the system. If the BBPOU does not respond to the complaint within the specified TAT (Super escalation), the complaint status changed to unresolved. Attribute: remarks Presence Definition Data Type Format Compliance : Conditional : Last updated additional information provided by the BBPOU pertaining to the complaint and fetched in the complaint status check (506) response. : Alphanumeric Special : Min Length – 1, Max Length – 100 : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 120 Element: Presence Definition : Conditional : List of transactions containing the details of transactions linked to a mobile number and date range combination. Element: Presence Definition : Conditional : Record containing the details of a single transaction. Attribute: txnReferenceId Presence Definition Data Type Format Compliance : Conditional : Transaction reference number used by the Customer for referring to a payment transaction. : Alphanumeric : Fixed Length – 12 or 20 i) Originating Institution ID (Customer OU Id or Participating AI Id) - 04, Random alphanumeric - 08 ii) Originating Institution ID (Customer OU Id or Participating AI Id) - 04, Julian Date - 04 and Random alphanumeric - 12 : Data format and type. Attribute: amount Presence Definition Data Type Format Compliance : Conditional : Amount (in paise) involved in the payment transaction. : Numeric : Min Length – 1, Max Length – 18 : Data format and type. Attribute: txnDate Presence Definition Data Type Format Compliance : Conditional : Date of the bill payment transaction. : ISODateTime : Fixed Length – 25 i.e., YYYY-MM-DDThh:mm:ss+hh:mm (e.g. 2017-02-14T13:10:15+05:30) Where, YYYY = four-digit year MM = two-digit month number (01 indicates January, etc.) DD = two-digit day of month (01 through 31) T = separator used between date and time hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) +hh:mm = time zone difference from GMT in hours and minutes. The default value of this attribute is assumed to be IST (+05:30). : Data format and type. BBPS API SPECIFICATIONS | Version 13.0 121 Attribute: agentId Presence Definition Data Type Format Compliance : Conditional : Agent ID of the Agent involved in the transaction. : Alphanumeric : Fixed Length – 20, e.g. OU01OU02INT000000001 Where,  Customer BBPOU ID – 4  Agent Institution ID – 4  Agent Payment Channel Code – 3  Random number – 9 : Data format and type. Attribute: billerId Presence Definition Data Type Format Compliance : Conditional : Biller ID of the Biller involved in the transaction. : Alphanumeric : Fixed Length – 14, e.g. TATAPWR00DEL01 Where,  Short identifier of the biller (may be augmented with trailing zeroes) - 9  Coverage - 3  Random number - 2 : Data format and type. Attribute: txnStatus Presence Definition Data Type Format Compliance : Conditional : Status of the transaction – successful or failure. : Code Set : Min Length – 1, Max Length – 50 : Data format and type. Element: Presence Definition : Conditional : Details of the customer for a successful transaction search (401) response. Attribute: mobile Presence Definition Data Type Format Compliance : Conditional : Mobile number linked to the transaction(s). : Numeric : Minimum Length – 6, Maximum Length - 20 : Data format and type. Element: Presence Definition : Optional : Search the Biller details associated or non-associated with the BBPOU initiating the request. BBPS API SPECIFICATIONS | Version 13.0 122 Attribute: mybiller Presence Definition Data Type Format Compliance : Conditional : Flag indicating request for the Biller details associated or non-associated with the BBPOU initiating the request. : Code Set : Min Length – 2, Max Length – 3 : Accepted values are "Yes" or "No". Element: Presence Definition : Optional : Search the Biller or Agent details based on certain parameters. Element: Presence Definition : Conditional : Biller ID for which the Biller details are requested. Element: Presence Definition : Conditional : Agent ID for which the Agent details are requested. Element: Presence Definition : Optional : Searching the Biller or Agent details based on time parameter. Element: Presence Definition : Conditional : Request for Biller or Agent details for all the Billers or Agents updated in the system after the time provided. Element: Presence Definition : Conditional : MDM details of the Biller. Element: Presence Definition : Mandatory : Identifier of the Biller. Element: Presence Definition : Mandatory : Name of the Biller. BBPS API SPECIFICATIONS | Version 13.0 123 Element: Presence Definition : Mandatory : Alias name of the Biller. Element: Presence Definition : Mandatory : Biller category. Element: Presence Definition : Mandatory : Biller mode, i.e., Online, Offline A, Offline B. Element: Presence Definition : Mandatory : Flag indicating if the Biller accepts adhoc payment. Element: Presence Definition : Mandatory : Flag indicating if the Biller is a parent Biller. Element: Presence Definition : Conditional : Identifier of the parent Biller. Element: Presence Definition : Mandatory : Biller ownership, i.e., Government, PSU, Private. Element: Presence Definition : Mandatory : Coverage of the Biller, i.e., National, State/UT, City/District. Element: Presence Definition : Mandatory : Indicates if the Biller allows Bill Fetch or not – possible values are MANDATORY, OPTIONAL, NOT_SUPPORTED. Element: Presence : Mandatory BBPS API SPECIFICATIONS | Version 13.0 124 Definition : Indicates if the Biller allows Bill Validation or not – possible values are MANDATORY, OPTIONAL, NOT_SUPPORTED. Element: Presence Definition : Conditional : Indicates if the Biller (having Mandatory Bill Fetch) allows exact payment or not – possible values are Exact, Exact and above, Exact and below. Element: Presence Definition : Mandatory : Effective from date of the Biller. Element: Presence Definition : Mandatory : Effective to date of the Biller. Element: Presence Definition : Mandatory : Temporary deactivation start date of the Biller. Element: Presence Definition : Mandatory : Temporary deactivation end date of the Biller. Element: Presence Definition : Mandatory : Payment mode details of the Biller. Element: Presence Definition : Mandatory : Payment modes supported by the Biller. Element: Presence Definition : Conditional : Maximum limit accepted by a Biller for a particular payment mode. Element: Presence Definition : Mandatory : Minimum limit accepted by a Biller for a particular payment mode. BBPS API SPECIFICATIONS | Version 13.0 125 Element: Presence Definition : Conditional : Flag indicating whether Pending Status is applicable for the payment mode or not – Yes/No. Element: Presence Definition : Mandatory : Payment channel details of the Biller. Element: Presence Definition : Mandatory : Payment channels supported by the Biller. Element: Presence Definition : Conditional : Maximum limit accepted by a Biller for a particular payment channel. Element: Presence Definition : Mandatory : Minimum limit accepted by a Biller for a particular payment channel. Element: Presence Definition : Conditional : Flag indicating whether Pending Status is applicable for the payment channel or not – Yes/No. Element: Presence Definition : Mandatory : Customer parameter details of the Biller. Element: Presence Definition : Mandatory : Customer parameter name. Element: Presence Definition : Mandatory : Customer parameter data type. Element: Presence Definition : Mandatory : Flag indicating if the Customer parameter is optional. BBPS API SPECIFICATIONS | Version 13.0 126 Element: Presence Definition : Conditional : Minimum length of the Customer parameter. Element: Presence Definition : Conditional : Maximum length of the Customer parameter. Element: Presence Definition : Conditional : Regular expression (RegEx) is a string of characters representing permissible values of the customer parameters for a biller. Element: Presence Definition : Conditional : Default (possible) values list against a Customer Parameter. Element: < biller.customerParamGroups> Presence Definition : Conditional : Customer Parameter Groups with respect to the various combinations supported. Element: < biller.customerParamGroups.group> Presence Definition : Conditional : Customer Parameter Group. Element: < biller.customerParamGroups.group.name> Presence Definition : Conditional : Name of the Parent/Sub-Group. Element: < biller.customerParamGroups.group.input> Presence Definition : Conditional : Flag indicating the required number of tags from the group. Element: < biller.customerParamGroups.group.param> Presence Definition : Conditional : Customer parameter name. Element: Presence Definition : Mandatory : Biller Responses with respect to the various amount combinations supported. BBPS API SPECIFICATIONS | Version 13.0 127 Element: Presence Definition : Mandatory : Amount options supported by the Biller. Element: Presence Definition : Mandatory : Amount combination for a particular amount option. Element: Presence Definition : Conditional : Additional information details provided by the Biller. Element: Presence Definition : Conditional : Additional information parameter name. Element: Presence Definition : Conditional : Additional information parameter data type. Element: Presence Definition : Conditional : Flag indicating if the additional information parameter is optional. Element: Presence Definition : Mandatory : Interchange fee configuration details of the Biller. Element: Presence Definition : Mandatory : Message Type Indicator for the fee, i.e., fetch, payment, etc. Element: Presence Definition : Mandatory : Response code associated with the fee. Element: Presence Definition : Conditional : Payment mode associated with the fee. BBPS API SPECIFICATIONS | Version 13.0 128 Element: Presence Definition : Conditional : Payment channel associated with the fee. Element: Presence Definition : Mandatory : Fee codes for applicable interchange fee. Element: Presence Definition : Mandatory : Flag indicating if it is a default fee or not. Element: Presence Definition : Mandatory : Effective from date for the fee. Element: Presence Definition : Mandatory : Effective to date for the fee. Element: Presence Definition : Mandatory : Interchange fee details of the Biller. Element: Presence Definition : Mandatory : Fee code associated with the Biller. Element: Presence Definition : Mandatory : Description of the corresponding fee code. Element: Presence Definition : Mandatory : Direction of fee movement, i.e., Customer BBPOU to Biller BBPOU or vice-versa. Element: Presence Definition : Mandatory : Interchange fee details pertaining to range, type and validity. BBPS API SPECIFICATIONS | Version 13.0 129 Element: Presence Definition : Mandatory : Maximum range for a particular fee configuration. Element: Presence Definition : Mandatory : Minimum range for a particular fee configuration. Element: Presence Definition : Mandatory : Percentage fee details. Element: Presence Definition : Mandatory : Flat fee details. Element: Presence Definition : Mandatory : Effective from date for the fee configuration. Element: Presence Definition : Mandatory : Effective to date for the fee configuration. Element: Presence Definition : Mandatory : Status of the Biller, i.e., active, deactivated, etc. Element: Presence Definition : Optional : Additional information related to Billers. Element: Presence Definition : Optional : Flag indicating whether deemed success is applicable for the biller or not – Yes/No. Element: Presence Definition : Optional : Flag indicating whether pending status is applicable for the biller or not – Yes/No. BBPS API SPECIFICATIONS | Version 13.0 130 Element: Presence Definition : Conditional : MDM details of the Agent. Element: Presence Definition : Mandatory : Identifier of the Agent. Element: Presence Definition : Mandatory : Business type of the Agent. Element: Presence Definition : Mandatory : Name of the Agent. Element: Presence Definition : Mandatory : Alias name of the Agent. Element: Presence Definition : Mandatory : Code of the Agent Institution associated with the Agent. Element: Presence Definition : Mandatory : Agent geo-location. Element: Presence Definition : Mandatory : Shop name of the Agent. Element: Presence Definition : Mandatory : Mobile number of the Agent. Element: Presence Definition : Mandatory : Flag indicating if the Agent represents an electronic or physical channel. BBPS API SPECIFICATIONS | Version 13.0 131 Element: Presence Definition : Mandatory : Payment mode details of the Agent. Element: Presence Definition : Mandatory : Payment modes supported by the Agent. Element: Presence Definition : Conditional : Maximum limit accepted by an Agent for a particular payment mode. Element: Presence Definition : Mandatory : Minimum limit accepted by an Agent for a particular payment mode. Element: Presence Definition : Mandatory : Payment channel details of the Agent. Element: Presence Definition : Mandatory : Payment channels supported by the Agent. Element: Presence Definition : Conditional : Maximum limit accepted by an Agent for a particular payment channel. Element: Presence Definition : Mandatory : Minimum limit accepted by an Agent for a particular payment channel. Element: Presence Definition : Mandatory : Flag indicating if the Agent is configured through bulk upload feature in BBPS Canvas (intranet portal). Element: Presence Definition : Mandatory : ID used by a BBPOU / Agent Institution to internally identify an Agent. BBPS API SPECIFICATIONS | Version 13.0 132 Element: Presence Definition : Mandatory : PIN Code of the Agent. Element: Presence Definition : Mandatory : Registered city of the Agent. Element: Presence Definition : Mandatory : Registered state of the Agent. Element: Presence Definition : Mandatory : Registered address of the Agent. Element: Presence Definition : Mandatory : Registered country of the Agent. Element: Presence Definition : Mandatory : Effective from date of the Agent. Element: Presence Definition : Mandatory : Effective to date of the Agent. Element: Presence Definition : Mandatory : Temporary Deactivation Start date of the Agent. Element: Presence Definition : Mandatory : Temporary deactivation end date of the Agent. Element: Presence Definition : Mandatory : Status of the Agent, i.e., active, deactivated, etc. BBPS API SPECIFICATIONS | Version 13.0 133 23 Appendix 23.1 List of Error Messages ErrorCodeWithMessa ges v5.0.xlsx 23.2 File Naming Convention for Settlement Files Naming Convention for BBPS Settlement Files v2.0.docx BBPS API SPECIFICATIONS | Version 13.0