#The Bridge

(Website Name) Bridge is a single web portal that allows you to select, configure and go live with your (Website Name) integrations, generate and download transaction and settlement reports, and invite users from your organization to use our platform.

Sign up on The Bridge to get started if you haven’t already.

Using this console, you will be able to access all information related to your (Website Name) integration in just a few clicks. Of course, some workflows are still dependent on offline methods, but we are working hard to provide a seamless, fully-online experience for all of our financial integrations.

#Basic terminology

Here are some terms you might see repeated through out these guides—

Partner

Partners are businesses that integrate with (Website Name) to use our platform. As soon as the entity signs up on the Bridge, they are given a partnerID, which uniquely identifies them within our system.

Product

(Website Name) offers multiple financial API integrations, each of which addresses a particular use case. With Collect BBPS, you can become a biller on the Bharat Bill Payment System, while with FD, you can embed a full-featured fixed deposit flow into your app. Each of these discrete, individual offerings is called a “product”.

Product configuration / Configured product

Each of these products requires a set of input parameters before they can be used. In order to test and go live with the products, you need to fill out an empty template with the required details.

For example, the Collect BBPS product requires the partner to enter details about where to fetch bills from, how to identify customers on their system, and where to settle the incoming payments. These together, make up the “configuration” required for the Collect BBPS to begin making transactions.

Once the configuration has been set, the partner now has a “configured product”, which they can now begin testing. Partners can create as many product configurations as they need, there are no limits.

Sandbox / production environments

As soon as a partner is on-boarded, they are given access to a virtual isolated space where they can configure and test as many products and configurations as they wish. This is called the “sandbox” environment. Transactions made in sandbox are all mocked, meaning there is no actual movement of money between the involved parties.

Upon completing testing in sandbox, the partner can submit the product configuration along with the org KYC to (Website Name) for final review. Once we verify the configuration and the KYC, the partner is now given access to the “production”, or “prod” environment.

Here, in the production environment, partners can create as many fresh configurations as required, which can be be taken “live”. Transactions made with these configurations would trigger actual movement of money between the parties.

Data is not shared between sandbox and production—so configurations exist independently on sandbox and production. You can switch between them easily by hovering over the coloured border on the top of each page. Sandbox is coloured orange, and production is coloured green.

#Reports

You can access all transactions that happen at the partner level through Reports. From the left nav panel, you can access reports. You can also access a configuration's records by clicking on it and navigating to the "Transaction" tab.

Various filters are available on the top to help you narrow down and find specific transactions.

Depending on the environment you are in, the reports data may differ. You can only see sandbox transactions in sandbox, and only production transactions in production for live configurations.

Here’s how you can make the switch—

#The reports table

The records are listed below the filter section in the form of a large table. By default, this table contains some basic information.

Display details

Click on a row—and an info panel open up on the right, which displays in-depth information about that transaction. Click on the cross at the top of this panel to close it again. You can also keep the panel open persistently—simply click on another record to update the details displayed in the info panel.

Show and hide columns

This table can be customized to display more data by changing the default information. Click on the “Show / hide columns” option just above the table, and check the columns you want displayed, and uncheck the ones you do not. Close the info panel, and you should see the updated table with the new columns.

#Apply filters

Report data can be narrowed and sorted using the extensive set of filters in the top section. To retrieve the records, select the ones you want, then click "Apply filters" at the top.

Date range

This filter lets you select a start and end date for the time period you need the reports for. It comes with a “day” preset for present day, “week” for the present week, and “month” for the present month.

Besides this, you can also specify if the dates you have selected are for transactions or settlements. See settlement reports, on filtering by settlement date. Here’s a video on how to search for, view and download settlement information.video on how to search for, view and download settlement information.

Payment instrument

(Website Name) supports the following payment instruments. Payment instruments can be selected specifically. Click on an instrument type to select and add it to the filter. Added instruments to be applied are highlighted with a light border. Click on it again to remove it from your selection. Hit “Apply filters” at the top to run the search with the selected instruments.

Bill status

This filter lets to narrow down records based on status of the transaction.

