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

📘

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.io for each example to switch to production.

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

Use your Sandbox API keys 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"
    }
}

Key Parameter

Data Type

Description

access_token

string

token that is required to connect Brick API

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 institutions list currently supported by Brick.

Key Parameter

Data Type

Description

id

integer

identification number of the transaction

name

string

Institution name

bank_code

string

institution code

country_code

string

country code for the institution

country_name

string

country name of the institution

primary_color

string

primary color of the institution for UI color

logo

string

logo of the institution

createdAt

string

date and time of the institution is up

updatedAt

string

date and time of the institution is updated

channels - id

integer

institution identification number

channels - institution_id

integer

institution identification number

channels - name

string

institution banking name (e.g. Internet banking or Mobile banking)

channels - type

string

Institution type (e.g. Individual or Corporate)

channels - createdAt

string

date and time of the institution is up

channels - updatedAt

string

date and time of the institution is updated

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 https://sandbox.onebrick.io/v1/ecommerce/identity
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful E-commerce connection through the widget which needs to be passed as the Bearer token in the Authorization header.

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

{
    “status”: 200,
    “message”: “OK”,
    “data”: {
        “personalProfile”: {
            “username”: “user_name”,
            “name”: “john doe”,
            “email”: “[email protected]”,
            “phoneNumber”: “6281234456789”,
            “storeName”: “John_Doe”,
            “gender”: “Laki-laki”,
            “dateOfBirth”: “2000-01-01T17:00:00.000+00:00”
        },
        “addressList”: [
            {
                “name”: “John Doe”,
                “phoneNumber”: “6281234456789",
                “address”: “kebayoran indah\nKOTA JAKARTA SELATAN-KEBAYORAN INDAH\nDKI JAKARTA\nID 12222"
            }
        ]
    }
}

Response Parameter

Keys Parameter

Data Type

Description

username

string

Username of the user

name

string

Full name of the user

email

string

Email of the user

phoneNumber

string

Phone number of the user

storeName

string

Name of the store belong to the user

gender

string

Gender of the user

storeName

string

Name of the store belong to theuser

dateOfBirth

string

Date of birth of the user

address

string

Address of the user

Step 5: Retrieve Buyer Transaction Data

curl https://sandbox.onebrick.io/v1/ecommerce/transaction
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful E-commerce connection through the widget which needs to be passed as the Bearer token in the Authorization header.

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

{
    “status”: 200,
    “message”: “OK”,
    “data”: {
        “transactionItem”: [
            {
                “transactionId”: “64123141583481”,
                “status”: “order completed”,
                “lastStatusUpdateTime”: “2021-01-13T02:45:04.000+00:00”,
                “itemDetails”: [
                    {
                        “itemName”: “HD / Kaos raglan polos lengan panjang Pria / fashion pria / baju raglan pria / kaos distro”,
                        “pricePerItem”: 19500,
                        “quantity”: 1,
                        “merchantName”: “HD Official Shop”
                    },
                    {
                        “itemName”: “HD / Kaos raglan polos lengan panjang Pria / fashion pria / baju raglan pria / kaos distro”,
                        “pricePerItem”: 19500,
                        “quantity”: 1,
                        “merchantName”: “HD Official Shop”
                    }
                ],
                “totalTransactionAmount”: 2,
                “TotalTransactionPriceAmount”: 39000
            },
            {
                “transactionId”: “64122329146048",
                “status”: “order completed”,
                “lastStatusUpdateTime”: “2021-01-13T07:25:08.000+00:00",
                “itemDetails”: [
                    {
                        “itemName”: “Handuk CID PREMIUM Murah dan Tebal 70x140cm / 420gr”,
                        “pricePerItem”: 37800,
                        “quantity”: 1,
                        “merchantName”: “THREADCOUNT”
                    },
                    {
                        “itemName”: “Handuk CID PREMIUM Murah dan Tebal 70x140cm / 420gr”,
                        “pricePerItem”: 37800,
                        “quantity”: 1,
                        “merchantName”: “THREADCOUNT”
                    }
                ],
                “totalTransactionAmount”: 2,
                “TotalTransactionPriceAmount”: 75600
            }
        ]
    }
}

transactionID

string

Unique identifier of the transaction

status

string

Latest status of the transaction

lastStatusUpdateTime

string

The time when the latest status has been updated

itemName

string

Detail name of the item

pricePerItem

integer

Price for each item

quantity

integer

Quantity of the particular item bought by the user

merchantName

string

Name of the merchant where the user did the transaction

totalTransactionAmount

integer

Total quantity of item bought by the user

TotalTransactionPriceAmount

integer

Total amount paid by the user

Step 6: Retrieve Merchant Identity Data

curl https://sandbox.onebrick.io/v1/ecommerce/merchant-identity
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful E-commerce connection through the widget which needs to be passed as the Bearer token in the Authorization header.

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

{
    “status”: 200,
    “message”: “OK”,
    “data”: {
        “merchantProfile”: {
            “shopName”: “John_Doe”,
            “joinedDate”: “2020-04-04T04:29:10.000+00:00”,
            “followers”: 0,
            “following”: 2,
            “totalProducts”: 3,
            “responseRate”: 88,
            “responseTime”: “Hitungan jam”,
            “shopRating”: 5.0,
            “totalRatingReceived”: 2
        },
        “addressList”: [
            {
                “name”: “John Doe”,
                “phoneNumber”: “628123456789",
                “address”: “kebayoran indah\nKOTA JAKARTA SELATAN-KEBAYORAN INDAH\nDKI JAKARTA\nID 12222"
            }
        ]
    }
}

Key Parameter

Data Type

Description

shopName

string

Name of the store belong to the user

joinedDate

timestamp

The date when the user create the merchant

followers

integer

Number of follower of the merchant

following

integer

Number of user followed by the merchant

totalProducts

integer

Number of products listed in the merchant

responseRate

integer

Percentage of chat responses compare to chat received by the merchant

responseTime

string

Average of how fast the merchant respond to a chat

shopRating

float

Average of rating received by the merchant

totalRatingReceived

integer

Total frequency of rating received by the merchant

address

string

Address of the merchant

Step 7: Retrieve Merchant Income Data

curl https://sandbox.onebrick.io/v1/ecommerce/merchant-income
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer user-access-token'

Where [user-access-token] is the access token generated after a successful E-commerce connection through the widget which needs to be passed as the Bearer token in the Authorization header.

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

{
    “status”: 200,
    “message”: “OK”,
    “data”: {
        “pendingIncome”: 0.0,
        “totalIncomeThisWeek”: 0.0,
        “totalIncomeThisMonth”: 249000.0,
        “totalIncomeOnTimeRange”: 0.0
    }
}

pendingIncome

double

Projected income from the incomplete transactions

totalIncomeThisWeek

double

Total income received from the complete transaction in the last 7 days

totalIncomeThisMonth

double

Total income received from the complete transaction in the last 30 days

totalIncomeOnTimeRange

double

Total income received from the complete transaction based on date range

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


Did this page help you?