#BBPS BillCollect

#What is BBPS?

BBPS, or the Bharat Bill Payment System, facilitates the collection of various payments encompassing utility bills, loan EMIs, school fees, and more. It accommodates cash and digital payments through 400+ digital applications and 3.5 million offline touchpoints.

Join as a biller to list your bills on BBPS.

#Who is a Biller?

A biller refers to any business that issues invoices for products or services offered to customers and intends to receive payments using BBPS.

#What functionalities are offered by this product?

Accept payments via 400+ UPI and banking applications like PhonePe or GPay, and also gain exposure on offline channels.

[Website Name] delivers API integrations and settlement services for this product.

Integration Time: 3 days

Go-Live Time: 1 to 5 weeks .

#How it works

Here are the steps involved in receiving payments from a customer. Let's consider the example of a borrower repaying a loan to a lender. In this case, the lender is the Biller partner integrated with [website name].

1. The customer opens their preferred UPI or banking application and clicks on “Loans.”
2. A list of lenders is displayed, and the customer selects their specific lender.
3. The customer verifies their identity by entering their loan number or mobile number, which the lender recognizes as a customer identifier. (See: fetchCustomerBills↗)fetchCustomerBills↗
4. The customer reviews the repayment amount and proceeds with the payment. Note: The interface displays the precise amount to be paid, but we also support partial payments with customized validation.
5. The app prompts the customer to choose the payment method, such as UPI.
6. The customer inputs the UPI mPIN to make the payment from their preferred bank account.
7. The payment is processed, verified in line with the biller's validations, and settled to the biller's account on T+2.

#Quickstart for BillCollect

The onboarding process for BBPS BillCollect is summarized below.

#Step 1 — Initiate KYC and Business Documentation

This phase begins subsequent to the interaction with [website name]'s Sales team, upon confirming the integration. You will be required to provide specific details and undergo an agreement review process:

1. Submit essential KYC and business contact particulars, which vary depending on your business category.
2. Review and authenticate the consent form needed for BBPS integration.
3. Authorize the required legal agreements—comprising the SOP agreement with [website name] and the Pricing agreement.

#Step 2 — Select Integration Approach

(Website Name) will furnish a technical onboarding form to gather all BBPS BillCollect integration details. You have the following integration options to choose from:

No-code CSV Integration

Refer to the CSV quickstart for further instructions.

• No API integration required—bill details are provided by (Website Name) for bill fetch and payment.
• Upload customer bills in CSV format as provided by (Website Name).

API Integration

Refer to the API quickstart for detailed instructions.

• Integrate using bill fetch and bill pay APIs.
• Share the most recent customer bill information via APIs.

#Step 3 — Go Live

Submit your configuration for review in the Go Live section. [Website Name] will approve your configuration once it has been approved.

#No-code CSV integration

[Website Name]'s BBPS BillCollect simplifies onboarding billers onto BBPS without requiring the implementation of APIs from their end. Through a predefined CSV format, you can seamlessly upload your customers' bills.

Explore a detailed comparison between CSV upload and API integration here .

#How to integrate

Begin the integration process by registering on The Bridge ↗, (Website Name)'s unified platform for handling all your integrations with us.

#Step 1 — Establish a biller on The Bridge

Navigate to the Available products section using the sidebar and choose one of the Collect BBPS cards located under the Payments tab. Click on the Create a Biller button. When creating your biller, ensure that you opt for the CSV upload method.

#Incorporating Configuration on The Bridge

Following the creation of the biller, you'll be directed to the biller profile page where you'll encounter four primary tabs: Dashboard, offering an overview; Configuration, housing integration specifics for the biller; Transactions, showcasing test payments directed to this biller; and Copy to Production, facilitating the replication of the configuration to the Production environment later on.

Navigate to the Configuration tab within the biller profile. It is essential to input both biller and bill details before proceeding to set up the integration. The specific customer identifiers entered will determine the format required for the CSV.

• Attribute name refers to the variable or parameter recognized by your system as the unique customer identifier. Ensuring this name corresponds with the column containing customer identifier data in your CSV file is crucial.

• Attribute displayed as is what the user will view in payment applications like PhonePe or GPay.

• Length indicates the allowable range of characters a customer can input for the identifier, encompassing both the minimum and maximum limits.

• Regex / pattern serves to validate whether the customer's entered identifier is accurate or not.

You have the flexibility to define up to four customer identifiers.

#Step 3 — Prepare CSV file for bills

Proceed to the integration (Website Name)p section and find a sample CSV generated according to the customer identifiers you previously entered in the Bill details section. You have the option to modify the column names if necessary.

After confirming the column names in the CSV file, download the provided sample and incorporate all your customer bills into this file.

#Step 4 — Upload bills in CSV file

Proceed to the Dashboard tab and access the Upload CSV section. Place the CSV file containing your customer bills in the drag-and-drop area.

You can monitor the upload progress from the panel on the right-hand side. The panel displays a log of previously uploaded CSV files, with the latest appearing at the top.

Once the CSV upload is completed, the system will display the number of bills that were successfully uploaded and saved.

#Upload another CSV file with bills

You can add new bills to the system in the same way as described above. When you upload a CSV file, bills with new customer identifiers will be appended to existing bill data.

#API Integration

Begin by registering on The Bridge ↗, our comprehensive platform for managing all your connections with us.

Should you encounter any difficulties during the integration process, please submit a support ticket ↗, and our team will promptly assist you.

#Platform (Website Name)p Process

Step 1 — Establish a Biller

The principal entity within the BBPS network is termed a "biller." Navigate to the assortment of products provided by (Website Name), and opt for one of the product cards under Payments > Collect BBPS.

Several Collect BBPS cards are available, each associated with a distinct banking provider. Although the bank might vary, the overall product experience remains uniform across providers. Click on one of these cards to access the detailed profile page, offering further insights into the product. Subsequently, select the "Create a biller" button.

Enter the biller's name in the provided field. This name will be visible to your customers in payment applications, so ensure its accuracy.

Following this, choose the category that best aligns with the biller. Presently, (Website Name) supports only two categories, but the platform intends to introduce additional categories soon. After completing these selections, click on the "Create biller" button.

Congratulations! The biller has been successfully created, allowing you to proceed to the biller dashboard.

Step 2 — Adding Product Configuration

After completing the biller creation, you will be directed to the biller's profile. This page encompasses four tabs:

Click on the "Configuration" tab to initiate the (Website Name)p for your biller. To ensure a comprehensive configuration, you'll need to:

• Add at least one customer identifier: This identifier assists payment apps in recognizing a specific customer to retrieve their bills from the biller system. For instance, a customer's loan number could be utilized to access their EMI payment.
• Set up URLs: These are used to direct (Website Name) on where to retrieve the bills from your system and specify the authentication mechanism. You also have the option to establish a callback URL to receive notifications.
• Add settlement accounts: These accounts are designated for receiving funds from (Website Name) once customers have successfully made a payment. In the Sandbox environment, these transactions are solely for mock purposes.

Adding Customer Identifiers:

Start by establishing at least one identifier: An app like PhonePe or GPay will prompt your customer to input a value for this identifier, unique to them, enabling them to retrieve their specific bill.

Attribute name is what your system recognises as the identifier to uniquely identify a customer.

Displayed as is what the user would see in an app like PhonePe or GPay.

Length denotes the minimum and maximum characters the customer can enter for the identifier.

Regex / pattern helps to check if the identifier entered by the customer is valid or not.

Once you enter these values, you can save it, and add another if you wish.

Add URL endpoints

Configure the baseURL, which allows (Website Name) to retrieve bills and receipts from the biller system.

Your biller must expose the following web APIs:

