Quickstart

A quick introduction to build with Brankas!

Introduction

Let’s test out running Brankas locally. You’ll need API keys, which you can receive by signing up in the Dashboard.

API Keys on Brankas Dashboard

You’ll have two different API keys, and there are two different Brankas environments. Today we’ll start in the Sandbox environment. View the API Keys section of the Dashboard to find your Sandbox secret.

API Key

Environment Explanation
Sandbox Get started with test credentials and life-like data
Live Ready to transact with real customer

Brankas Products

Brankas has several products in nature such as payment initiation and data retrieval. Thus we will explain the quickstart documentation for each of Brankas products since it’s different from one to another.

Product Explanation
Direct Providing direct bank transfer as a payment option in your business
Disburse Deliver funds to multiple bank accounts
Statement Monthly transactional data from bank accounts
Pay Bank transfer option for SMEs
Account Opening Opening a saving account online

If you get stuck at any point in the Quickstart, help is just a click away! Ask us via email at support@brank.as.

Quickstart Setup

Once you have your API keys, it’s time to run the Brankas Quickstart locally! The API Keys will be used to identify your application and help Brankas ensure that your application is authorized to access specific data points (read more about API Keys here).

For security purposes, you will be required to enter your API Key under the API headers for every subsequent API call. Make sure to keep the API Key safe. If your API Key is lost or compromised, simply generate a new one on Brankas dashboard > API Keys menu.

API Environment

Brankas provides both sandbox and live environments for use.

Product Sandbox Live
Direct direct.sandbox.bnk.to direct.bnk.to
Disburse disburse.sandbox.bnk.to disurse.bnk.to
Statement statement.sandbox.bnk.to statement.bnk.to
Pay api.pay.sandbox.bnk.to api.pay.bnk.to
Account Opening account-opening.sandbox.bnk.to account-opening.bnk.to

Authorization

All requests to the Brankas API must be authorized using your unique API Key. This helps to ensure that your connection to the API is secure.

In order to prevent accidental misuse of the credentials, you will need to generate a unique API key per environment. There are two environments to set keys for:

  • Sandbox: Select Sandbox Mode in Brankas dashboard when generating the API key and you will be able to call endpoints that have a <product>.sandbox.bnk.to base URL.
  • Live: Once you have completed any Go Live requirements, select Live Mode in Brankas dashboard when generating the API key and you will be able to call endpoints that have a <product>.bnk.to base URL.
-H 'Content-Type:application/json' \
-H 'x-api-key:O66Q9XWlyoV0A5xhTeF2uRpVXFPXqmutUESQEB6C5ziQJp3lVSHR5eiDkAE8823R' \

Postman Collection

The Brankas Postman collection is a convenient tool for exploring Brankas API endpoints without writing code. The Postman collection provides pre-formatted requests for almost all of Brankas’s API endpoints. All you have to do is fill in your API keys and any arguments. To get started, check out our postman collection below.

Setting up for Direct

Brankas Direct provides Fintechs and SMEs with an API-driven payment solution that allows them to digitally transact with their end users and customers by debiting their online bank accounts and transferring directly to their accounts payable accounts. By leveraging Brankas Direct, enterprises are able to execute fund transfer based transactions over a growing basket of banks via a single set of APIs.

Getting Started with Direct

One more step before you can start making a request with Brankas Direct. After getting your API Key on Brankas Dashboard, you’ll also need to register your Business Information and Destination Account.

Registering business information

You will need to register your business information and destination account through Brankas Dashboard. Enrolling these bank accounts will allow them to be targeted by Direct as a valid beneficiary account in a fund transfer.

After login you can go to the setting section on Brankas Dashboard

Business information setup

You can find business and Direct sections on the settings. Business section is where you can fill out information about your business while Direct tab is where you can register your destination accounts.

If you have more than one destination account, you can definitely add as many as you want.

Registering destination accounts

For SMEs, Fintechs, merchants, and other corporate clients that intend to receive end user payment via one or several corporate accounts receivable bank accounts, you will need to enroll these bank accounts as part of the requirements for accessing and using the live environment of your Direct instance. Enrolling these bank accounts will allow them to be targeted by Direct as a valid beneficiary account in a fund transfer.

Registering these beneficiary accounts are part of Brankas’s pre-launch requirements prior to granting your Direct instance access to our live bank integrations. This is a critical piece of security due diligence that must be performed in order to ensure compliance with any Anti-Money Laundering and Anti-Fraud regulations.

To register your destination account, you can visit Brankas Dashboard > Settings > Direct tab, and add a new destination account.

Destination Account registration

Registering callback URLs

Brankas Direct processes transactions asynchronously. When a transaction operation is completed, Brankas Direct will POST to the Callback URL registered by the client, alerting them that a new transaction has been completed and logged in the transaction database. These transactions can be directly queried via the RetrieveTransfers endpoint using their Brankas assigned transaction_id.

In order for Brankas Direct to POST to your webhook URL, it must be registered on Brankas’s systems. You also need to have your callback listener to support idempotency. To enable this you need to watch for the Idempotency-Key in the request header. If it is the same as the previous one, then there is no need to reprocess the callback.

