Brankas menu
×

Introduction

Welcome to Brankas API Documentation! This document will walk you through how to deploy API calls to Brankas endpoints in a sandbox environment.

Reach out to us at solutions@brank.as for any feedback and suggestions. We are keen to improve our documents for you. You may reach out to our Sales team at sales@brank.as when you are ready to transition to the live environment.

Our Privacy Policy and Terms of Use is available for you to review. This will allow you to understand how we interact with you data.

Glossary

Here are the list of terms and definitions that are covered in this document. Reach out to our Sales team at sales@brank.as when you are ready to transition to the live environment.

TermsDefinition
API OperationA communication touchpoint between an API and a server. API Operation is also known as API Endpoint.
API ServiceInterfaces that provide a program with a description of how to interact with a system in order to retrieve and/or change the data within it.
Application Programming Interface (API)A set of definitions and protocols for building and integrating application software.
ClientsRefers to banks and financial institutions.
Client IDUnique public identifier for apps.
Client SecretRandomly generated client API key known only to the application and the authorization server.
CustomersRefers to end-users.
DELAPI method to delete
EnvironmentDeployment environment
GETAPI method to retrieve
Identity Provider (IdP)The source for validating user identity in a federated identity system.
Internet Payment Gateway (IPG)A third-party between merchants and customers that securely take the money from customers and send it to the merchant’s bank account.
IntegrationsRefers to any bank integrations by any core product.
MerchantsAlso known as third-party providers.
OAuthSecure delegated access to server resources on behalf of a resource owner.
One Time Password (OTP)A common form of Two-factor Authentication: A password that is valid for only one login session or transaction, on a computer system or other digital device.
Open BankingEnabling bank services through technology.
POSTAPI method to create
ProductionDeployment environment that serves end-users/clients
PUTAPI method to update
SandboxSoftware testing environment that isolates untested code changes and outright experimentation from the production environment or repository.
ScraperA program that extracts data from websites directly using HTTP, or through a web browser.
Software Development Kid (SDK)A downloadable software package that contains the tools you need to build on a platform.
StagingDeployment environment that mirrors the production environment
Third Party ProviderThird-party providers are companies that provide financial tech services. For example, Hoolah.
TokenAccess token unique to a session.
Two-Factor Authorization (2FA)A method of confirming users’ claimed identities by using a combination of two different factors: something your user knows and something they have.
WebhooksUser-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different applications or third-party APIs.
White LabelBrandless product.

Getting Started

How to Sign Up to Brankas Account

Download the API collection:

Quick and Easy API Testing

Click Run in Postman to import and run Brankas API Collection on one click with Postman.

Click here for Direct API Collection
Direct API Collection Run in Postman
Click here for Statement API Collection
Direct API Collection Run in Postman

To start testing in the sandbox environment, you will need:

  • Subdomain
  • Client ID
  • Client Service

To get all of those you will need to

  • Sign up on https://brank.as/create-account
  • Enter the 6 digit code sent to your email address.
  • Enter your company workspace. This will be
  • Welcome and log in to the admin Dashboard.
  • Launch each product for Client Service.
  • To retrieve Client ID, click on each product and scroll for Client ID

API Keys and Updates

This section details the first steps you need to take to successfully launch Brankas Direct, Statement, or Disburse including how to register, how to set up an OAuth2 client on your system, and acquiring access tokens.

API Protocol

An API token will be issued to access Brankas endpoints. Add the API token as the header parameter to every request. See example below: Authorization: Bearer XXXX-XXXX-XXXX

Revoking API Token

Due to security constraints and how OAuth has been set up, API tokens cannot be revoked. Tokens are set to expire after 1 hour (3600 seconds) from being issued.

Keeping API Token Save

Keeping API token safe API tokens are identifiers that authenticate to access your Brankas account. It is essential to safeguard your API tokens. Here are some of the DOs and Donts in keeping your API tokens safe.

Donts

Do not store API tokens as plaintext files in the Version Control System. Storing API tokens in the Version Control System 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.

Dos

Do store in the dedicated mechanism for storing data secrets if it is available. Do store it in the configuration file that is excluded from your version control. It can be created manually, or stored in the deployment server by automated tools. Ensure that the file can only be read by your web application. We highly recommend to limit access to only users that requires the information

In case of security breach

In case of incidents where a token has been accidentally pushed to a remote public repository, we suggest to rotate it. Deletion of access tokens from VCS will not be sufficient in case of security breach because VCS stores historical changes, is distributed and has automation assigned to new pushes. We highly recommend revoking old tokens that are no longer in use.

Encryption

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

Do validate certificates. However, if you receive a validation error from Brankas, do not proceed with the connection. Ensure that your applications are encrypted with HTTPS. To ensure that, connection should fail when the certificate validation fails.

Application design

Secure your application against common security flaws. Learn more about Top 10 web Application Security Risks.

If your application is large, do 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.

API Host

These are the host for Sandbox environment:

DirectDisburseStatement
direct.sandbox.<YOUR_SUBDOMAIN>.bnk.todisburse.sandbox..bnk.tostatement.sandbox..bnk.to

These are the host for Production environment:

DirectDisburseStatement
direct..bnk.todisburse..bnk.tostatement..bnk.to

Errors

Our client libraries are set to raise exceptions such as

  • failed charge
  • invalid paramaters
  • authentication errors and
  • network unavailability

We suggest writing codes that would handle all possible API exceptions. Error responds can be found on each product section.