• fetchCustomerBills ↗: Utilized to share a customer's bill(s) with the BBPS system.
• fetchBillReceipt ↗: Used to generate and access a receipt for a customer's payment. These APIs will be invoked by BBPS through the (Website Name) platform. Further details on implementing these APIs have been provided below.

The callbackURL is specifically designated for (Website Name) to dispatch notifications regarding BILL_SETTLEMENT_STATUS events exclusively. If you opt to implement this feature, more information is available here .

The callbackURL is for Website Name to send notifications for BILL_SETTLEMENT_STATUS event only. If you want to implement this, read more here.

Setup the baseURL along with its auth scheme. Depending on the scheme you select, you would need to provide the corresponding credentials.

If you require notifications along with every settlement event, then setup the callbackURL as well.

Add settlement account(s)

Settlement accounts are the destinations where (Website Name) transfers funds after a customer has completed their payment. It's important to note that in the Sandbox environment, these accounts are simulated and do not involve any actual monetary transactions.

Add the account holder’s name, account number and IFSC. You can also add multiple accounts, and have funds split between them based on settlement instructions. Read more here.

#APIs to facilitate:

Retrieve customer bill

This entails a multi-leg transaction involving BBPS, (Website Name), and the biller system.

BBPS communicates with (Website Name) by providing customer identifier(s) details entered by a customer on a BBPS enabled app or offline collection point.

(Website Name) communicates with the biller using the same details and the API to obtain the fetch bill ↗ subsequently sharing it with BBPS.

The biller’s API URL is expected to be in the following format—

https://<partner-base-api-url>/bills/fetch
                                            

The request body will specify the customer identifier—

{
      "customerIdentifiers": [
        {
          "attributeName": "customerId",
          "attributeValue": "9117534711"
        }
      ]
}

Note:

• customerId is defined as per biller's use case, such as loanNumber, studentId, etc

Response scenarios

When BBPS sends a fetch bill request to (Website Name), (Website Name) forwards the request to biller specified baseURL. (Website Name) expects to receive a response from the biller system, with three possible scenarios—

• Success, with outstanding bill for customer
• Identifier matched, but no outstanding bill for customer
• Failure, no customer found

Scenario 1: Success, with outstanding bill for customer

This is when the customer is present in the biller system, and has outstanding bills. In this case, the biller can return a 200 response—

{
  "data": {
    "customer": {
      "name": "Sharmaji Ka Beta",
      "additionalInfo": [
        {
          "EMI Amount": "900"
        },
        {
          "Charges": "100"
        }
      ]
    },
    "billDetails": {
      "bills": [
        {
          "items": [],
          "generatedOn": "2022-06-07T05:18:02.234Z",
          "customerAccount": {
            "id": "9117534711"
          },
          "recurrence": "ONE_TIME",
          "aggregates": {
            "total": {
              "amount": {
                "value": 100000, // in paise
                "currencyCode": "INR"
              },
              "displayName": "Total Receivable"
            }
          },
          "billerBillID": "891234567",
          "amountExactness": "EXACT"
        }
      ],
      "billFetchStatus": "AVAILABLE"
    }
  },
  "status": 200,
  "success": true
}

Note

• additionalInfo items will be displayed in the Payment App/site which can describe additional information about the bill.
• items are used to show details about the bill / itemized break up. Maximum of 4.
• generatedOn and dueDate must adhere to the
  following guidelines from NPCI
  • generatedOn should not be greater than dueDate
  • generatedOn should not be a future date
  • dueDate should not be equal to generatedOn

  ---

  Scenario 2: Identifier matched, but no outstanding bill for customer

  When a customer is identified in the biller system but has paid all bills, and so, has no outstanding bill amount. In this case, the biller can return a 200 response—

  Copy

  {
        "data": {
          "billDetails": {
            "billFetchStatus": "NO_OUTSTANDING",
            "bills": []
          },
          "customer": {
            "name": "Sharmaji Ka Beta"
          }
        },
        "success": true,
        "status": 200
  }

  
  

  The dueDate can be the last payment date from the customer or the current timestamp.

  ---

  Scenario 3: Failure, no customer found

  Either the biller does not recognise the parameter, or there are no customers with that particular parameter. Then, the biller can return a 400 response—

  Copy

  {
        "success": false,
        "status": 400,
        "error": {
          "traceID": "XXXXXX",
          "code": "customer-not-found",
          "docURL": "",
          "detail": "A customer with the provided credentials does not exist in the biller system.",
          "title": "customer-not-found"
        }
  }

  
  

  ---

  Retrieve payment receipt for a bill

  This involves a multi-leg transaction among BBPS, (Website Name), and the biller system. Illustrated in the diagram below, BBPS contacts (Website Name), and subsequently, (Website Name) reaches out to the biller through the fetchBillReceipt ↗method.

  

  Upon receiving a payment against a bill, (Website Name) receives a notification and triggers the fetchBillReceipt ↗ API call to the biller system. The biller’s API URL must follow this format—

  Copy

  https://<partner-base-api-url>/bills/fetchReceipt

  
  

  (Website Name) adds the /bills/fetchReceipt at the end of biller provided baseURL.

  
  

  A typical request for a receipt would look something like—

  Copy

  {
        "platformBillID": "906910589572351478",
        "billerBillID": "891234567",
        "paymentDetails": {
          "amountPaid": {
            "value": 1000,
            "currencyCode": ""
          },
          "billAmount": {
            "value": 1000,
            "currencyCode": ""
          },
          "platformTransactionRefID": "26602931-3b6a-4c87-a14d-5d7cf584008f",
          "uniquePaymentRefID": "PP012151MYB616O9BSY1",
          "instrument": "UPI",
          "additionalInfo": null,
          "transactionNote": "",
          "campaignID": ""
        }
  }

  
  

  Once you receive this call—

  1. Create a receipt against uniquePaymentRefID.
  2. Update your ledger to reflect this new balance.
  3. Return a 200 response with id and date.

  Success response

  Copy

  {
        "status": 200,
        "success": true,
        "data": {
          "receipt": {
            "id": "XYZ987-891234567",
            "date": "2022-06-07T05:55:54.789Z"
          }
        }
  }

  ---

  Failure scenarios

  Case 1

  If your system encounters difficulties in accepting or processing payments due to various issues, like use case errors, validation problems, business requirements, or technical errors on the biller server (e.g., server downtime, bad gateway, unavailability, etc.), your response should be a 500 response -

  Copy

  {
      "status": 500,
      "success": false,
      "error": {
          "code": "unable-to-fulfill-request",
          "detail": "An error occured while processing this request.",
          "docURL": "",
          "title": "API_ERROR",
          "errors": [],
          "traceID": "XXXXXX"
      }
  }

  ---

  Note:

  • During the payment request, if your system fails to respond to (Website Name) within 30 seconds or responds with an error, the request to /fetchReceipt will be reattempted with the same request body as the first attempt.
  • It is necessary to implement a duplicate check against the uniquePaymentRefID:
    • If the uniquePaymentRefID doesn't exist for that Transaction, you must update the same and return a 200 Success response
    • If the same uniquePaymentRefID exists in your system for that Transaction, you can return a 200 Success response

  ---

  Security considerations

  1. The API should work from only whitelisted IPs (on production)
  2. HTTPS is mandatory
  3. Authentication mechanism is required. Supported methods—Basic auth, JWT, OAuth.

  ---

  #APIs to call

  Expire Bill (optional)

  The purpose of this API is to promptly change the status of an unpaid link to BILL_EXPIRED. This action prevents the customer from using the link or associated VPA for payment. In the rare instance that the customer can still make a payment using the link (for example, due to app caching or similar issues), the amount will be automatically refunded.

  TheplatformBillID a unique identifier for a bill on (Website Name)'s system, is required for expiring the bill. This information is accessible in the response of the Create Payment Link API.

  Method	POST
  Path	/utilities/bills/<platformBillId>/expire
  Header	X-(website name)-Product-Instance-ID Authorization: Bearer (insert_token_here). Read about how to generate this token here.

  Success

  Copy

  {
      "status"  : 200,
      "success" : true
  }

  Failure

  In case the platformBillID provided is incorrect, (Website Name) will respond with 400 bill not found error—

  Copy

  {
      "status": 400,
      "success": false,
      "error": {
          "code": "bill-not-found",
          "detail": "Bill with ID [<platformBillID>] not found.",
          "docURL": "",
          "title": "PLATFORM_ERROR",
          "errors": [],
          "traceID": "XXXXXX"
      }
  }

  If a bill has been expired, ideally, a payment by a customer would not be allowed, if verify VPA call returns an error on a payment app.

  But if the verify VPA call was not made and the customer makes a payment, payment will go through but will be refunded in the settlement flow.

  ---

  Was this page helpful?

  Yes

  No