To register or update your callback URL, you can do it via Brankas Dashboard > Settings > Callback URL tab.

Setting up callback URL in Brankas Dashboard

List of statuses Brankas Direct sends for transaction callback

Code Status Description
2 SUCCESS Transfer is completed and fund is successfully settled
3 ERROR Transfer hits an error state, either Bank/Brankas/User error
11 EXPIRED Transfer has expired. By default 24 hours after checkout is created and end user did not finish the payment
12 FLAGGED Transaction is neither SUCCESS or FAILED as returned by the bank. A merchant needs to check in the statement of account if the funds were indeed received or not
13 CANCELLED End user selected one of the ‘Cancel’ buttons in Tap/payment pages
14 DENIED End a user-selected the ‘Deny’ button in Tap consent page
15 FAILED Transaction is marked as FAILED by merchants via v1/checkout/settle after checking on beneficiary account statement

Making API requests

Now that we’ve gone over the Direct flow and registering your business and destination account, we can explore what happens when you make an API call. As an example, we’ll look at the Quickstart’s call to v1/checkout, which creates a fund transfer initiation request that end user can complete via the Brankas Tap.

curl -X POST \
    https://docs.brank.as/v1/checkout \
    -H 'Content-Type: application/json' \
    -H 'x-api-key:O66Q9XWlyoV0A5xhTeF2uRpVXFPXqmutUESQEB6C5ziQJp3lVSHR5eiDkAE8823R' \
    -d '{
        "customer": {
            "fname": "Vanessa",
            "lname": "Sarah",
            "mname": "Griselda",
            "customer_id": "4f30b317-f98b-4454-bc05-7c4a2e48ec0d",
            "email": "vanessa.griselda@brank.as",
            "mobile": "+62-283-5559-907",
        },
        "from": {
            "type": "BANK",
            "bank_code": "DUMMY_BANK_PERSONAL",
            "country": "ID"
        },
        "destination_account_id": "b3f1a14c-c0dd-11ea-8f93-ca56f9871a24",
        "amount": {
            "cur": "IDR",
            "num": "10800"
        },
        "reference_id": "9005376336",
        "memo": "A note attached to the transaction by the client"
        "payment_channel": "_",
        "client": {
            "display_name": "Your Application Name",
            "logo_url": "https://example.com/logo.svg",
            "return_url": "https://example.com/success",
            "fail_url": "https://example.com/error",
        }
    }'

Example response data:

{
  "transaction_id": "a6d0516b-94e1-4403-bef1-e172baa901f8",
  "redirect_uri": "https://tap.brank.as?fail_url=https%3A%252F%252Fmerchant.ph%252Ffailed&logo_url=https%3A%252F%252Fbrank.as%252F_%252Ff3d317.svg&merchant=Your+application+name&return_url=https%3A%252F%252Fmerchant.ph&transaction_id=a6d0516b-94e1-4403-bef1-e172baa901f8",
  "short_redirect_uri": "https://direct.bnk.to/tap/Hrcjl1mD/Vanessa"
}

Remember Me Feature on Brankas Tap

The Brankas Tap, provides end users with a secure environment where they can safely submit their online banking access credentials to login to their bank and authorize a transaction.

The Brankas Tap also provides end users with a Remember Me feature that allows end users to be automatically logged on subsequent transactions facilitated by Brankas, delivering a more seamless experience.

End user online banking credentials are never saved or stored on Brankas or 3rd Party systems and are never exposed to 3rd Parties.

All credentials are secured using industry leading encryption standards. The feature is purpose built such that the end user is ultimately the custodian of their online banking access credentials.

To activate Remember Me feature, simply add this parameter “deep_link”: true in the body of your request.

Remember Me feature in Brankas Tap

Next Steps

Congratulations, you have completed the Brankas Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Brankas API. There are a few directions you can go in now:

You can also explore building with a particular product: Statement, Disburse, Pay, and Account Opening.

Setting up for Disburse

Brankas Disburse helps the process of bulk transfer or fund transfer to multiple destination accounts. By leveraging Brankas Disburse, enterprises are able to execute fund transfer based transactions over a growing basket of banks via a single set of APIs.

Getting Started with Disburse

One more step before you can start making a request with Brankas Disburse. After getting your API Key on Brankas Dashboard, you’ll also need to register your Business Information and Source Account.

Client Identifier and Secret

You will need to ask your bank about your client identifier and secret to put it on the API request.

Here’s some list needed from the bank

Country Bank Requirement
Indonesia BCA Client secret, Client identifier, API secret, & API identifier
Indonesia Permata Client secret, Client identifier, API secret, & API identifier
Indonesia BNI Client secret & Client identifier
Phillipines UBP Client secret, Client identifier, & Partner account

Here’s some example of the requirement

