Brankas Brankas

Home

Welcome to Brankas API Documentation! This document walks you through deploying API calls to Brankas endpoints in the sandbox environment. For feedback and suggestions, please send us an email at support@brank.as. We are keen to improve our documents for you. When you’re ready to transition to the live environment, please reach out to our Sales team at sales@brank.as or request a live key through Brankas Dashboard.

You can review our Privacy Policy and Terms of Use to better understand how Brankas interacts with you data.

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

EnvironmentExplanation
SandboxGet started with test credentials and life-like data
LiveReady to transact with real customer

Brankas Product

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

ProductExplanation
DirectProviding bank transfer as payment option in your business
DisburseDeliver funds to multiple bank account
StatementMonthly transactional data from bank account
PayBank transfer for SME
Account OpeningOpening a saving account online

If you get stuck at any point in the Quickstart, help is just a click away! Ask other developers in email at support@brank.as or submit a support ticket.

Quickstart Setup

Once you have your API keys, it’s time to run the Brankas Quickstart locally! The instructions below will guide you through the process of cloning the Quickstart repository. This API Key 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 or contact our team through support@brank.as

API Environment

Brankas provides both a sandbox and live environments for use.

ProductSandboxLive
Directdirect.sandbox.bnk.todirect.bnk.to
Disbursedisburse.sandbox.bnk.todisurse.bnk.to
Statementstatement.sandbox.bnk.tostatement.bnk.to
Payapi.pay.sandbox.bnk.toapi.pay.bnk.to
Account Openingaccount-opening.sandbox.bnk.toaccount-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. Your API Key is not environment-specific; you may use the same Key for both sandbox and live environments. Below is a sample header to include in your request body when calling Brankas endpoints.

-H 'Content-Type:application/json' \
-H 'x-api-key:O66Q9XWlyoV0A5xhTeF2uRpVXFPXqmutUESQEB6C5ziQJp3lVSHR5eiDkAE8823R' \

Postman Collection

The 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 the Brankas Postman Collection Quickstart on GitHub.

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 and Destination Account registration

You can find business and direct section on the setting. Business section is where you can fill out information about your business while direct is where you can register your destination account.

If you have more than one destination account, you can definitely add as many as you want. If there is a case where you enter the same bank then Brankas will prioritise the funds to be transferred to the first registered destination account bank.

Making API request

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 Identity Provider service (idP).

curl -X POST \
    https://docs.brank.as/v1/checkout \
    -H 'Content-Type: application/json' \
    -H 'x-api-key:O66Q9XWlyoV0A5xhTeF2uRpVXFPXqmutUESQEB6C5ziQJp3lVSHR5eiDkAE8823R' \
    -d '{
        "customer": {
            "fname": "Indriari",
            "lname": "Tyassanto",
            "mname": "Vega",
            "customer_id": "4f30b317-f98b-4454-bc05-7c4a2e48ec0d",
            "email": "ivo@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": "10000"
        },
        "reference_id": "9005376336",
        "memo": "A note attached to the transaction by the customer"
        "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": "f6355a01-e32b-426e-b2af-85366d305743",
  "redirect_uri": "https://pidp-server.your-subdomain.bnk.to?transaction_id=f6355a01-
e32b-426e-b2af-85366d305743&merchant=YOUR_APP&logo_url=https:%2F%2Fexample.com&return_url=https:%2F%2Fexample.com",
}

Next Step

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 help the process of bulk transfer or fund transfer to multiple destination account. 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

CountryBankRequirement
IndonesiaBCAClient secret, Client identifier, API secret, & API identifier
IndonesiaPermataClient secret, Client identifier, API secret, & API identifier
IndonesiaBNIClient secret & Client identifier
PhillipinesUBPClient secret, Client identifier, & Partner account

Here’s some example of the requirement

CountryBankRequirementExample
IndonesiaBCAAPI Identifiera8a866fb-ffd6-4a9a-ae82-7f7fa8003d0e
IndonesiaBCAAPI Secretde1faa09-673b-4efd-9627-466c8297bb07
IndonesiaBCAClient Secret3d6929ad-5eec-416e-a916-74d7d3e63de1
IndonesiaBCAClient Identifierb24475e9-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 request

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 Step

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 request

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 Step

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.

API

Comprehensive reference for integrating with Brankas API endpoints

Endpoint and Schema Overview

Here’s the full list of Brankas endpoints and guideline

ProductsEndpoints
Direct/v1/checkout, /v1/transfer
Disburse/v1/disbursements, /v1/disbursements/process, /v1/disbursements/account-inquiry
Statement/v1/notification, /v1/statement-retrieval, /v1/statements, /v1/statement-init, /v1/static-link
Pay/v1/merchant, /v1/invoice, /v1/deposit-account
Account Opening/v1/product-list, /v1/form-request, /v1/status

API Access

To gain access to the Brankas API, create an account on the Brankas developer dashboard. Once you’ve completed the signup process and acknowledged our terms, you can access API Key via the Dashboard.

API Protocols and Header

The Brankas API use POST request to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Brankas API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS version below 1.2 are not supported, as they will transmit your API Key in plaintext over the network.

Always validate certificates. You should not proceed with a connection if you receive a certificate validation error from Brankas. Make sure all parts of your application are using encryption and HTTPS and failing when certificate validation fails.

To use it, you can put it in your API request header.

For example:

-H 'Content-Type:application/json' \
-H 'x-api-key:O66Q9XWlyoV0A5xhTeF2uRpVXFPXqmutUESQEB6C5ziQJp3lVSHR5eiDkAE8823R' \