#Go Live

Test your integration in the Bridge Sandbox environment to ensure that all components function as intended. After successful testing, you can proceed to the live environment and start accepting payments from real customers.

In case you face an issue with any of the following steps, raise a support ticket ↗ and our team will reach out to you.

#Step 1 — Create Configuration on Production

Initially, ensure you're in the Production environment. Most functionalities in the Production environment are similar to those in the Sandbox environment. You can find more information about environments.

Alternatively, if the details significantly differ, you can create a fresh Production configuration. To switch to the Production environment, click on the environment toggle at the top of the home page. If it's your first time accessing Production, the Configured products section will be empty.

Go to the Products page, choose the required provider under the Collect BBPS section, and begin the configuration process.

#Step 2 — Add Configuration Details

Configuring a biller on Production is identical to the process on Sandbox. For detailed guidance, you can refer to the CSV or API integration quickstart guide.

#Step 3 — Add KYC Details

The Production environment differs from the Sandbox due to its handling of actual monetary transactions. To commence live transactions, additional biller-level KYC procedures need to be fulfilled.

Click on the “KYC” tab to see the list of details you need to add.

Our team may also reach out separately to collect a few more details offline, depending on your business category.

#Step 4 — Submit config for review

For the Production phase, your configuration and KYC details will be examined and verified by the (Website Name) team before going live.

Verification by (Website Name) typically takes about 3–4 business days. Once completed, you will receive a notification from our team. The “Review” tab will then reflect “Your latest configuration is live in production”.

It's essential to note that at this stage, your biller will only be available on the (Website Name) platform. The information will be conveyed to the BBPS system, which on-boards billers in weekly batches.

Customers can retrieve their bills via BBPS-supported apps and proceed with payments. The transactional details will be visible on the Reports page on the Bridge.

#Reports for live transactions and settlements

You can access the transaction list from the Reports page from the link on the left nav bar, or the “Reports” tab inside the biller dashboard.

Read more about reports ↗.

#Editing your config after going live

If you wish to adjust the configuration after launching a biller, you can modify it and then proceed to “Submit for review” once more. The process remains consistent, showing a confirmation message—“You have submitted for review”. upon submission. The revised details will appear on the “Review” tab.

Following submission, the review of your modified configuration usually takes 2–4 days by a (Website Name) admin.

During the approval or rejection period for new details, the existing configuration will remain operational, allowing your customers to continue making payments.

#Notifications

Outgoing event alerts sent by (Website Name) to partners.

At present, there exists a singular event—BILL_SETTLEMENT_STATUS, which prompts a notification according to the following explanation.

#Bill settlement status

Bill settled

A notification termed SETTLEMENT_SUCCESSFUL is dispatched to the biller upon successful settlement from (Website Name) to the biller, in accordance with the agreed settlement frequency between (Website Name) and the biller.

// Sample JSON structure
{
    "partnerDetails": {
        "appID"             : "string",
        "productInstanceID" : "string"
    },
    "events": [
        {
            "id"        : "f3b41c8f-72fc-485d-b39a-cf497787a039",
            "type"      : "BILL_SETTLEMENT_STATUS",
            "timeStamp" : 1594293083984,
            "data"      : {
                "amountSettled"     : {
                    "currencyCode" : "INR",
                    "value"        : 108400 // in paise
                },
                "platformBillIds"   : ["platformBillId1", "platformBillId2"], // list of strings  
                "status"            : "SETTLEMENT_SUCCESSFUL",
                "transactionId"     : "1074362738220"
            }
        }
    ]
}

As next steps, you can either start your internal reconciliation process or consume our Report APIs ↗ to get detailed settlement reports.

#Constructing a bill on Collect

How to personalize the (Website Name) bill object for any business use case

The (Website Name) bill object lies at the heart of Collect, allowing for a wide range of business scenarios—enabling recurring payments for insurance premiums or handling school fee collections with multiple line items. It achieves this by adopting a versatile, modular information structure that can be tailored to your specific requirements.

Discover the entire object on the API reference ↗.

#Basic bill structure

The data object houses 2 types of data—

• billDetails—the components are explained in the following sections.
• customer—these are the customer details required by NPCI, as per biller category. Read about special cases ↗.

"data" : {
    "customer": {
        "name": "Shailesh"
    },
    "billDetails" : {
        "billFetchStatus" : "AVAILABLE",
        "bills" : [
            {
                "generatedOn"       : "2020-06-04T06:59:04Z" // bill generation / fee start date, 
                "dueDate"           : "2020-06-04T06:59:04Z" // last date for fee payment,  
                "recurrence"        : "ONE_TIME",  
                "amountExactness"   : "EXACT", 
                "billerBillID"      : "string",  // bill identifier, sent with each payment
                "customerAccount"   : {},
                "amount"            : {}, //amount against the bill
                "items"             : [], // array of line items
                "aggregates"        : {} // details on final amount that the customer needs to pay
            }
        ]
    }
}

#Bill Components

In the bill object, the details are broken down into simple logical units, that follow the same pattern and structure where ever they appear.

Amount

"amount" : {
    "currencyCode" : "INR", // ISO 4217
    "value"        : 10000  // in paise, so this means 100 rupees
}

amount is made of two attributes—

• currencyCode The currency used in the bill its three-letter ISO 4217 format.
• value The money value of the bill, in paise.

This same object structure is re-used whenever there is a need to denote amounts against any item such as fees, taxes, discounts etc.

Items

"items" : [
    {
        "code"            : "string",
        "displayName"     : "string",
        "description"     : "string",
        "measurementUnit" : "ENUM",
        "quantity"        : 0,
        "unitPrice"       : {},
        "discounts"       : [],
        "fees"            : [],
        "taxes"           : [],
        "aggregates"      : 
        {
            "discount" : {},
            "subTotal" : {},
            "tax"      : {},
            "total"    : {}
        },
    }
]

This array is where the individual prices against services or products (for which the bill has been raised) are listed out.

Fees

"fees" : [
    {
        "quantity"    : 0,
        "displayName" : "string",
        "description" : "string",
        "unitCost"    : {},
        "discounts"   : [],
        "taxes"       : [],
        "aggregates"  : {
            "discount" : {},
            "subTotal" : {},
            "tax"      : {},
            "total"    : {}
        }
    }
]

The fees array within the (Website Name) bill object is utilized to consolidate details regarding supplementary costs, like processing fees. Within this array, the taxes child component allows for a breakdown of each tax element associated with the fees.

Any value linked to items such as taxes, discounts replicate the same object structure as described in the amount object.

Taxes

