Sign UpLog In

Tutorial: Connect Financial Institution A/C (with MFA) & view Transactions

The following steps are only applicable for Financial institutions that require OTP or other types of Multi-Factor Authentication. If you are using Financial Institution that does not require OTP or Multi-Factor Authentication please go to this Tutorial: Connect Financial Institution A/C & view Transactions

📘

In this section, you will learn how to connect with a financial institution and access your first financial data like accounts, balance and transactions.

Brick is currently offering two environments:

  • Sandbox, a sandbox environment with test data perfect for test and development phases.
  • Production, a live environment used in production with real connections to institutions.

To generate your keys for each environment, have a look to our guide to get your Brick API keys or Sign Up now!.

📘

In the following examples we will use the sandbox environment.
Change the base URL to https://api.onebrick.io for each example to switch to production.

Step 1: Generate a JWT bearer token (Public access token)

Use your Sandbox API keys viz. a ClientID & ClientSecret with the generate public token api to get a JWT((JSON Web Token). This JWT or what we call a public access token can be used to launch the Brick widget and access institution list. 

curl -u Client ID:Client Secret https://sandbox.onebrick.io/v1/auth/token

{
    "status": 200,
    "message": "OK",
    "data": {
        "access_token": "public-sandbox-b70bcf83-87a1-4f2c-8f2a-16d48021413a"
    }
}

Step 2: List all supported institutions ( Optional )

You can use this JWT/public access token to view the list of institutions currently supported by Brick or jump to Step 3 directly to try the Brick Front End Widget and connect a Financial Institution account to view its data. 

curl https://sandbox.onebrick.io/v1/institution/list
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer JWT-public-access-token'

Where [JWT-public-access-token] is the public access token/JWT generated in the previous step which needs to be passed as the Bearer token in the Authorization header.

The API responds with the institutions list currently supported by Brick.

Step 3: Launch Brick Widget

Use the JWT/public-access-token to launch the brick widget in your application and let your users connect their financial Institution accounts with your application.
To launch the brick UI widget you need to construct the url in the following format-
https://cdn.onebrick.io/sandbox-widget/v1/?accessToken=public-sandbox-access-token

📘

Notice that the URL above is a newer version ( V1 ) of our Brick Widget that contained a new feature inside comparing to the old version. Currently, we still offer you our old Brick Widget where your end-user can only connect a single account at a time ( https://cdn.onebrick.io/sandbox-widget/?accessToken=public-sandbox-access-token ) until further notice.

Therefore, we encourage you to integrate and experienced our newest feature on Brick Widget as soon as possible where your end-user have the ability to connect multiple accounts/institutions in single flow.

P.S : This feature would be very helpful for you to have as much information from the connected accounts/institutions from your end-users.

There are some optional parameters that can be added to the above URL for customizations which can be seen here.

Read the Brick Widget Section to see in-depth integration steps.

Step 4: Retrieve Financial Institution accounts

Retrieve List of all accounts for this user

Using the previously created user-access-token in Step 3, we can now retrieve the information about different Financial Institution accounts connected by this user.

In the postman application, make a GET request with the following link,

https://sandbox.onebrick.io/v1/account/list

Then, in Authorization tab, input the Bearer Token with user-access-token from Step 3 as the value. Where [user-access-token] is the access token generated after successful Financial Institution connection through the widget which needs to be passed as the Bearer token in the Authorization header.

So in your postman, it should look like this.

1323

The token in this picture will be different from your user-access-token

After you have click the send GET request, you will get JSON response like the following.

{
    "status": 428,
    "message": "An OTP is required by the institution to login",
    "data": {
        "sessionId": "8t7kFhWgwawUDDFwAGTgz9vsUmf9hd",
        "requestId": "e408f1be-3429-49db-9139-6b934dc64769",
        "token": null,
        "duration": 50000
    }
}

Next, copy the sessionId value (from the above code the sessionId value is "8t7kFhWgwawUDDFwAGTgz9vsUmf9hd") to a new postman POST request.

https://sandbox.onebrick.io/v1/account/list

Then, in Body tab, input the 2 keys, sessionId with sessionId that you have just received from the GET request, and token with OTP that you received from your mobile number. Where OTP is the access token generated after a successful Financial Institution connection through the widget.

So in your postman, it should look like this,

1320

The api responds with accounts associated with the user who logged in using the Brick widget.

{
    "status": 200,
    "message": "OK",
    "data": [
        {
            "accountId": "LGWgrp3xMMlpkNVlt1JhRA==",
            "accountHolder": "MUHAMMAD ABDULLOH",
            "accountNumber": "90270107748",
            "balances": {
                "available": 11019.0,
                "current": 11019.0
            }
        }
    ]
}

Retrieve Full-details of a particular Financial Institution account

Using the previously created user-access-token in Step 3, we can now retrieve the information about different Financial Institution accounts connected by this user.

In the postman application, make a GET request with the following link,

https://sandbox.onebrick.io/v1/account/fulldetail

Then, in Authorization tab, input the Bearer Token with user-access-token from Step 3 as the value. Where [user-access-token] is the access token generated after successful Financial Institution connection through the widget which needs to be passed as the Bearer token in the Authorization header.

So in your postman, it should look like this.

1406

After you have click the send GET request, you will get JSON response like the following.

{
    "status": 428,
    "message": "An OTP is required by the institution to login",
    "data": {
        "sessionId": "eU8gFN0WQtbemc0NNXEVnYhy2zB5S5",
        "requestId": "e2adc9f0-2d56-4312-ae71-48aede28e70e",
        "token": null,
        "duration": 50000
    }
}

Next, copy the sessionId value (from the above code the sessionId value is "8t7kFhWgwawUDDFwAGTgz9vsUmf9hd") to a new postman POST request.

https://sandbox.onebrick.io/v1/account/fulldetail

Then, in Body tab, input the 2 keys, sessionId with sessionId that you have just received from the GET request, and token with OTP that you received from your mobile number. Where OTP is the access token generated after a successful Financial Institution connection through the widget.

So in your postman, it should look like this,

1398

The api responds with accounts associated with the user who logged in using the Brick widget.

{
    "status": 200,
    "message": "OK",
    "data": {
        "account": {
            "accountId": "LGWgrp3xMMlpkNVlt1JhRA==",
            "accountHolder": "MUHAMMAD ABDULLOH",
            "accountNumber": "90270107748",
            "balances": {
                "available": 11022.0,
                "current": 11022.0
            }
        },
        "transactions": [
            {
                "id": 0,
                "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
                "category_id": 0,
                "subcategory_id": 0,
                "merchant_id": 0,
                "location_country_id": 0,
                "location_city_id": 0,
                "outlet_outlet_id": 0,
                "amount": 1.0,
                "date": "2020-12-28",
                "description": "Pajak Bunga",
                "status": "CONFIRMED",
                "direction": "out"
            },
            {
                "id": 0,
                "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
                "category_id": 0,
                "subcategory_id": 0,
                "merchant_id": 0,
                "location_country_id": 0,
                "location_city_id": 0,
                "outlet_outlet_id": 0,
                "amount": 4.0,
                "date": "2020-12-28",
                "description": "Bunga",
                "status": "CONFIRMED",
                "direction": "in"
            }
         ]
}

Retrieve details of a particular Financial Institution account

Using the accountId retrieved from the previous API- accounts list, you can get in-depth details about the account include any identifying information that's available on the account.

curl https://sandbox.onebrick.io/v1/account/detail?accountId=accountId 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful Financial Institution connection through the widget which needs to be passed as the Bearer token in the Authorization header. And accountId is the identification of account for which you want the details.

The API responds with details of the account associated with the accountId.

{
    "status": 200,
    "message": "OK",
    "data": {
        "accountId": "S8vzhyw3owDtYDOB87va==",
        "accountHolder": "John Doe",
        "accountNumber": "987-0675-789",
        "balances": {
            "available": 7500000.0,
            "current": 7500000.0
        }
    }
}

Retrieve balance of a particular Financial Institution account

Using this api you can get latest balance information for a particular accountId.

curl https://sandbox.onebrick.io/v1/account/balance?accountId=accountId 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer user-access-token'

Where [user-access-token] is the access token generated after successful Financial Institution connection through the widget which needs to be passed as the Bearer token in the Authorization header. And accountId is the identification of the account for which you want the details.

Step 5: Retrieve transactions

Using the previously generated user-access-token, we can now retrieve all transactions for this user from all his Financial Institution accounts under the login used with the brick widget.

In the postman application, make a GET request with the following link,

https://sandbox.onebrick.io/v1/transaction/list?from=2020-11-01&to=2020-12-31

Where, parameter [from] and [to] can be change to your liking. In the example, we will retrieve transaction that happened between 2020-11-01 to 2020-12-31.

Then, in Authorization tab, input the Bearer Token with user-access-token from Step 3 as the value. Where [user-access-token] is the access token generated after successful Financial Institution connection through the widget which needs to be passed as the Bearer token in the Authorization header.

So in your postman, it should look like this,

1322

After you have click the send GET request, you will get JSON response like the following.

{
    "status": 428,
    "message": "An OTP is required by the institution to login",
    "data": {
        "sessionId": "Z6Jp7e9rnHYIXdcG35Wfeu3TYHeu6k",
        "requestId": "ae703314-a5ad-4caa-800d-3a47cf46d5fd",
        "token": null,
        "duration": 50000
    }
}

Next, copy the sessionId value (from the above code the sessionId value is "Z6Jp7e9rnHYIXdcG35Wfeu3TYHeu6k") to a new postman POST request.

https://sandbox.onebrick.io/v1/transaction/list

Then, in Body tab, input the 4 keys, sessionId with sessionId that you have just received from the GET request, token with OTP that you received from your mobile number, from with starting date that you want to retrieve from transaction from, and to with ending date that you want to retrieve your transaction to.

So in your postman, it should look like this,

1326

The api responds with rich transaction data of all the accounts associated with the user under his login.

{
    "status": 200,
    "message": "OK",
    "data": [
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 6500.0,
            "date": "2020-12-01",
            "description": "CASHBACK FIRST TOPUP",
            "status": "CONFIRMED",
            "direction": "in"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 100244.0,
            "date": "2020-11-30",
            "description": "FLIPTECH LENTERA INSPIRASI PERTIWI",
            "status": "CONFIRMED",
            "direction": "out"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 100000.0,
            "date": "2020-11-30",
            "description": "December trx FLP39067839",
            "status": "CONFIRMED",
            "direction": "in"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 1.0,
            "date": "2020-11-27",
            "description": "Pajak Bunga",
            "status": "CONFIRMED",
            "direction": "out"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 7.0,
            "date": "2020-11-27",
            "description": "Bunga",
            "status": "CONFIRMED",
            "direction": "in"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 145051.0,
            "date": "2020-11-17",
            "description": "FLIPTECH LENTERA INSPIRASI PERTIWI",
            "status": "CONFIRMED",
            "direction": "out"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 150094.0,
            "date": "2020-11-17",
            "description": "FLIPTECH LENTERA INSPIRASI PERTIWI",
            "status": "CONFIRMED",
            "direction": "out"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 200098.0,
            "date": "2020-11-17",
            "description": "FLIPTECH LENTERA INSPIRASI PERTIWI",
            "status": "CONFIRMED",
            "direction": "out"
        },
        {
            "id": 0,
            "account_id": "LGWgrp3xMMlpkNVlt1JhRA==",
            "category_id": 0,
            "subcategory_id": 0,
            "merchant_id": 0,
            "location_country_id": 0,
            "location_city_id": 0,
            "outlet_outlet_id": 0,
            "amount": 500000.0,
            "date": "2020-11-16",
            "description": "MUHAMMAD ABDULLOH",
            "status": "CONFIRMED",
            "direction": "in"
        }
    ]
}

Status Error caused by MFA

OTP Expired

OTP received from mobile phone is expired, it will return status 400.

{
    "status": 400,
    "message": "Bad Request",
    "data": "Your request exceeding the time limit"
}

Request not found

The application may not found your request, you can try to redo the request for this error.

{
    "status": 500,
    "message": "Internal Server Error",
    "data": "Service unavailable"
}

Conclusion

Using this step by step guide you have been able to get a first preview on Brick's API and how to integrate Brick in your website or application

Updated over 2 years ago