Country Bank Requirement Example
Indonesia BCA API Identifier a8a866fb-ffd6-4a9a-ae82-7f7fa8003d0e
Indonesia BCA API Secret de1faa09-673b-4efd-9627-466c8297bb07
Indonesia BCA Client Secret 3d6929ad-5eec-416e-a916-74d7d3e63de1
Indonesia BCA Client Identifier b24475e9-0e37-4eed-adec-63b5e1d52238

Doesn’t have developer to start testing API integration? You can definitely can start testing using our Brankas Dashboard.

Disburse Dashboard

In the dashboard, you can access the disburse product on the left bar. In the dashboard all of your transaction and their status appear here.

Registering your business information

Before start disbursing you want to update your business information, source account, and beneficiary account on the setting section

Adding source account and beneficiaries

After adding source account and beneficiary account, you can start trying our disbursement product. On the sandbox mode, you can register using DUMMY_BANK. Find out more on the Sandbox institution list.

Making API requests

Now that we’ve gone over the Disburse flow and registering your business and source and beneficiary account, we can explore what happens when you make an API call. As an example, we’ll look at the Quickstart’s call to v1/disbursements, which creates a fund transfer initiation request that

curl -X POST 'https://disburse.bnk.to/v1/disbursements' \
-H 'x-api-key: UQjF3yLpYqc0FxTQ2oAtSvDk2xjHA7Fk5PqU09n36gMWKAkcDrzlgICL6DxfEHWe' \
-d '{
  "credentials": {
  	"BCA_API":{
  		"identifier":"a8a866fb-ffd6-4a9a-ae82-7f7fa8003d0e",
  		"secret":"de1faa09-673b-4efd-9627-466c8297bb07"
  	},
  	"BCA_CLIENT":{
  		"identifier":"3d6929ad-5eec-416e-a916-74d7d3e63de1",
  		"secret":"b24475e9-0e37-4eed-adec-63b5e1d52238"
  	},
  },
  "disbursements": [
    {
    	"corporate_id": "IBSBRANKAS",
        "reference_id": "documentation-bca-00001",
        "type": "ON_DEMAND",
        "source_account": {
            "bank": "BCA_CORPORATE",
            "number": "7145061717",
            "holder_name": "Brankas Teknologi Indonesia"
        },
        "source_amount": {
        	"cur": "IDR"
        },
		"destination_account": {
            "bank": "ID_BCA",
            "number": "5255144445",
            "holder_name": "Eri Marina Yo"
        },
        "destination_amount": {
            "num": "1000000",
            "cur": "IDR"
        }
    }
  ]
}'

Response example:

{
    "result": [
        {
            "disbursement": {
                "corporate_id": "IBSBRANKAS",
                "reference_id": "documentation-bca-00001",
                "type": "ON_DEMAND",
                "source_account": {
                    "bank": "BCA_CORPORATE",
                    "number": "7145061717",
                    "holder_name": "Brankas Teknologi Indonesia"
                },
                "destination_account": {
                    "bank": "ID_BCA",
                    "number": "5255144445",
                    "holder_name": "Eri Marina Yo",
                    "address": {}
                },
                "source_amount": {
                    "cur": "IDR"
                },
                "destination_amount": {
                    "cur": "IDR",
                    "num": "1000000"
                },
                "fees": {},
                "disbursement_id": "75b37286-435d-4983-bb33-c2a8160968af",
                "external": {
                    "reference_id": "20210422133625011001"
                },
                "status": "SUCCESS",
                "created": "2021-04-22T06:28:12.262Z",
                "updated": "2021-04-22T06:28:12.262Z",
                "processed": "2021-04-22T06:28:12.261Z",
                "batch_id": "167d19a9-3d4d-44ca-8509-743be2941306"
            },
            "result": {}
        }
    ]
}

Next Steps

Congratulations, you have completed the Brankas Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Brankas API.

You can also explore building with a particular product: Statement, Direct, Pay, and Account Opening.

Setting up for Statement

Brankas Statement endpoints enable fintechs and financial service providers to leverage customer transaction information and deliver highly personalized financial services and applications.

You can use Brankas Statement for credit scoring, financial management applications, personalized cross-sell opportunities, and customer verification.

Getting started with Statement

After getting your API Key, you can start making an API request to Statement sandbox endpoints.

Making API requests

Now that we’ve gone over the Statement flow, we can explore what happens when you make an API call. As an example, we’ll look at the Quickstart’s call to v1/statement-retrieval, which creates a statement retrieval request.

curl -X POST 'https://disburse.bnk.to/v1/disbursements' \
-H 'x-api-key: UQjF3yLpYqc0FxTQ2oAtSvDk2xjHA7Fk5PqU09n36gMWKAkcDrzlgICL6DxfEHWe' \
-d {
    "bank_code": " DUMMY_BANK_PERSONAL",
    "credential": {
       "identifier": "user+1@domain.com",
       "secret": "user+1"
    },
  }

Response Example:

{
  "statement_id": "123_statement_id",
  "status": "PENDING",
  "site_response": "Your request is currently being processed"
}

Next Steps

Congratulations, you have completed the Brankas Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Brankas API.

You can also explore building with a particular product: Disburse, Direct, Pay, and Account Opening.