"taxes" : [
    {
        "type"        : "string"
        "displayName" : "string",
        "amount"      : {},
        "computation" : {},
        "components"  : [
            {
                "type"        : "string",
                "displayName" : "string",
                "amount"      : {},
                "computation" : {},
            }
        ],
    }
]

The taxes array is used to bundle all the tax-related information in the (Website Name) bill object. It has a components child, which can be used to provide a breakdown of the individual tax elements of the bill. This, in turn, contains a similar structure as the parent object, to be consistent.

The amounts against any item such as taxes, discounts replicate the same object structure as described in the amount object. The amount and the computation objects displayed are replicated in the same way as within other objects.

Taxes

"taxes" : [
    {
        "type"        : "string"
        "displayName" : "string",
        "amount"      : {},
        "computation" : {},
        "components"  : [
            {
                "type"        : "string",
                "displayName" : "string",
                "amount"      : {},
                "computation" : {},
            }
        ],
    }
]

The taxes array in the (Website Name) bill object serves to consolidate all tax-related information. Within this array, the components child includes a breakdown of the specific tax elements for the bill. This component adheres to a structure akin to the parent object to maintain consistency throughout the bill details.

The amounts associated with various items, such as taxes, or discounts follow the identical object structure outlined in the amount object. The display of both the amount and computation objects are replicated consistently, akin to how they're presented in other objects.

Computation

"computation" : {
    "currencyCode" : "string",
    "value"        : int,
    "method"       : "PERCENTAGE" | "VALUE",
}

Sometimes, values are calculated dynamically, and is dependant on the rest of the elements in the bill. This is where the computation object comes into the picture. It is very similar to the amount object, but with an additional method attribute which describes how that value was arrived at.

Aggregates

"aggregates" : {
    "itemQuantity" : {},
    "discount"     : {
        "displayName" : "string",
        "amount"      : {
            "currencyCode" : "string",
            "value"        : 0
        },
    },
    "fee"      : {},
    "tax"      : {},
    "subTotal" : {},
    "total"    : {}
}

The aggregates object is employed to present the overall combined value gathered from all the aforementioned components. Each of these attributes follows a consistent structure, encapsulating the amount→ object within, along with the displayName string.

#Sample bill

Utilizing all these components, it becomes possible to generate a bill for a real-world scenario. Let’s consider the creation of an EMI payment bill with the following details—

In this instance, we must accommodate two line items for the EMIs, two types of fees, and a single total amount for the complete bill. The EMIs can be structured utilizing the items object as follows—

"items" : [
    {
        "displayName" : "EMI — June",
        "description" : "Missed installment payment for June",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 600000  // INR6000 in paise
            }
        }
    },
    {
        "displayName" : "EMI — July",
        "description" : "Installment for July",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 600000  // INR6000 in paise
            }
        }
    }
]

And for the fees included, we can use the fees object, like so—

"fees" : [
    {
        "displayName" : "Late fees",
        "description" : "Extra charge for missing the June payment",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 20000  // in paise
            }
        }
    },
    {
        "displayName" : "Convenience fees",
        "description" : "Online processing charges",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 1500  // in paise
            }
        }
    }
]

Filling the other attributes and putting it all together, the bill object now looks something like this—

//  ENTIRE BILL OBJECT
{
    "billerBillID"    : "CXR5JEQO8K",
    "recurrence"      : "ONE_TIME",
    "generatedOn"     : "2019-07-27T12:56:39Z",
    "dueDate"         : "2019-08-26T12:56:39Z",
    "amountExactness" : "EXACT",
    "fees" : [
        <late fees object>,
        <convenience fees object>
    ],
    "items" : [
        <june fee object>,
        <july fee object>
    ],
    "customerAccount" : {
        "id" : "[email protected]"
    },
    "aggregates"      : {
        "subtotal" : {
            "amount" : {
                "displayName" : "EMI amount",
                "value"       : 1200000  // in paise
            }
        },
        "total": {
            "amount" : {
                "displayName" : "Total payable amount",
                "value"       : 1221500  // in paise
            }
        }
    }
}

Finally, wrap the bill object in the following pattern, and send it across to us as the fetchCustomerBills↗ response to (Website Name)—

//  FETCH CUSTOMER BILLS API RESPONSE
{
    "status"  : 200,
    "success" : true,
    "data"    : {
        "customer" : {
            "name" : "Asha Dev"
        },
        "billDetails" : {
            "billFetchStatus" : "AVAILABLE",
            "bills" : [
                <bill object>
            ]
        }
    }
}

#Special cases for Biller categories

Certain biller categories require additional parameters, aside from the usual data points required in a bill to be sent to BBPS.

#Biller Category—Education

The customer object necessitates additional details for a biller that operates as a school or university. This is managed through the additionalInfo object, designed to accommodate custom parameters.

For instance, when collecting fees from a student attending a school or university, the customer object might include student-specific details, structured as follows—

{ 
    "customer" : {
        "name" : "string", // should be student name
        "additionalInfo" : {
            "academicYear"   : "2020-2021",  // school academic year for the fees
            "course"          : "Class VIII-B",  // student class
            "enrollmentCode" : "7340-24703M",  // student unique enrolment code
            "parentName"     : "Asha Dev",  // parent name
            "schoolName"     : "India Public School",  // school name
            "schoolAddress"  : "5/3, KG Avenue, 2nd Block, Sector 6, Delhi"  // school address
        }
    }
}

To know more about how the bill object is structured to support line items for such use cases, see the sample bill below.

#Sample bill for education category

Here’s a sample bill for a school wanting to collect tuition, transport and canteen fees for a student on a monthly basis—

In the above bill, we need to process three line items for monthly school payments, one type of fee and one total amount for the entire bill. There are two ways of sharing this information with (Website Name).

Option 1

The line items are constructed using the items object, like so—

"items": [
    {
        "displayName" : "Tuition",
        "description" : "Tuition for June",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 1500000  // in paise
            }
        }
    },
    {
        "displayName" : "Transport charges",
        "description" : "Transport charges for June",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 300000  // in paise
            }
        }
    }, 
    {
        "displayName" : "Canteen charges",
        "description" : "Canteen charges for June",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 200000  // in paise
            }
        }
    }
]

And for the processing fees included, we use the fees object—

"fees": [
    
    {
        "displayName" : "Payment mode fees",
        "description" : "Online processing fees",
        "aggregates"  : {
            "total"   : {
                "currencyCode" : "INR",
                "value"        : 3000  // in paise
            }
        }
    }
]

Now, completing the remaining attributes and consolidating them, the bill object begins to take the shape as follows:

//  ENTIRE BILL OBJECT
{
    "billerBillID"    : "CXR5JEQO8K",
    "recurrence"      : "ONE_TIME",
    "generatedOn"     : "2020-07-27T12:56:39Z",
    "dueDate"         : "2020-08-26T12:56:39Z",
    "amountExactness" : "EXACT",
    "fees" : [
        <Convenience fees object>
    ],
    "items" : [
        <Monthly tuition object> //shown above,
        <Monthly transport object> //shown above,
        <Monthly canteen object> //shown above
    ],
    "customerAccount" : {
        "id" : "[email protected]"
    },
    "aggregates"      : {
        "subtotal" : {
            "amount" : {
                "value"       : 2000000  // in paise
            },
            "displayName" : "EMI amount"
        },
        "total": {
            "amount" : {
                "value"       : 2003000  // in paise
            },
            "displayName" : "Total payable amount"
        }
    }
}

Wrap the bill object in the following pattern, and send it across to us as part of the fetchCustomerBills↗ response to (Website Name). Be sure to include details in the additionalInfo array required for education category in the data.customer object.

