Brankas menu
×

API Reference Review

Welcome toBrankas 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 solutions@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. You can review our Privacy Policy and Terms of Use to better understand how Brankas interacts with you data.

Version Update

Direct

The current version is v2.0.3 release on September 29th 2020.

Disburse

The current version is v1.2.0 release on July 15th 2020.

Statement

The current version is v1.5.1 release on September 12nd 2020.

Get Started

Sign Up Account

Download the API Collection and Test API

  1. Download a collaboration platform to test API calls like Postman.
  2. Click the product you want to test to view the Brankas API collection.
  1. Click Run in Postman in the upper right corner to import and run the Brankas API Collection.

API Hosts

ProductSandboxProduction
Directdirect.sandbox.bnk.todirect.bnk.to
Statementstatement.sandbox.bnk.tostatement.bnk.to

API Protocol

API Tokens

An API key is available for you to use for triggering our API.

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

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.

Encryption

Brankas APIs require HTTPS with TLS >= 1.2. Non-encrypted HTTP connections are not accepted because it transmits your access token into plaintext.

Application Design

If your application is large, consider extracting Brankas-specific functionality into a separate middleware or service layer. This enables you to store API tokens separate from the main application.

If you need to pass the token around via HTTP requests, use HTTP headers or POST body - do not store the token in URI or query parameters. Web servers usually log the URL and browsers pass it between websites via the Referer header.

Brankas Identity Provider (IdP) for Direct and Statement

Brankas leverages a web application called the Brankas Identity Provider service (IdP) to secure this exchange of sensitive information.

After initiating a request with the Brankas product, the service returns a pre-formatted URL to the Brankas IdP that end-users can be redirected to. These URLs are unique and specific to the current request.

The Brankas IdP supports various the end-user authentication and authorization mechanisms used by their bank’s internet banking platform. These include:

  1. Internet banking login credentials
  2. TFA challenges of various types to authenticate the end user as part of login
  3. TFA challenges of various types to authorize a fund transfer

Brankas IdP ​automatically​ adjusts its flow to enforce the authentication and authorization requirements of any bank that it has been integrated with.

End-user Security

Brankas uses Redirect URIs to a unique Brankas IdP user session to ensure that there are no touch points for third party applications to gain access to sensitive internet banking credentials or TFA codes.

Additionally, we enforce secure HTTPS connections to the Brankas IdP and all internal micro-service communications are encrypted using mTLS >= 1.2. It also uses Cross-Site Request Forgery (CSRF) tokens and secure cookies to ensure the uniquene access to Brankas IdP sessions, preventing any potential session hijacking by malicious actors.

End-user credentials and TFA challenges are never stored. Access to internet banking credentials and accounts cannot abused.

Errors

Our client libraries are set to raise the following exceptions:

  • failed charge
  • invalid parameters
  • authentication errors
  • network unavailability

Authorization

All requests made to the Brankas’ API must be authorized using a API Key-based authentication.

API authorization involves sending x-api-key header value with a base 64-encoded UUID assigned to your organization

To access user data, please include your API key when you submit your request to the endpoint.

To maintain security, the data shared to the endpoints should be transferred via HTTPS.

After acquiring API Key from Brankas Dashboard, You need to pass the API Key in your request header in x-api-key in all subsequent resource requests. This involves sending a header value of x-api-key followed by the API Key, please note the colons after the word ‘‘x-api-key’. example: –header ‘x-api-key: Th!sis4n4P1K3y’

You can test these actions in an API client application, like cURL, Postman or Insomnia.