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 firstname.lastname@example.org for any feedback and suggestions. We are keen to improve our documents for you. You may reach out to our Sales team at email@example.com when you are ready to transition to the live environment.
Here are the list of terms and definitions that are covered in this document. Reach out to our Sales team at firstname.lastname@example.org when you are ready to transition to the live environment.
|API Operation||A communication touchpoint between an API and a server. API Operation is also known as API Endpoint.|
|API Service||Interfaces 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.|
|Clients||Refers to banks and financial institutions.|
|Client ID||Unique public identifier for apps.|
|Client Secret||Randomly generated client API key known only to the application and the authorization server.|
|Customers||Refers to end-users.|
|DEL||API method to delete|
|GET||API 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.|
|Integrations||Refers to any bank integrations by any core product.|
|Merchants||Also known as third-party providers.|
|OAuth||Secure 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 Banking||Enabling bank services through technology.|
|POST||API method to create|
|Production||Deployment environment that serves end-users/clients|
|PUT||API method to update|
|Sandbox||Software testing environment that isolates untested code changes and outright experimentation from the production environment or repository.|
|Scraper||A 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.|
|Staging||Deployment environment that mirrors the production environment|
|Third Party Provider||Third-party providers are companies that provide financial tech services. For example, Hoolah.|
|Token||Access 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.|
|Webhooks||User-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different applications or third-party APIs.|
|White Label||Brandless product.|
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.
To start testing in the sandbox environment, you will need:
- 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.
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.
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.
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.
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.
These are the host for Sandbox environment:
These are the host for Production environment:
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.