//  fetchCustomerBills API response
{
    "status"  : 200,
    "success" : true,
    "data"    : {
        "customer" : {
            "name" : "Shailesh Yadav", // student name
            "additionalInfo" : {
                "academicYear"   : "2020-2021",  // school academic year for the fees
                "course"         : "Class VIII-B",  // student class
                "enrollmentCode" : "7340-24703M",  // student unique enrolment code
                "parentName"     : "Asha Dev",  // parent name
                "schoolName"     : "India Public School",  // school name
                "schoolAddress"  : "5/3, KG Avenue, 2nd Block, Sector 6, Delhi"  // school address
            }
        },
        "billDetails" : {
            "billFetchStatus" : "ENUM",
            "bills" : [
                <bill object>
            ]
        }
    }
}

Please note that, for a biller—a school or university in this case—to be able to display a line by line break up of tuition fees, transport fees, mess fees etc, the biller has to get all line items registered with (Website Name) to display the fees break up properly. Raise a ticket to get support.

Option 2

We recommend this method since this gives you the flexibility to change the bill breakup headers dynamically.

The line items are shared using a parameter named URL in the customer.additionalInfo object, like so—

{
    "customer" : {
        "name" : "string", // should be student name
        "additionalInfo" : {
            "academicYear"   : "2020-2021",  // school academic year for the fees
            "course"          : "Class VIII-B",  // student class
            "enrollmentCode" : "7340-24703M",  // student unique enrolment code
            "parentName"     : "Asha Dev",  // parent name
            "schoolName"     : "India Public School",  // school name
            "schoolAddress"  : "5/3, KG Avenue, 2nd Block, Sector 6, Delhi",  // school address
            "URL"            : "https://some.url/with/bill/details"  // bill breakup URL
        }
    }
}

And the customer facing UI would contain some simple HTML code to display the breakup of the bill, like so—

<table>
    <thead>
        <tr>
            <td>Monthly charges</td>
            <td>Amount (₹)</td>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Tuition</td>
            <td>15,000</td>
        </tr>
        <tr>
            <td>Transport charges</td>
            <td>3000</td>
        </tr>
        <tr>
            <td>Canteen charges</td>
            <td>2000</td>
        </tr>
        <tr>
            <td>Convenience fees</td>
            <td>30</td>
        </tr>
        <tr >
            <td>
                Total payable
            </td>
            <td>
                20,030
            </td>
        </tr>
    </tbody>
</table>

Enclose the customer object with other details, similar to the bill object pattern, and transmit it to us as part of the fetchCustomerBills↗ response to (Website Name). Ensure to incorporate the necessary particulars in the additionalInfo array required for education category in the data.customer object.

//  fetchCustomerBills API response
{
    "status"  : 200,
    "success" : true,
    "data"    : {
        "customer" : {
            "name" : "Shailesh Dev", // student name
            "additionalInfo" : {
                "Academic Year"   : "2020-2021",  
                "Course"          : "Class VIII-B",  
                "Enrollment Code" : "7340-24703M",  
                "Parent Name"     : "Asha Dev",  
                "School Name"     : "India Public School",  
                "School Address"  : "5/3, KG Avenue, 2nd Block, Sector 6, Delhi" ,
                "URL"             : "https://some.url/with/bill/details"
            }
        },
        "billDetails" : {
            "billFetchStatus" : "ENUM",
            "bills" : [
                <bill object>
            ]
        }
    }
}

#Reports API

The (Website Name) Reports API offers access to transaction and settlement data, enabling automation of your reconciliation process.

#Transaction Report

Request

{
    "filters" : {
        "paymentStartDate"    : "2019-12-31T18:30:00.000Z",  // ISO-8601 timestamp in UTC
        "paymentEndDate"      : "2020-12-10T18:29:59.999Z",  // ISO-8601 timestamp in UTC
        "settlementStartDate" : "2019-12-31T18:30:00.000Z",  // ISO-8601 timestamp in UTC
        "settlementEndDate"   : "2020-12-10T18:29:59.999Z",  // ISO-8601 timestamp in UTC
        // payment modes you want to filter, we recommend skipping this parameter
        "paymentMode"         : [
            "UPI",
            "CASH",
            "NEFT",
            "RTGS",
            "IMPS",
            "IFT",
            "CC",
            "DC",
            "Prepaid",
            "Internet Banking",
            "Debit Card",
            "Credit Card",
            "Cash",
            "Wallet",
            "Prepaid Card",
            "AEPS",
            "Account Transfer",
            "Bharat QR",
            "USSD"
        ],
        "platformBillStatus" : [  // bill statuses you want to filter, we recommend using only "SETTLEMENT_SUCCESSFUL" for exact reconciliation
            "PAYMENT_SUCCESSFUL",
            "PAYMENT_FAILED",
            "CREDIT_RECEIVED",
            "SETTLEMENT_SUCCESSFUL",
            "SETTLEMENT_FAILED",
            "BILL_EXPIRED"
        ]
    },
    "pagination": {  // set your pagination limit for large number of records
        "cursor": "",  // use "nextCursor" value as returned by API response, as an input to subsequent API call to move the cursor ahead
        "limit": 100  // min 100 max 500
    },
    "productIds": [  // list of all product IDs for which you want to fetch the records for
        "374024227163997852"
    ],
    "reportType": "transaction"
}

Response

{
    "status": 200,  // http status
    "success": true,  // success status of API request
    "data": {  // data in case of success
        "metadata": {  // metadata about records that match the request
            "totalRecords": 2,  // total number of matching records
            "filters": {},  // filters applied
            "previousCursor": "",  // updated cursor position after this call
            "nextCursor": ""  // next cursor position for use with next iteration of pagination
        },
        "records": [  // array of records
            {
                "platformBillID": "517002663317996567",  // (website name)'s unique ID for every bill
                "billerBillID": "fb0e9146-466a-40f1-9bd6-e8d01d4940e2",  // biller's ID associated with this bill
                "billerMCC": "Loans",  // category of business
                "platformBillStatus": "CREDIT_RECEIVED",  // status of the transaction, read here to know more: https://support.(website name).co/support/solutions/articles/81000385479
                "amountTotal": 1992,  // bill amount
                "deemedStatus": "NOT_DEEMED",  // whether this bill was deemed success (upcoming feature)
                "currencyCode": "INR",
                "amountPaid": 200000,  // amount paid by the customer
                "paymentInstrument": "UPI",  // payment method used by the customer
                "paymentDate": "2020-12-10T05:43:30+05:30",  // ISO-8601 timestamp for payment
                "paymentReferenceID": "517002663317996567",  // unique payment ID as shared by customer app
                "paymentReceipt": "dceeb285-c4ab-49e4-a7f0-d37bdef3b906",  // receipt generated against the payment
                "settlementDate": "2020-12-12T10:54:30+05:30",  // ISO-8601 timestamp for settlement
                "settlementUtr": "CMS201022000BLO",  // bank Unique Transaction Reference number for the settlement
                "primaryAccountNumber": "XXXXXXXX060510",  // primary bank account associated with the biller
                "primaryAccountIfsc": "KKBK0000431",  // primary bank IFSC associated with the biller
                "primaryAccountName": "John Wick",  // primary bank account holder name associated with the biller
                "primaryAccountSettlementAmount": 198384,  // settlement amount sent to primary bank account
                "split": "YES",  // indicates if settlement has been split into parts
                "splitSettlements": [  // array with objects describing each part of the split in settlement
                    {
                        "date": "2020-10-22T10:54:30+05:30",
                        "utr": "CMS201023000BLO",
                        "name": "The Manager",
                        "id": "XXXXXXXX060511",
                        "ifsc": "KKBK0000431",
                        "amount": 1144
                    }
                ],
                "bpcTotal": 400,  // bill payment charge deducted by (website name)
                "bpcPercentage": 0,  // percentage on the basis of which the bill payment charge is calculated
                "bpcFlat": 400,  // flat fee as part of bill payment charge
                "gstTotal": 72,  // GST charged on bill payment charge
                "gstPercentage": 18,  // percentage fee on the basis of which the GST is calculated
                "gstFlat": 0  // flat fee as part of GST
            },
            {
                ...
            }
        ]
    }
}

