Tutorial: Connect E-wallet A/C & view Transactions
The following steps are only applicable to eWallets Financial institutions.
In this section, you will learn how to connect with an E-wallet and access your first financial data like accounts, balances, 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 at 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.com/v2 for using the APIs in production.
Our new version of APIs(v2) is callback-based APIs, So if you have not set up a callback URL till now, Please set it from brick dashboard.
Step 1: Generate a JWT bearer token (Public access token)
Use public token API with sandbox API keys with client_id & client_secret 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 the institution list.
Data Product
curl --request GET \
--user client_id:client_secret
--url https://sandbox.onebrick.io/v2/data/auth/token \
--header 'Accept: application/json'
This API gives give you a JWT/public access token that is only valid for the next 30 minutes and which can be used to launch the Brick Widget and access Brick APIs. It can be used multiple times in 30 minutes.
{
"status": 200,
"data": {
"message": "We are successfully able to fetch data",
"access_token": "token",
"primary_color": "#97FF00",
"expiry": 1654681846751
},
"metadata": {
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "AUTH"
},
"error": null
}
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.
curl --request GET \
--url https://sandbox.onebrick.io/v2/data/institution/list \
--header 'Accept: application/json' \
--header 'public_access_token: Bearer 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 institution's 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.
1. OVO
From the above picture, you can choose E-wallet (OVO) to continue with. Then once you choose OVO, you will need to key in your Registered Mobile Number.
If your mobile number is available, then OVO will prompt you for your OTP and PIN refer to the following picture.
Finally, you will be able to see the user-access-token. Read the Brick Widget to see in-depth integration steps. You can check more details about API to generate user_access_token here.
please note that since OVO only allows 1 device connection, you would need to key-in your PIN and OTP, if you have already login to OVO applications.
2. Gopay
From the above picture, you can choose E-wallet (Gopay) to continue with. Then once you choose Gopay, you will need to key in your Registered Mobile Number.
If your mobile number is available, then GoPay will prompt you for your OTP refer to the following picture.
Finally, you will be able to see the user-access-token. Read the Brick Widget Section to see in-depth integration steps. You can check more details to generate user_access_token here
please note that since Gopay only allows 1 device connection, you would need to key-in your OTP, if you have already login to Gopay applications.
3. ShopeePay
From the above picture, you can choose E-wallet (ShopeePay) to continue with. Then once you choose ShopeePay, you will need to key in your Registered Mobile Number and Password.
If your mobile number is available and password is correct, then ShopeePay will send you a link to you via SMS that you need to click, after clicking the link on the SMS, you need to tick the box and continue.
refer to the following picture.
Finally, you will be able to see the user-access-token. Read the Brick Widget Section to see in-depth integration steps.
3. Dana
From the above picture, you can choose E-wallet (Dana) to continue with. Then once you choose Dana, you will need to key in your Registered Mobile Number and PIN Number.
If your mobile number is available and password is correct, then Dana will send you a an OTP via SMS that you need to key in.
refer to the following picture.
Step 4: Retrieve Financial Institution & E-wallet accounts
Retrieve List of all accounts for this user
Using the previously created user-access-token in Step 3 and public_access_token in Step 1, We can now retrieve the information about different financial institution accounts connected by this user.
curl --request GET \
--url https://sandbox.onebrick.io/v2/data/account/list \
--header 'Accept: application/json' \
--header 'public_access_token: Bearer public_access_token' \
--header 'user_access_token: Bearer user_access_token'
Where [user-access-token] is the access token generated after a successful financial Institution connection through the widget which needs to be passed in headers as user_access_token.
This API is Async API, So once you send the request you will receive the acceptance response synchronously and then will receive the data in your callback URL asynchronously. If you haven't set the callback URL till now, Feel free to set it from here.
The API responds with accounts associated with the user who logged in using the Brick widget.
After you have clicked the send GET request, you will get a JSON response like the following.
{
"status": 202,
"data": {
"job_id": "KVWJUrwQ78333309",
"message": "We are processing your request and will send the data in the callback URL."
},
"metadata": {
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "Data"
},
"error": null
}
{
"data": {
"method": "GET",
"api": "/v2/data/account/list",
"message": "We are able to fetch a list of accounts of end-users",
"job_id": "MaBkJUww03291282",
"count": "1",
"last_updated_at": "1662103296909",
"session": "valid",
"account_list": [
{
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_holder": "ABC",
"account_number": "88XXXXXX6",
"type": "Savings",
"currency": "IDR"
"balances": {
"available": 2195258.5,
"current": 2195258.5,
"limit": null
},
{
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_holder": "XYZ ",
"account_number": "88XXXXXX7",
"type": "Savings",
"currency": "IDR"
"balances": {
"available": 2111258.5,
"current": 195258.5,
"limit": null
},
}
]
},
"metadata": {
"entity": "Data",
"source": "API"
},
"error": null,
"status": 200
}
Retrieve details of a particular Financial Institution & E-wallet account
Using the account_id retrieved from the previous API- accounts list, You can get in-depth details about the account including any identifying information that's available on the account.
curl --request GET \
--url 'https://sandbox.onebrick.io/v2/data/account/detail?account_id=account_id' \
--header 'Accept: application/json' \
--header 'public_access_token: Bearer public_access_toke' \
--header 'user_access_token: Bearer user_access_token'
Where [user-access-token] is the access token generated after a 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.
Where [user-access-token] is the access token generated after a successful financial Institution connection through the widget which needs to be passed as the user_access_token and account_id is the identification of the account for which you want the details.
This API is Async API, So once you send the request you will receive the acceptance response synchronously and then will receive the data in your callback URL asynchronously. If you haven't set the callback URL till now, Feel free to set it from here.
The API responds with details of the account associated with the account_id.
{
"status": 202,
"data": {
"job_id": "KVWJUrwQ78333309",
"message": "We are processing your request and will send the data in the callback URL."
},
"metadata": {
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "Data"
},
"error": null
}
{
"data": {
"method": "GET",
"api": "/v2/data/account/detail",
"job_id": "GYGJ4Tbb03371498",
"last_updated_at": "1662103375848",
"message": "We are able to fetch account details for you",
"session": "valid",
"account_details": {
"account_holder": "Taufic Hidayat",
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"address": null,
"email": null,
"ktp_number": null,
"phone_number": null,
"type": "Savings",
"balances": {
"available": 2195258.5,
"current": 2195258.5,
"limit": null
},
"currency": "IDR"
}
},
"metadata": {
"entity": "Data",
"source": "API"
},
"error": null,
"status": 200
}
Step 5: Retrieve transactions
Using the previously generated user-access-token in step 3 and public_access_token in step 1, We can now retrieve all transactions for a user from all his financial institution account under the login used with the brick widget.
curl --request GET \
--url 'https://sandbox.onebrick.io/v2/data/transaction/list?from=2022-01-15&to=2022-03-20' \
--header 'Accept: application/json' \
--header 'public_access_token: Bearer public_access_token' \
--header 'user_access_token: Bearer user_access_token'
Where parameters [from] and [to] can be changed to your liking. In the example, we will retrieve transactions that happened between 15-01-2022 to 20-03-2022.
Where [user-access-token] is the access token generated after a successful Financial institution connection through the widget which needs to be passed as the headers.
This API is Async API, So once you send the request you will receive the acceptance response synchronously and then will receive the data in your callback URL asynchronously. If you haven't set the callback URL till now, Feel free to set it from here.
The API responds with rich transaction data of all the accounts associated with the user under his login.
{
"status": 202,
"data": {
"job_id": "KVWJUrwQ78333309",
"message": "We are processing your request and will send the data in the callback URL."
},
"metadata": {
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "Data"
},
"error": null
}
{
"data": {
"method": "GET",
"api": "/v2/data/transaction/list",
"job_id": "PRwR0rlr03400817",
"message": "We are able to fetch transactions for you",
"count": "5",
"last_updated_at": 1662103406871,
"session": "valid",
"transaction_list": [
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10001,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10001.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-1",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10002,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10002.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-2",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10000,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10000.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-3",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10001,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10001.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-4",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-19",
"amount": 15000,
"description": "BIAYA ADM",
"status": "CONFIRMED",
"direction": "out",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220819-1",
"transaction_type": "Savings",
"category": {
"category_id": 4,
"category_name": "payment",
"classification_group_id": 21,
"classification_group": "fee & tax",
"classification_subgroup_id": 63,
"classification_subgroup": "admin fee"
}
}
]
},
"metadata": {
"entity": "Data",
"source": "API"
},
"error": null,
"status": 200
}
Step 6: Refresh Expired Session and Retrieve Transactions
When the e-wallet account session is expired, Brick will return the last updated transaction data of the user with the specified time of the update in the "lastUpdateAt" variables, for example "lastUpdateAt": "2022-01-04 16:42 GMT+0700" as well as the status of the session itself in the "session" variable, for example "session": "expired"
{
"status": 200,
"message": "OK",
"lastUpdateAt": "2022-01-04 16:42 GMT+0700",
"session": "expired",
"data": [
{
"id": 0,
"institution_id": 12,
"account_id": "800103xxxxxx3001",
"category_id": 0,
"subcategory_id": 0,
"merchant_id": 0,
"merchant_name": "TOKOPEDIA",
"location_country_id": 0,
"location_city_id": 0,
"outlet_outlet_id": 0,
"amount": 5.0,
"date": "2021-04-04",
"description": "TOKOPEDIA Rewards",
"status": "CONFIRMED",
"direction": "in"
}
]
}
In order to refresh the e-wallet account session and access the fresh transaction data, there are two steps that need to be done:
1. Making a POST request to trigger an OTP to be sent to user
curl --request POST \
--url https://sandbox.onebrick.io/v2/data/transaction/list \
--header 'Accept: application/json' \
--header 'public_access_token: Bearer public_access_token' \
--header 'user_access_token: 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.
This API is Async API, So once you send the request you will receive the acceptance response synchronously and then will receive the data in your callback URL asynchronously. If you haven't set the callback URL till now, Feel free to set it from here.
For example, In the postman application, make a POST request with the following link,
https://sandbox.onebrick.io/v2/data/transaction/list?from={from}&to={to}
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,
After you have click the send POST request, you will get JSON response like the following.
{
"status": 202,
"data": {
"job_id": "KVWJUrwQ78333309",
"message": "We are processing your request and will send the data in the callback URL."
},
"metadata": {
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "Data"
},
"error": null
}
{
"status": 200,
"data": {
"message": "Please open the link sent to your phone number and click submit button in this page to continue the process",
"method":"POST",
"api":"/v2/data/transaction/list",
"job_id": "KVWJUrwQ78333309",
"session_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxx",
"request_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
"token": null,
"duration": 500000
},
"metadata":{
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "Data"
},
"error": null
}
2. Making a PATCH request and providing the session_id that is received from previous POST request and OTP that is sent to user after making previous POST request
Using the session_id retrieved from the previous request, the OTP that is sent to user and also the specified from and to date, you can use it to make a new PATCH request to the following link
curl --request PATCH \
--url 'https://sandbox.onebrick.io/v2/data/transaction/list' \
--header 'Accept: application/json' \
--header 'public_access_token: Bearer public_access_token' \
--header 'user_access_token: Bearer user_access_token'
--form 'token="e-wallet OTP/LINK"' \
--form 'from="2021-12-01"' \
--form 'to="2021-12-30"' \
--form 'sessionId="whVOGr1SpBNFH0dJ3PjupheSWXU31t"'
The API responds with the rich latest transaction data of all the accounts associated with the user under his login.
This API is Async API, So once you send the request you will receive the acceptance response synchronously and then will receive the data in your callback URL asynchronously. If you haven't set the callback URL till now, Feel free to set it from here.
For example, in the Postman application copy the sessionId value (from the above code the sessionId value is "NYnidfEYsMvTeJRSwegtuY9zyZBopT") to a new postman PATCH request.
https://sandbox.onebrick.io/v2/data/transaction/list?from={from}&to={to}
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,
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 user, 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,
{
"status": 202,
"data": {
"job_id": "KVWJUrwQ78333309",
"message": "We are processing your request and will send the data in the callback URL."
},
"metadata": {
"source": {{API/Widget/Dashboard/SDK/Portal}},
"entity": "Data"
},
"error": null
}
After you have click the send PATCH request, you will get JSON response like the following.
{
"data": {
"method": "PATCH",
"api": "/v2/data/transaction/list",
"job_id": "PRwR0rlr03400817",
"message": "We are able to fetch transactions for you",
"count": "5",
"last_updated_at": 1662103406871,
"session": "valid",
"transaction_list": [
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10001,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10001.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-1",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10002,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10002.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-2",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10000,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10000.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-3",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-12",
"amount": 10001,
"description": "TRSF E-BANKING CR 1208/FTSCY/WS95051 10001.00 BRICK TEKNOLOGI IN",
"status": "CONFIRMED",
"direction": "in",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220812-4",
"transaction_type": "Savings",
"category": {
"category_id": 5,
"category_name": "transfer-in ",
"classification_group_id": 26,
"classification_group": "account transfer-in",
"classification_subgroup_id": 92,
"classification_subgroup": "others account transfer-in"
}
},
{
"id": 0,
"account_id": "XH3c7dtoskIqAmEbwHAM7Q==",
"account_number": "8831355336",
"account_currency": "IDR",
"institution_id": 2,
"merchant_id": 0,
"outlet_outlet_id": 0,
"location_city_id": 0,
"location_country_id": 0,
"date": "2022-08-19",
"amount": 15000,
"description": "BIAYA ADM",
"status": "CONFIRMED",
"direction": "out",
"reference_id": "XH3c7dtoskIqAmEbwHAM7Q==-20220819-1",
"transaction_type": "Savings",
"category": {
"category_id": 4,
"category_name": "payment",
"classification_group_id": 21,
"classification_group": "fee & tax",
"classification_subgroup_id": 63,
"classification_subgroup": "admin fee"
}
}
]
},
"metadata": {
"entity": "Data",
"source": "API"
},
"error": null,
"status": 200
}
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 1 year ago