Revoke API Tokens

Due to security constraints and how OAuth has been set up, API key cannot be revoked. API Key will be automatically revoked when you re-create a new API Key.

Store API Tokens

API tokens are identifiers that authenticate your access to your Brankas account. It is essential to safeguard your API tokens. Here are some reminders to keep your tokens safe:

  • Store API tokens in the dedicated mechanism for storing data secrets if it is available.
  • Store API tokens in the configuration file that is excluded from your version control. It can be created manually or stored in the deployment server using automated tools.
  • Ensure that that only your web application can read your file.
  • DO NOT store API tokens as plaintext files in the Version Control System (VCS). Storing API tokens in the VCS may result in sharing it publicly. Thus, allowing anyone with the token to access your accounts.
  • DO NOT store tokens in email inboxes or chat logs. Tokens should only live in Brankas and production systems. You can retrieve API tokens from your Profile Setting page.
  • DO NOT store the token in user-accessible code such as browser-side, JavaScript, or Android apps that can be decompiled.

In case of security breach

In case of incidents where an API Key has been accidentally pushed to a remote public repository, we suggest to rotate it. Deleting an access token from VCS is not sufficient because a VCS stores historical changes, is distributed and has automation assigned to new pushes.

API Host

The Sandbox environment is unrestricted and supports only test Items. All testing should be done in the Sandbox. All activity in the Production environment will be billed. When you’re getting ready to launch into Production, request Live API access via the dashboard.

ProductSandboxLive
Directdirect.sandbox.bnk.todirect.bnk.to
Disbursedisburse.sandbox.bnk.todisurse.bnk.to
Statementstatement.sandbox.bnk.tostatement.bnk.to
Payapi.pay.sandbox.bnk.toapi.pay.bnk.to
Account Openingaccount-opening.sandbox.bnk.toaccount-opening.bnk.to

API Versioning and Changelog

This page covers backwards-incompatible, versioned API changes. For a list of all API updates, including non-versioned ones, see the API changelog for each of the products you are using.

Whenever we make a backwards-incompatible change to a general availability, non-beta product, we release a new API version to avoid causing breakages for existing developers. You can then continue to use the old API version, or update your application to upgrade to the new Brankas API version. APIs for beta products are subject to breaking changes without versioning.

We consider the following changes to be backwards compatible:

  • Adding new API endpoints
  • Adding new options parameter to existing endpoints
  • Adding new data elements to existing response schemas
  • Adding new enum values, including error_type and error_codes
  • Changing the length or content of any API identifier

Version 2021-2-1

  • Direct updated version is v2.1.0
  • Disburse updated version is 2.2.0
  • Statement updated version is 2.2.0
  • Pay updated version is 1.2.0

Postman Collection

Learn more about the Brankas Postman Collection, which allows you to send API request without code

Introduction

Brankas offers a Postman Collection as 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.

Brankas Postman Collection

To get started, check out the Brankas Postman Collection Quickstart on GitHub.

Sandbox

Brankas sandbox is a free and fully-featured environment for application development and testing. All Brankas functionality of Brankas API is supported in the Sandbox environment. A variety of test accounts and institutions are available to test against, and you can create an unlimited number of test transaction. Sandbox API keys can be obtained in the Brankas Dashboard.

Using Sandbox

The sandbox can be access through each product sandbox endpoint.

ProductSandbox
Directdirect.sandbox.bnk.to
Disbursedisburse.sandbox.bnk.to
Statementstatement.sandbox.bnk.to
Payapi.pay.sandbox.bnk.to
Account Openingaccount-opening.sandbox.bnk.to

All products can be immediately tested in Sandbox with no extra configuration. After filling the business information and setting information in the dashboard, you can already start testing on Sandbox.

Sandbox Institutions

Some that are available in our Live environments are available in our Sandbox. There are several supported Sandbox-only institutions that are suitable to write integration tests against:

InstitutionDirectDisburseStatement
Dummy BankAvailableAvailableAvailable

Accounts

Your Brankas account is managed through the Brankas Dashboard.

This section provides information on topics related to managing your Brankas account, such as account security, user team management.

Registration

When you want to register, you can visit this link. The only informations required are:

After providing the required information from the form above, you can login and these are the available benefits for you:

  • To have sandbox access that enables you:

    • To create API key for sandbox or test mode
    • To test our API in sandbox or test mode
  • To invite your team to try our API together

  • To see any transaction created in sandbox in each product dashboard

  • To configure your sandbox environment for product use like:

    • Callback URL
    • Business name or company name in sandbox
    • Add destination account for testing Direct product
    • Add source and beneficiary account for testing Disburse product

Manage Team Member

To invite your team, you can invite them into your team member by following this step by step guide:

  • Open and login to Brankas Dashboard

  • Go to user menu, you also can access it by clicking this link

  • Click Invite New User

  • Input the required information

  • After you submit the data, the invited user will get an invitation email to manage the organization account according to the role that you choose. Roles available for the user are:

    • Admin
      Admin can do anything on top of the org account
    • Approver
      Approver can access features to approve transactions on product dashboard and view created and approved transaction
    • Accountant
      Accountant can access features to create transactions on product dashboard and view created and approved transaction
    • Developer
      Developer only able to access view created and approved transaction and also create API Key
    • Operation
      Operation only able to see the created transaction

Update User Account

As an organization admin you can update the user information from the user menu. The available data to update is:

  • Full name
  • Email Address
  • Job title
  • Phone Number, and
  • Role