#Refund Report

Request

{
    "filters": {
        "createdAtEndDate": "2022-08-10T11:15:41.631Z",  // ISO-8601 timestamp in UTC
        "createdAtStartDate": "2022-08-06T18:30:00.000Z"  // ISO-8601 timestamp in UTC
        "payeeVPA": "anothersample@okbank",
        "payerVPA": "sample@okbank",
        "paymentReferenceID": "1234567890",
        "refundReason": [
            "Order ID invalid in credit alert",
            "Duplicate payment made against bill",
            "Payment amount validation failure",
            "Credit alert received after bill expiry",
            "Credit alert not received from bank",
            "Initiated by merchant",
            "Source account info missing from credit alert",
            "TPV check failure"
        ],
        "refundStatus": [
            "Created",
            "MarkedForRefund",
            "QueuedForRefund",
            "Rejected",
            "Initiated"
        ]
    },
    "pagination": {  // set your pagination limit for large number of records
        "cursor": "",  // use "nextCursor" value as returned by API response, as an input to subsequent API call to move the cursor ahead
        "limit": 100  // min 100 max 500
    },
    "productIds": [  // list of all product IDs for which you want to fetch the records for
        "374024227163997852"
    ],
    "reportType": "refund"
}

Response

{
    "status": 200,
    "success": true,
    "data": {
        "metadata": {
            "totalRecords": 39,
            "filters": {
                "createdAtEndDate": "2022-08-10T11:15:41.631Z",  // ISO-8601 timestamp in UTC
                "createdAtStartDate": "2022-08-06T18:30:00.000Z",  // ISO-8601 timestamp in UTC
                "paymentMode": null,
                "platformBillStatus": null,
                "productTypes": null,
                "refundReason": [
                    "Order ID invalid in credit alert",
                    "Duplicate payment made against bill",
                    "Payment amount validation failure",
                    "Credit alert received after bill expiry",
                    "Credit alert not received from bank",
                    "Initiated by merchant",
                    "Source account info missing from credit alert",
                    "TPV check failure"
                ],
                "refundStatus": [
                    "Created",
                    "MarkedForRefund",
                    "QueuedForRefund",
                    "Rejected",
                    "Initiated"
                ]
            },
            "previousCursor": "",
            "nextCursor": ""
        },
        "records": [
            {
                "actorID": "1234567890",
                "amount": 1234,
                "batchID": "cbpobt817cjflqbfl5r0",
                "createdAt": "2022-08-10T15:48:29+05:30",
                "initiatedAt": "",
                "payerVPA": "sample@okbank",
                "payeeVPA": "anothersample@okbank",
                "paymentReferenceID": "222234971910",
                "paymentTransactionID": "PTMDCWAAD8A02F7412B90DE8C32236D0494",
                "platformBillID": "958135084945245239",
                "refundReason": "Initiated by merchant",
                "refundID": "958136906271525795",
                "refundStatus": "Created",
                "type": "MerchantInitiated",
                "deductions": [
                    {
                        "account": {
                            "name": "",
                            "id": "0566102000016463",
                            "ifsc": "IBKL0002536"
                        },
                        "split": {
                            "value": 1234,
                            "unit": "INR"
                        },
                        "UTR": ""
                    }
                ]
            },
            {
              ...
            }
        ]
    }
}

#Additional resources

Detailed instructional resources for this solution.

#OAuth 2.0

OAuth 2.0 is an open standard that facilitates authorization via HTTPS. It's utilized within (Website Name)'s framework in two distinct scenarios.

• Merchants can authorize (Website Name) requests related to BBPS.
• (Website Name) can authorize a merchant's requests to access the (Website Name) Reports API.

For additional information on OAuth 2.0, explore more details here ↗.

#(Website Name) utilizes the Merchant OAuth Token API

By initiating a request to the Token URL. This request involves the credentials configured on Bridge within the OAuth2.0 authentication scheme.

Assume the URLs to be

• Base URL: https://api.my-company.com/v1/bbps
• Token URL: https://api.my-company.com/v1/bbps/auth/oauth

Based on the chosen OAuth2.0 scheme on Bridge, (Website Name) will make either one of the following requests

• For Client credentials

        
    curl --location --request POST 'https://api.my-company.com/v1/bbps/auth/oauth' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_secret=myOAuthSecret' \
    --data-urlencode 'client_id=myClientID'
    

{
      "access_token": "actual_token", 
      "refresh_token": "token_used_to_refresh_access_token"
}

• For Password

        
    curl --location --request POST 'https://api.my-company.com/v1/bbps/auth/oauth' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'username=myUsername' \
    --data-urlencode 'password=myPassword' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'client_secret=myOAuthSecret' \
    --data-urlencode 'client_id=myClientID'
    

{
      "access_token": "actual_token", 
      "refresh_token": "token_used_to_refresh_access_token"
}

This access_token would then be used to make /bills/fetch and /bills/fetchReceipt requests to the Base URL configured on Bridge as follows.

curl --location --request POST 'https://api.my-company.com/v1/bbps/bills/<fetch||fetchReceipt>' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access_token>' \
    --data '{......}'
    

#Calling (Website Name)-hosted APIs for Reports

Merchants access (Website Name)'s hosted APIs to retrieve reports, utilizing OAuth keys to generate an access token for authorizing these API requests, as detailed in the following explanation.

OAuth keys for (Website Name) products offer considerable flexibility, enabling the establishment of a single set of keys to authorize requests across multiple product configurations. Alternatively, they allow the authorization of requests for a single configuration using multiple sets of keys.

Note on JWT authentication

The generation of tokens through the API is exclusive to OAuth keys. While JWT authentication is currently supported, we advise transitioning to OAuth, as further feature development for JWT is not planned.

Change of URLs for OAuth

#How to get OAuth keys

Step 1—Accessing API Keys

Navigate to The Bridge and log in.
If you are an Admin, locate the API keys card under "Org settings" in the left panel. Click on the OAuth keys card to view keys for all your product configurations.

Step 2—Configure key details

On clicking “Generate new key”, button

Select the environment: Sandbox keys access sandbox configs, while production keys access production configs.

Provide a descriptive "Key name" for easy identification.

Choose the product configurations this key should access using the "Add products" option.

Step 3—Generate key

Once all required fields are filled, the "Generate key" button becomes active. Click on it, and the clientID and secret for this key will be displayed.

You can now utilize this key to initiate API requests to (Website Name). For more details on the supported features for OAuth keys, refer to the link ↗ provided.

#Generate Token API

(Website Name) provides an API for generating tokens, which are used to authorize other API requests. This API works with OAuth keys only.

Request

Request body

{
    "clientID" : "c0a411d5-b6f9-4bfd-a342-7cb01935ed43",    
    "secret"   : "b2b3e650-a31b-47a3-acf6-c96c9c5c282d",
}

Response

Success

A new token is provided by (Website Name) in the success response, along with an expiresIn param, which states the validity of the token in seconds (the present default value is 1800 seconds or 30 minutes). You may store and keep reusing the same token till it expires.

