Collection API - BBPS

Why BBPS?

BBPS is one of the most popular digital platforms for bill payments in India. It has the largest ecosystem to support cash and all recurring digital payment modes.

Our simplified BBPS integration allows you to become available as a business on any UPI or banking app. Additionally, this integration gives access to 3.5 million offline touchpoints, serving 10k+ locations across India.

How can this product help you?

We will help you get registered as a Biller(add biller definition link) on BBPS by signing up with our bank partners. Instantly become available on all UPI, banking apps and offline channels. Kaleidofin will be your technology partner throughout the entire customer collections journey.

Payment app - Customer journey

Customer looks up a biller from a categorized section of billers.
Enters a unique identifier that retrieves their specific bills.
Selects bill and makes a payment.

APIs to implement

List of minimal APIs that needs to implement to become part of bbps

Generate Bill

API to validate the customer account details and fetch bills.

Header Parameters

POST <partner domain> /bills/fetchBills

Request body scheme: application/json

Input Parameters

Array of object (Bill Identifier) - List of parameters to uniquely identify a customer.

"identifierKey"

string Name of the identifier

"identifierValue"

string Value of the identifier

Sample Copy


										[
											{
												"identifierKey":"name",
												"identifierValue":"vishakha"
											},
											{
												"identifierKey":"customerId",
												"identifierValue":"AY1234"
											}
										]

Response schema

"billName"

string Purpose of the payment to be populated in the Payment Link.

"billAmount"

number Due amount as per bill

"partnerBillId"

string Unique bill identifier provided by the biller.

"dueDate"

string Due date of the bill in the YYYY-MM-DD, upto seconds precision.

"generatedDate"

string Bill generated date in YYYY-MM-DD, upto seconds precision.

"amountExactness"

ENUM(EXACT|ANY) Amount to be paid by customer

Responses Copy


{
  "data": {
    "billFetchStatus": "AVAILABLE",
    "customerBills": {
      "bills": [
        {
          "billName": "JuneInstallment",
          "billAmount": 1000,
          "partnerBillId": "TESTING-002",
          "dueDate": "2020-09-01",
          "generatedDate": "2020-08-01",
          "amountExactness": "EXACT"
        },
        {
          "billName": "JulyInstallment",
          "billAmount": 1200,
          "partnerBillId": "TEST-124",
          "dueDate": "2020-08-15",
          "generatedDate": "2020-08-01",
          "amountExactness": "EXACT"
        }
      ]
    },
    "customer": {
      "info": {
        "name": "Vishakha",
        "phoneNumber": "7706057010",
        "consumerId": "AY1234"
      },
      "name": "Vishakha"
    }
  },
  "status": 0,
  "success": true
}

Acknowledge Bill Payment

API to response to bill payment acknowledgement with a receipt.

Header Parameters

POST <partner domain> /bills/fetchReceipt

Request body scheme: application/json

Input Parameters

Object(BillPaymentAcknowledgement) – Bill Payment Acknowledgement details.

"systemBillId"

number Bill id in kaleidofin’s system

"partnerBillId"

string Bill id provided at the time of fetching bill

"billAmount"

number Due amount as per bill

"amountPaid"

number Amount paid by customer

"transactionId"

string Transaction Id provided by BBPS

Sample Copy


										{
										  "systemBillId": 14,
										  "partnerBillId": "SAMPLE_ID",
										  "paymentDetails": {
											"billAmount": 1000,
											"amountPaid": 1000,
											"transactionId": "20201223246869"
										  }
										}

Response schema

"date"

string YYYY-MM-DD, upto seconds precision.

"id"

string Unique receipt Id for payment

Responses Copy


									{
									  "data": {
										"receipt": {
										  "date": "2020-08-31T06:06:55Z",
										  "id": "R0123"
										}
									  },
									  "status": 0,
									  "success": true
									}

APIs to call

Check Bill Status

List of APIs to be called by OU to fetch outstanding bills, sending payment details and to check bill status.

Fetch Bills for Customer

API to fetch bills for a given partner based on the details provided by the user.

Header Parameters

POST <kaleidofin’s fetch bills url> /{billerId}

Request body scheme: application/json

Input Parameters

