BBPS Biller APIs

BBPS Biller API Document v1.0

BBPS Solution for Billers

Introduction

Payout Fintech APIs are organised around REST. Our API has predictable resource-oriented URLs, accepts JSON requests and returns JSON response, and uses standard HTTP response codes and verbs.

Pass API content-type for all the requests in the header.

  • content-type: application/json

Authentication and Security

Following options are optional but highly recommended.

Client(Biller) has to develop the API based on the specification, Payout Fintech consumes the API. To secure the API from unauthorised access, we recommend using any of the following authentication methods in your API. We support bearer authentication and basic authentication. We recommend developing your API with any one of the authentication methods and share the credentials with us so our system will invoke your API with the authentication method and credentials.

Our system will invoke your API from the predefined IPs, for security reasons we recommend whitelisting our IPs.

BBPS Fetch API

Fetch API will be invoked by our system, when a customer fetches from third-party PSP Apps or Bank Apps. It is a real time API call, your API should respond in a timely manner to fulfil the Fetch API request. If your system does not respond with the expected response within the agreed timeframe our system will consider it as failure. Due to the nature of the API call retry is not possible. For the API call your system has to return invoice dues as per the below specification.

  • URL: Client have to provide
  • Method: POST
  • Header: { Content-Type: application/json }
  • Retry: N/A.

Request

Parameters Datatype Required Description
key string Y Unique identifier to fetch the bill Ex: Consumer No., Customer ID
billerId string Y Biller for each client we will provide unique billerId

Response

Parameters Datatype Description
key string Unique identifier to fetch the bill Ex: Consumer No., Customer ID
billerId string Biller for each client we will provide unique billerId
customerName string Name of the customer for the bill
amount number Bill amount
billDate string Bill date
dueDate string Due date of the bill
billNumber string Bill Number
billPeriod string Bill Period. The value should be

MONTHLY

QUARTERLY

HALFYEARLY

YEARLY

Example

Request

{

   "key" :   "9000000123",

   "billerId" :   "BILLERID001"

}

Success Response

{

   "code" :   "SUCCESS",

   "data" : {  

"key" :   "9000000123",

"billerId" :   "BILLERID001",

"customerName" :   "Demo",

"amount" :   "2500",

"billDate" :   "2022-09-28",

"dueDate" :   "2022-10-28",

"billNumber" :   "12312312",

"billPeriod" :   "MONTHLY"

}

}

Failure Response for Customer Not Found

{

   "code" :   "NOT_FOUND"

}

Failure Response for No Dues

{

   "code" :   "NO_DUES"

}

Other Failure Response

{

   "code" :   "FAILURE"

}

BBPS Payments Notification API

After the successful customer payment, our system will invoke your Payment Notification API. It means a customer has made the payment which was acknowledged by the BBPS system. Our system will send the payment confirmation details including invoice numbers so your API has to update the payment information and acknowledge as per the below specification.

  • URL: Client need to provide
  • Method: POST
  • Header: { Content-Type: application/json }

Request

Parameters Datatype Description
bbpsRefNo string bbpsRefNo for the transaction
customerName string customerName for the transaction
mode string Mode for the transaction
amount number Amount for the transaction
fee number Returns the fee for the transaction
tax number Returns the tax for the fee
totalFee number Returns the sum of fee and tax
netAmount number Actual amount after deducting fee and tax
paysharpReferenceNo string Payment reference number for the transaction
transactionDate datetime Transaction date
attemptCount number Number of times the webhook invoked(Only returned for webhook response)
key string Unique identifier to fetch the bill Ex: Consumer No., Customer ID

Response

Parameters Datatype Description
message string Message for the transaction
code string code for the transaction

Example

This request will be provided by Payout Fintech

Request

{

"bbpsRefNo" :   "st559526",

"customerName" :   "Demo",

"mode" :   "Internet Banking",

"amount" :   2500,

"fee" :   1,

"tax" :   0.18,

"totalFee" :   1.18,

"netAmount" :   2498.82,

"paysharpReferenceNo" :   "pbb_efe54d72wGLn2Xh3tdzwiR",

"transactionDate" :   "2022-09-21T11:50:37.787Z",

"attemptCount" :   1,

"key" :   "7824800800"

}

Response Success case

{

   "message" :   "success",

   "code" :   200

}