{
    "status" : 200,
    "success" : true,
    "data" : {
        "expiresIn" : 1800, //seconds
        "token"     : "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJsaWJ6NGFNaE4yUk5xMlpyVk9QaFhaMXpoMjA0V2gtdTdhT21LX2huRVQ4In0.eyJleHAiOjE2MTM5OTQzMTIsImlhdCI6MTYxMzk5NDAxMiwianRpIjoiZmZhZjM2ZTUtZmI3Mi00NTY2LTljOGYtY2U5N2I5MjY2Y2E4IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLWRldi5zZXR1LmNvL2F1dGgvcmVhbG1zL2NvbGxlY3QiLCJzdWIiOiJhZGE1MTNhMS0xYjVhLTQ1NGQtYTk2Ny05OGI3YTYwNjY3MTAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjZDRlYTM5OC03YWIzLTQ3ZGUtYWE1MC03YzNiOWIzZjBhMjYiLCJzZXNzaW9uX3N0YXRlIjoiYmYxYjJjZjgtNTgzZC00Y2MwLWIwN2QtNmI5YWQyNmZiNGI0IiwiYWNyIjoiMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiJjZDRlYTM5OC03YWIzLTQ3ZGUtYWE1MC03YzNiOWIzZjBhMjYiLCJjbGllbnRIb3N0IjoiMTA2LjUxLjE1LjI1MCIsIlgtU2V0dS1Qcm9kdWN0LUluc3RhbmNlLUlEIjoiNTYyNDMzODMwNDMwOTY2OTk4IiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LWNkNGVhMzk4LTdhYjMtNDdkZS1hYTUwLTdjM2I5YjNmMGEyNiIsImNsaWVudEFkZHJlc3MiOiIxMDYuNTEuMTUuMjUwIn0.QfEzImuN1P9jwTBJTcJ6ozP_gC3J-FOJp0D0va2AfXUUw8d5HLA5zqojCd6BnE6ApqKWnVU1aB0YWFwDbgHaVA3Netr-hmGadElLMhGiHah2UaLO0Bk86pZpyxNxtdx9u6YjfVYT6TSvUsqO4lISegFTJRTqFZxuBFv4WoKJPPD0JwEMYGH71LyOiCJA2sAq4YbOMKOvRrj2X_ipkSqvsrgEZicJ3lTY4vWyoGJ8wps0VW6k4vFSdX1qRKrAz_7XVKr8MKz_H1ng91h5XlZqsUh6BPz3WW0atWjt0RbAtXR32iB0zaB204IECxwriNmka1FxA9PZq94NvPwANDznhQ"
    }
}

Failure

(Website Name) may respond with the following error if incorrect clientID and secret details are provided:

{
    "status"  : 400,
    "success" : false,
    "error" : {
        "code"    : "invalid-api-key",
        "detail"  : "API key invalid [cd4ea398-7ab3-47de-aa50-7c3b9b3f0a21], please recheck your credentials.",
        "docURL"  : "",
        "title"   : "AUTHENTICATION_ERROR"
        "traceID" : "8b7bd233-5231-4bdd-8d48-aa4c0dae07b9"
        "errors"  : [],
    }
}

• In the above response, the traceID is dynamic and can be shared with the (Website Name) support team for further debugging.

#How to use the token

After obtaining a valid token linked to product configuration(s), you can retain it and apply it to authorize (Website Name) API calls by setting the authorization request header as Bearer .

For token expiry

Implement a workflow to generate new token when the old one expires. The general setup might look something like this—

• Maintain the clientID and secret .
• Generate a new token using the stored clientID and secret upon token expiration. If a 401 unauthorized error occurs while calling the API, it suggests the token has expired.
• Save the newly generated token and utilize it for future API calls.

#JWT basics

The JWT is sent as part of the authorisation header of every API request. Typically it looks like this—

// Auth header format
Authorization: Bearer <JWT_TOKEN>
// Sample JWT encoded
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI4ZjQ3ZTQxYy00Njg0LTRhZjEtYjFiOC0yNDZjODMxMTIwMzMiLCJpYXQiOjE1NzI0OTMzNTYsImp0aSI6ImM1MzQ0N2UzLTk5M2EtNDRhZS05Yzc4LTMxZjQ1YzNjMDgyZSJ9.xfYii9lfWMHtMBgjK5U6NFN_6_Q9jw8UMQu8Jnvftbs

A JWT has three parts header, payload, and a signature. The format used by (Website Name) is as follows:

// JWT format
urlsafe_base64(<JWT_HEADER>).urlsafe_base64(<JWT_PAYLOAD>).urlsafe_base64(<SIGNATURE>)
// Sample JWT decoded
{
    "alg" : "HS256",
    "typ" : "JWT"
},
{
    "aud" : "8f47e41c-4684-4af1-b1b8-246c83112033", // This is the schemeID
    "iat" : 1572493356,
    "jti" : "c53447e3-993a-44ae-9c78-31f45c3c082e"
}

This means that—

header    : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
payload   : eyJhdWQiOiI4ZjQ3ZTQxYy00Njg0LTRhZjEtYjFiOC0yNDZjODMxMTIwMzMiLCJpYXQiOjE1NzI0OTMzNTYsImp0aSI6ImM1MzQ0N2UzLTk5M2EtNDRhZS05Yzc4LTMxZjQ1YzNjMDgyZSJ9
signature : xfYii9lfWMHtMBgjK5U6NFN_6_Q9jw8UMQu8Jnvftbs

Header

The value has been encoded in base64 The algorithm used to calculate the signature is described in this section. This could have values such as HMAC SHA256 or RSA. For example—

// Sample JWT header
{
  "alg" : "HS256",
  "typ" : "JWT"
}
// is encoded to
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Payload

This is also a base64 encoded value. It contains information about the entity and the request made (also known as "claims"). As an example,

// Sample JWT payload
{
    "aud" : "8f47e41c-4684-4af1-b1b8-246c83112033", // This is the schemeID
    "iat" : 1572493356,
    "jti" : "c53447e3-993a-44ae-9c78-31f45c3c082e"
}
// is encoded to
eyJhdWQiOiI4ZjQ3ZTQxYy00Njg0LTRhZjEtYjFiOC0yNDZjODMxMTIwMzMiLCJpYXQiOjE1NzI0OTMzNTYsImp0aSI6ImM1MzQ0N2UzLTk5M2EtNDRhZS05Yzc4LTMxZjQ1YzNjMDgyZSJ9

• aud (Authorized User) represents the scheme_id in the JWT, which is shared by the entity sending the API response to the entity initiating API requests. (Website Name) provides this value under credentials for making calls to (Website Name) APIs. You need to set and share this value with (Website Name) to enable them to make calls to your APIs.
• iat  (Issued At) is the epoch timestamp in seconds, indicating when the request was issued. Any requests older than 120 seconds (2 minutes) are considered outdated and should be declined.
• jti (JWT ID) is a unique identifier for each request used for logging, debugging, and tracking purposes. As this ID is unique for every request, avoid reusing or replicating the same JWT token for different requests.

Signature

With the algorithm specified in the header, the encoded header, encoded payload, and secret, the signature is constructed as follows:

HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    secret
)

The secret is a confidential key shared between (Website Name) and your system, utilized to sign the token, ensuring the authenticity of the JWT sender. It confirms that the claims are originating from the aud as asserted. Authentication of the request depends on both the signature's validity and the verification of each claim separately. For instance—

Input string   : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI4ZjQ3ZTQxYy00Njg0LTRhZjEtYjFiOC0yNDZjODMxMTIwMzMiLCJpYXQiOjE1NzI0OTMzNTYsImp0aSI6ImM1MzQ0N2UzLTk5M2EtNDRhZS05Yzc4LTMxZjQ1YzNjMDgyZSJ9
Secret         : 7c2e036c-908f-48ba-abe3-cd8745a6fa99
HA256 Signaure : xfYii9lfWMHtMBgjK5U6NFN_6_Q9jw8UMQu8Jnvftbs

You can try this on your command line by running—