BILL_CREATED : The bill has been generated, ie, fetched successfully on the payer app.

PAYMENT_SUCCESSFUL : User has made a successful payment, but the payment is not yet settled to biller / merchant.

PAYMENT_FAILED : The customer attempted a payment, but the transaction was not successful. This might be due some validation reasons or bank side issues (rare scenario).

CREDIT_RECEIVED : The money is received by (Website Name).

SETTLEMENT_SUCCESSFUL : The amount for that payment has been settled to the biller / merchant successfully.

SETTLEMENT_FAILED : (Website Name) attempted to settle the amount to the biller / merchant, but was not able to. Usually, we would either resolve this in the next batch of settlements or reach out to you in case there is some additional info required.

BILL_EXPIRED : The due date for the bill has passed, and the customer has not made the payment.

Other bill details

Search by the unique platform bill ID, ie, the unique identifier on (Website Name)'s systems OR by unique payment reference ID, which the bank or the payment processor sends upon payment by the customer.

Settlement details

Search across one or more product configuration with settlement information like settlement UTR or settlement account number.

#Download reports

You can also download reports by clicking on the “Download CSV” button, just above the table. A CSV, or a comma-separated values file should begin downloading immediately. You can open this in any spreadsheet application, such as Microsoft Excel to view the records.

Note that this downloaded CSV file will include all data columns for the selected records, and not just the ones displayed on the table UI.

#Org settings

You can access your company-level settings by clicking on the “Org settings” on the left nav panel.

Depending on your role and access level, you would see links to invite people from your org to the Bridge, managing API keys etc.

#People

You can invite other members of your organization to Bridge, and you can also specify different types of permissions for users to access your Bridge account. Select the "People" card from the left nav panel by clicking the "Org settings" icon.

#Roles

You can assign specific roles to each user, where each role has certain permissions and access levels across Bridge. The following table shows the capabilities of each user.

#Add a user

Go to "Org settings" in the left navigation panel. The "People" card should be visible if you are an Admin for this partner ID. Click the card to proceed.

Now, click on the “Invite new member” button on the top right. You should see the invite form as shown below.

The first step is to enter the email address of the person you want to invite, as well as the role type. To select a role, please refer to the table above. Users cannot have different roles in Sandbox and Production, since they have the same role in both.

Select the product configurations to give access to on Sandbox and/or Production.

On the top right, click "Send Invite". This invites the user to log in to your partner ID with the specified role. Once they accept the invite and log in, their status on the people list page should change to “Active”.

#Edit a user’s role

Navigate to Organisation settings → People.

Search for the user you want to edit permissions for, and click to Edit permissions for the user.

#Disable a user’s role

You may need to disable a user if they leave your organization or for other reasons. Click on “Edit” and then the “Disable user” button to remove access to your partner account for that particular user.

#Change partner

There may be more than one partner with an account on The Bridge assigning roles to a user. If so, the user will see a list of partners they have access to, once they log in. The user can then select the partner they want to log in to.

The user may also switch their partner after logging in by navigating to Organisation settings → Switch org and selecting the new partner.

#API keys

Partners who have been onboarded can make API requests to (Website Name)'s systems. To authenticate such requests, partner admins can create and manage API keys on the Bridge.

(Website Name) currently supports two types of authentication—

• OAuth keys allow for one-to-many and many-to-one relationships between keys and product configurations. In addition to enabling/disabling keys, regenerating and deleting keys, OAuth also supports these features.
• JWT keys, where each product configuration has an unique key pair that is visible on the Bridge. JWT does not support any of the advanced functionality that OAuth offers.

Click on each one of them to learn more.

#JWT keys

At (Website Name), JSON Web Tokens, or JWTs, are mapped one-to-one with individual product configurations. To authorize API requests, each of your product configurations comes with its own auto-generated JWT key.

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.

The following table shows the full list of keys available at your org level, separated by environment, for each configuration you currently have. You can use the search feature to the top of the section to look for a specific key.

You'll see the product configuration name on each of these cards, which is also the key name. Click on the name to view the configuration associated with it. The schemeID and the secret for that configuration is also viewable on the card, which you can copy and use in your code.

