Tutorial: Connect to E-commerce and View Buyer & Merchant Data

The following steps are only applicable to E-commerce Financial institutions.

In this section, you will learn how to connect with E-commerce and access your first E-commerce from both Buyer & Seller.

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.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 frombrick dashboard.

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

Data Product

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.

curl --request GET \
     --url https://sandbox.onebrick.io/v2/data/auth/token \
     --header 'Accept: application/json' \
     --header 'password: client_secret' \
     --header 'username: client_id'

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: 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 with E-Commerce

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.

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

Generating user_access_token in E-Commerce is a two-step process. First generate OTP through Generate OTP for E-Commerce and then generate user_access_token through Generate User access token for E-Commerce

Step 4: Retrieve Buyer Identity Data

curl --request GET \
     --url https://sandbox.onebrick.io/v2/data/ecommerce/buyer/identity \
     --header 'Accept: application/json' \
     --header 'public_access_token: public_access_token' \
     --header 'user-access-token: user_access_token'

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.

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.

{
  "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":"We are successfully able to fetch the buyer data",
      "method":"GET",
      "api":"/v2/data/ecommerce/buyer/identity”,   
      "job_id": "KVWJUrwQ78333309",  
      "personal_profile":{
         "username":"user_name",
         "name":"john doe",
         "email":"[email protected]",
         "phone_number":"6281234456789",
         "store_name":"John_Doe",
         "gender":"Laki-laki",
         "date_of_birth":"2000-01-01T17:00:00.000+00:00"
      },
      "count":{{"Objects_in_address_list"}},
      "address_list":[
         {
            "name":"John Doe",
            "phone_number":"6281234456789",
            "address":"kebayoran indah",
            "last_1_month_transaction_quantity":20,
            "last_3_month_transaction_quantity":50,
            "last_6_month_transaction_quantity":72
         },
         {
            "name":"Doe",
            "phone_number":"62812344567",
            "address":"Vila Weliminium, Gang IV No.2",
            "last_1_month_transaction_quantity":10,
            "last_3_month_transaction_quantity":20,
            "last_6_month_transaction_quantity":30
         }
      ]
   },
   "metadata":{
      "source":{{API/Widget/Dashboard/SDK/Portal}},
      "entity":"Data"
   },
   "error":null
}

Step 5: Retrieve Buyer Transaction Data

curl --request GET \
     --url https://sandbox.onebrick.io/v2/data/ecommerce/buyer/transaction \
     --header 'Accept: application/json' \
     --header 'public_access_token: public_access_token' \
     --header 'user-access-token: user_access_token'

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.

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.

{
  "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":"We are successfully able to fetch the buyer transations",
      "method":"GET",
      "api":"/v2/data/ecommerce/buyer/transaction”,   
      "job_id": "KVWJUrwQ78333309",  
      "count":{{number_of_objects_in_transaction_item}}, 
      "transaction_item":[
         {
            "transaction_id":"64123141583481",
            "status":"order completed",
            "last_status_update_time":"2021-01-13T02:45:04.000+00:00",
            "count":{{"Objects in item details"}},
            "item_details":[
               {
                  "item_name":"HD / Kaos raglan polos lengan panjang Pria",
                  "price_per_item":19500,
                  "quantity":1,
                  "merchant_name":"HD Official Shop"
               },
               {
                  "item_name":"HD / Kaos raglan polos lengan panjang”,                       
                  “price_per_item":19500,
                  "quantity":1,
                  "merchant_name":"HD Official Shop"
               }
            ],
            "total_transaction_amount":2,
            "total_transaction_price_amount":39000
         }
      ]
   },
   "metadata":{
      "source":{{API/Widget/Dashboard/SDK/Portal}},
      "entity":"Data"
   },
   "error":null
}

Step 6: Retrieve Merchant Identity Data

curl --request GET \
     --url https://sandbox.onebrick.io/v2/data/ecommerce/merchant/identity \
     --header 'Accept: application/json' \
     --header 'public_access_token: public_access_token' \
     --header 'user-access-token: user_access_token'

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.

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.

{
  "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":"We are successfully able to fetch the seller data  ",
      "method":"GET",
      "api":"/v2/data/ecommerce/merchant/identity”,   
      "job_id": "KVWJUrwQ78333309",  
      "merchant_profile":{
         "shop_name":"John_Doe",
         "joined_date":"2020-04-04T04:29:10.000+00:00",
         "followers":0,
         "following":2,
         "total_products":3,
         "response_rate":88,
         "response_time":"Hitungan jam",
         "shop_rating":5.0,
         "total_rating_received":2
      },
      "count":{{"Objects in address list"}},
      "address_list":[
         {
            "name":"John Doe",
            "phone_number":"628123456789",
            "address":"kebayoran indah\nKOTA JAKARTA SELATAN",
            "last_1_month_transaction_quantity":20,
            "last_3_month_transaction_quantity":50,
            "last_6_month_transaction_quantity":72
         },
         {
            "name":"Doe",
            "phone_number":"62812344567",
            "address":"Vila Weliminium, Gang IV No.2, Jimbaran, KAB. BADUNG-JIMBARAN, BALI, ID 80363",
            "last_1_month_transaction_quantity":10,
            "last_3_month_transaction_quantity":20,
            "last_6_month_transaction_quantity":30
         }
      ]
   },
   "metadata":{
      "source":{{API/Widget/Dashboard/SDK/Portal}},
      "entity":"Data"
   },
   "error":null
}

Step 7: Retrieve Merchant Income Data

curl --request GET \
     --url 'https://sandbox.onebrick.io/v2/data/ecommerce/merchant/income?from=11-02-2020&to=11-04-2020' \
     --header 'Accept: application/json' \
     --header 'public_access_token: public_access_token' \
     --header 'user-access-token: user_access_Token'

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.

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.

{
  "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":"We are successfully able to fetch the merchant income ",
      "method":"GET",
      "api":"/v2/data/ecommerce/merchant/income”
      "job_id": "KVWJUrwQ78333309",  
      "pending_income":0.0,
      "total_income_this_week":0.0,
      "total_income_this_month":249000.0,
      "total_income_on_time_range":0.0
   },
   "metadata":{
      "source":{{API/Widget/Dashboard/SDK/Portal}},
      "entity":"Data"
   },
   "error":null
}

Step - 3 Retrieve merchant transaction data

curl --request GET \
     --url https://sandbox.onebrick.io/v2/data/ecommerce/merchant/transaction \
     --header 'Accept: application/json' \
     --header 'public_access_token: public_access_token' \
     --header 'user-access-token: user_access_token'

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.

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.

{
  "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":"We are successfully able fetch transitions for merchant",
      "method":"GET",
      "api":"/v2/data/ecommerce/merchant/transaction”
      "job_id": "KVWJUrwQ78333309",  
      "count":{{"Obejcts in transaction item"}},
      "transaction_item":[
         {
            "transaction_id":"64123141583481",
            "status":"order completed",
            "last_status_update_time":"2021-01-13T02:45:04.000+00:00",
            "count":2,
            "item_details":[
               {
                  "item_name":"abc",
                  "price_per_item":19500,
                  "quantity":1,
                  "buyer_name":"HD Official Shop"
               },
               {
                  "item_name":"asssdff",
                  "price_per_item":19500,
                  "quantity":1,
                  "buyer_name":"HD Official Shop"
               }
            ],
            "total_transaction_amount":2,
            "total_transaction_price_amount":39000
         }
      ]
   },
   "metadata":{
      "source":{{API/Widget/Dashboard/SDK/Portal}},
      "entity":"Data"
   },
   "error":null
}

Conclusion

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