Array of object(Bill Identifier) - List of parameters to uniquely identify a customer.

"identifierKey"

string Name of the identifier

"identifierValue"

string Value of the identifier

Sample Copy


										[ 
											{ 
											"identifierKey":"name", 
											"identifierValue":"vishakha" 
											}, 
											{ 
											"identifierKey":"consumerId", 
											"identifierValue":"AY1234" 
											} 
										]

Response schema

"systemBillId"

number Purpose of the payment to be populated in the Payment Link.

"partnerBillId"

string Unique bill identifier provided by the biller.

"dueDate"

string Due date of the bill in the YYYY-MM-DD, upto seconds precision.

"generatedDate"

string Bill generated date in YYYY-MM-DD, upto seconds precision.

"billStatus"

string Status of the bill

"billAmount"

number Bill amount of the particular month

"billName"

string Purpose of the payment to be populated in the Payment Link.

"customerName"

string Name of the customer

Responses Copy


										{ 
											    "success": true, 
											    "statusCode": "0", 
											    "statusMessage": "Success", 
											    "bills": [ 
											        { 
											            "systemBillId": 18, 
											            "partnerBillId": "TESTING-002", 
											            "dueDate": "2020-09-01", 
											            "generatedDate": "2020-08-01", 
											            "billStatus": "BILL_CREATED", 
											            "billAmount": 1000, 
											            "billName": "June Installment", 
											            "customerName": "Vishakha" 
											        }, 
											        { 
											            "systemBillId": 17, 
											            "partnerBillId": "TEST-124", 
											            "dueDate": "2020-08-15", 
											            "generatedDate": "2020-08-01", 
											            "billStatus": "BILL_CREATED", 
											            "billAmount": 1200, 
											            "billName": "July Installment", 
											            "customerName": "Vishakha" 
											        } 
											    ] 
											}

Status API

API to check status of a bill in kaleidofin’s system

Header Parameters

GET <kaleidofin’s status bills url>/{systemBillId}

Request body scheme: application/json

Response schema

"systemBillId"

number Unique bill identifier in the biller's system.

"receipt"

string Recipt for the payment

"billStatus"

string enum: 'BILL_CREATED' 'PAYMENT_SUCCESSFUL' 'PAYMENT_FAILED' 'PAYMENT_SUCCESSFUL' 'CREDIT_RECEIVED' 'SETTLEMENT_FAILED' 'SETTLEMENT_SUCCESSFUL' 'BILL_EXPIRED'

Current status of bill in Kaleidopay.

Responses Copy


									{ 
										"success": true, 
										"statusCode": "0", 
										"statusMessage": "Successful", 
										"billStatus": { 
											"systemBillId": 15, 
											"billStatus": "BILL_CREATED", 
											"receipt": null 
										} 
									}

Payment API

API to be called by OU to update the payment status on successful payment made by a customer against a bill.

Header Parameters

POST <kaleidofin’s payment bills url>

Request body scheme: application/json

Input Parameters

Input parameters for payment status

"systemBillId"

number Unique bill identifier provided by the biller.

"transactionId"

string Unique transaction reference ID for a payment in the payer app system.

"paymentDate"

string payment date in YYYY-MM-DD, upto seconds precision.

"amountPaid"

number Bill amount of the particular month

Sample Copy


										{ 
											"systemBillId":19, 
											"transactionId":"127829461946", 
											"amountPaid":1000, 
											"paymentDate":"2020-07-30" 
										}

Response schema

"systemBillId"

number Unique bill identifier in the biller's system.

"receipt"

string Receipt for the payment

"billStatus"

string enum: 'BILL_CREATED' 'PAYMENT_SUCCESSFUL' 'PAYMENT_FAILED' 'PAYMENT_SUCCESSFUL' 'CREDIT_RECEIVED' 'SETTLEMENT_FAILED' 'SETTLEMENT_SUCCESSFUL' 'BILL_EXPIRED'

Current status of bill in Kaleidopay.

Responses Copy


									{ 
										"success": true, 
										"statusCode": "0", 
										"statusMessage": "Successful", 
										"billStatus": { 
											"systemBillId": 19, 
											"billStatus": "PAYMENT_SUCCESSFUL", 
											"receipt": "R0123" 
										} 
									}