Another way to view the JWT key assigned to a configuration is from within its profile page. Click on a product card from the “Configured products” page, and the click on the “⚙” settings icon on the right-hand side of the top section.

#Generate and manage OAuth Keys

Website Name uses OAuth as one of the supported methods to authenticate API requests. You can create and manage these keys on The Bridge.

This mechanism is quite flexible—you can setup a single master key for authenticating requests to all your product configurations, or access a single configuration using multiple keys.

For specified product configurations, the OAuth keys are used with the generate token API as explained below, and tokens are used to authenticate API requests made to (website name).

#Generate an OAuth key

Step 1—Login to the Bridge and head to Org settings

OAuth keys are created and managed at the organisation level. Currently only the Admin can create keys.

Click on the “Org settings” icon on the left navbar. Here, if you are an Admin, you should see the API keys card. Click on OAuth, which is our recommended protocol.

Step 2—Configure key details

You should be greeted by an empty page, nudging you to generate your first key. Click on the “Generate your first key” button. Now you should see a simple form like the one in the image below.

Select environment—A key can exist only in one environment. Sandbox keys access only sandbox configs, and production keys access only production configs.

Keep in mind that once a key is generated, it cannot change environments later.

Key name—This is just for you to easily identify a key and tell what a particular key can access.

For example, a name like “Bangalore Schools—Website Name BBPS” would indicate that the key has access to the school billers configured on the BBPS product, specifically in the Bangalore region.

Add products—This is where you can select the individual product configurations that this key can access.

Click the “Add products” button. The info panel opens on the right, with all your configured products in the selected environment grouped by type. You can also search for a particular product by name or ID. Clicking on a product tile adds it to the list, which you can see reflected on the main UI. Add and remove products as you wish, and close the info panel when satisfied.

Step 3 — Generate the key

Now the “Generate key” button should become enabled, after all the fields are filled. Click it, and you should see the clientID and secret for this key.

And done! You are now all set to use this key to make API requests to (website name). The key should also now be listed on the API keys main page, at the very top.

#Enable or disable a key

You can also enable or disable a key as required. API requests made with a key that is disabled would fail, until it is re-enabled.

Select a key from the main page, and you should now be in the Edit key page. In the “Key details” section, click on the switch to toggle between the enabled and disabled states.

Be sure to hit the “Save changes” button on the top to commit the edits.

The list page also indicates which keys are active, and which aren’t.

#Regenerate a key

In case a key is compromised at any point, you can regenerate the clientID and the secret for that key easily on the Bridge.

Click on the key to go to the Edit key page, and scroll down to the Credentials section. Click on the “Regenerate key” button. You will be asked for confirmation twice, as key regeneration cannot be undone.

Once you confirm, the old credentials would stop working, and be deleted, and a fresh clientID and secret would be generated for you to use. The name of the key and the products it can access are not affected.

This process is independent and instant, and does not need the “Save changes” button to be clicked.

#Delete a key

If for some reason you want to completely erase a key from our systems, you can delete the entire key configuration from the same Edit page. All API requests made with that key instantly stop working.

Just like regenerating a key, this process is irreversible, and Website Name too cannot retreive a deleted key. So think twice, maybe even thrice before deleting a key.

Select a key from the list page, and in the Edit page at the top, click on the red “Delete key“ button. Confirm twice, and the key is deleted, and removed from the list page.

#Generate Token API

An API to generate tokens, which are used to authorise any other API requests made to (website name). 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

If incorrect clientID and secret details are provided, Website Name could respond with the following error—

{
    "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"  : [],
    }
}

• The traceID in the above response is dynamic and can be shared with Website Name support team, if further debugging is required.

#How to use the token

Once you have a valid token available against product configuration(s), you can store it and use it to authorise an API call made to (website name), by setting the authorization request header as Bearer<token-value>.

On expiry

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

• Store clientID and secret.
• Generate new token with stored clientID and secret when token has expired. If the API you call returns 401 unauthorized, it could be an indication that the token has expired.
• Store the newly generated token and use for subsequent API calls.