echo -n "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI4ZjQ3ZTQxYy00Njg0LTRhZjEtYjFiOC0yNDZjODMxMTIwMzMiLCJpYXQiOjE1NzI0OTMzNTYsImp0aSI6ImM1MzQ0N2UzLTk5M2EtNDRhZS05Yzc4LTMxZjQ1YzNjMDgyZSJ9.xfYii9lfWMHtMBgjK5U6NFN_6_Q9jw8UMQu8Jnvftbs" | openssl dgst -sha256 -hmac BBzKUWAZeAS2tBsk0FtJT4ep -binary|openssl base64 -e -A | sed s/+/-/ | sed -E s/=+$//

Read more about how we arrived at this command here ↗

#JWT authentication for Website Name APIs

The JSON Web Token (JWT) serves as a secure means of communication with (Website Name), functioning as an open standard for securely representing claims between two parties.

Although JWT keys are supported, it is suggested to use OAuth keys due to their enhanced security features, such as the capability to access multiple products using the same key, regenerate or delete keys as required, and more. Each product configuration within (Website Name) comes with its unique JWT key, allowing merchants to authorize API requests with individual JWT keys for specific products.

For further details on JWT, you can refer to the JWT website ↗ covering its working principles and involved concepts. This guide aims to simplify the implementation of JWT within (Website Name)'s system.

For Website Name products, JWT keys have a one-to-one mapping with individual product configurations. Essentially, each product configuration comes with its own JWT key that a merchant can use to authorise API requests.

#Calling (website name)-hosted APIs

A merchant uses (Website Name) APIs to perform various actions such as creating payment links, checking link statuses, and fetching reports. JWT is utilized to authenticate these requests with (Website Name).

If you are an Admin for your Bridge account, you should be able to see the API keys card under “Org settings” in the left panel. Click the JWT keys card to view keys for all your product configs. Read more ↗

#Sample code

Practically, you need not concern yourself with the encoding and decoding of a JWT.

Numerous third-party libraries are available to easily handle these processes. A variety of libraries in various programming languages can be found under the "Libraries for Token Signing/Verification" section here ↗.

For (Website Name) or its partners to acknowledge a request as authentic, the JWT format must be recognized, meaning the payload is verified, and the signature is valid. Requests may be rejected if:

1. The token was generated more than 2 minutes ago.
2. The aud claim is not verified.
3. The signature is invalid.

Sample code in popular languages is provided below.

Python

import jwt
import datetime
import uuid
scheme_id = "8f47e41c-4684-4af1-b1b8-246c83112033"
secret    = "7c2e036c-908f-48ba-abe3-cd8745a6fa99"
payload   = {
    "aud" : scheme_id,
    "iat" : datetime.datetime.utcnow(),
    "jti" : str(uuid.uuid1())
}
# generate a token like this
token = jwt.encode(payload, secret, algorithm="HS256")
# And to decode the token and verify the aud claim—
try:
    # verified claim
    jwt.decode(token, secret, audience=scheme_id)
    print("Verified token")
except jwt.PyJWTError:
    # unverified claim
    print("Token error")

PHP

<?php
require __DIR__.'/vendor/autoload.php';
use FirebaseJWTJWT;
$key = "7c2e036c-908f-48ba-abe3-cd8745a6fa99";
$aud = "8f47e41c-4684-4af1-b1b8-246c83112033";
// create token
$token = array(
    "aud" => $aud,
    "iat" => 1572493356,
    "jti" => "c53447e3-993a-44ae-9c78-31f45c3c082e"
);
$jwt = JWT::encode($token, $key);
print_r($jwt);
echo '<br/>';
// Decode Logic
/**
 * You can add a leeway to account for when there is a clock skew times between
 * the signing and verifying servers. It is recommended that this leeway should
 * not be bigger than a few minutes.
 *
 * Source: http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#nbfDef
 */
JWT::$leeway = 60; // $leeway in seconds
$decoded = JWT::decode($jwt, $key, array('HS256'));
$audClaimInToken = $decoded -> aud;
print_r($audClaimInToken);
echo '<br/>';
if($audClaimInToken == $aud){
  echo "Success";
}
else{
  echo "Fail";
}
?>

C#

using System;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;
public class JwtAuthManager
{
    static string SecretKey = "ReallyLongSecret"; // this should come from your configuration file
    static string audience = "YourAudClaim";// this should come from your configuration file
    public string GenerateJWTToken()
    {
        byte[] symmetricKey = Encoding.ASCII.GetBytes(JwtAuthManager.SecretKey);
        var token_Handler = new JwtSecurityTokenHandler();
        var now = DateTime.UtcNow;
        var securitytokenDescriptor = new SecurityTokenDescriptor
        {
            Audience = JwtAuthManager.audience,
            IssuedAt = now,
            SigningCredentials = new SigningCredentials(new SymmetricSecurityKey(symmetricKey), SecurityAlgorithms.HmacSha256)
        };
        var stoken = token_Handler.CreateToken(securitytokenDescriptor);
        var token = token_Handler.WriteToken(stoken);
        return token;
    }
    public bool ValidateToken(string token)
    {
        var simplePrinciple = JwtAuthManager.GetPrincipal(token);
        Console.WriteLine(simplePrinciple);
        if (simplePrinciple == null)
            return false;
        // You can implement more validation to check whether username exists in your DB or not or something else. 
        return true;
    }
    public static ClaimsPrincipal GetPrincipal(string token)
    {
        try
        {
            var jwtTokenHandler = new JwtSecurityTokenHandler();
            var jwtToken = jwtTokenHandler.ReadToken(token) as JwtSecurityToken;
            if (jwtToken == null)
                return null;
            byte[] symmetricKey = Encoding.ASCII.GetBytes(JwtAuthManager.SecretKey);
            var validationParameters = new TokenValidationParameters()
            {
                ValidateAudience = true,
                RequireExpirationTime = false,
                ValidateIssuer = false,
                ValidAudience = JwtAuthManager.audience,
                IssuerSigningKey = new SymmetricSecurityKey(symmetricKey)
            };
            SecurityToken securityToken;
            var principal = jwtTokenHandler.ValidateToken(token, validationParameters, out securityToken);
            Console.WriteLine("Principle");
            Console.WriteLine(principal);
            return principal;
        }
        catch (Exception e)
        {
            Console.WriteLine(e);
            return null;
        }
    }
}

Java

package com.(website name).helpers;
import com.auth0.jwt.JWT;
import com.auth0.jwt.JWTVerifier;
import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.exceptions.JWTVerificationException;
import com.auth0.jwt.interfaces.DecodedJWT;
import java.util.Date;
import java.util.UUID;
public class (website name)JwtHelper {
    private String schemedId;
    private String secret;
    public (website name)JwtHelper(String secret, String schemedId) {
        this.schemedId = schemedId;
        this.secret = secret;
    }
    public void setSchemedId(String schemedId) {
        this.schemedId = schemedId;
    }
    public void setSecret(String secret) {
        this.secret = secret;
    }
    public String yieldBearerToken() {
        Algorithm algorithm = Algorithm.HMAC256(this.secret);
        String token = JWT.create()
                .withAudience(this.schemedId)
                .withIssuedAt(new Date())
                .withClaim("jti",  UUID.randomUUID().toString())
                .sign(algorithm);
        return "Bearer " + token;
    }
    public void verifyBearerToken (String bearerToken) throws JWTVerificationException {
        bearerToken = bearerToken.replace("Bearer ", "");
        Algorithm algorithm = Algorithm.HMAC256(this.secret);
        JWTVerifier verifier = JWT.require(algorithm)
                .acceptLeeway(10)
                .withAudience(this.schemedId)
                .build(); //Reusable verifier instance
        DecodedJWT jwt = verifier.verify(bearerToken);
    }
}