Brankas How to integrate Balance
Sign Up
×

Integrate with Brankas Tap

Below are the steps to execute Brankas APIs with cURL commands. You may update and customize other implementation languages.

Create a Balance Retrieval session and enable features

Call ‘/v1/balance-init’ endpoint with initial parameters. Replace ‘x-api-key’ header with the generated API key. Learn how to generate API keys here .

curl -X POST \
	https://balance.sandbox.bnk.to/v1/balance-init \
	-H 'x-api-key: USE_YOUR_API_KEY' \
	-d '{
		"country": "string",
		"bank_codes": "[]BankCode",
		"external_id": "string",
		"app_redirect_uri": "string",
		"organization_display_name": "string",
		"app_redirect_error_uri": "string",
		"app_redirect_duration": "string",
		"remember_me": "bool",
		"link_id": "string",
		"auto_consent": "bool"
	}'

Set redirects

Customize redirects at the end of Balance retrieval, either success or failed retrieval. Examples of redirects are to your website or more service offerings. Redirects can be set according to 3 triggers:

  1. app_redirect_uri - This triggers when retrieval status is Success. If app_redirect_error_uri is not set, failed retrievals redirect according to Success.
  2. app_redirect_error_uri - Redirect after a failed retrieval
  3. app_redirect_duration - Duration taken before Brankas Tap UI redirects to either the success or failed URI’s. Default duration is 60 seconds.

Selective bank feature

To enable only selected banks as option for payment on the bank selector page, enter bank codes in the ‘bank_code’. Refer to bank codes here.

{
  ...
  "bank_codes": [
    "BDO_PERSONAL",
    "BPI_PERSONAL",
    "PNB_PERSONAL"
  ]
}

> Add DUMMY_BANK_PERSONAL a bank code for sandbox environment

Redirect to Brankas Tap

The response to the /v1/balance-init request will be a balance_id and a redirect_uri.

balance_id A unique id to this particular balance retrieval session. This is useful to associate with a particular user on your system for later reconciliation.
redirect_uri A unique URL to launch a Tap session to guide the end-user. This is a short-lived url.
{
  "balance_id": "string",
  "redirect+uri": "string"
}

Trigger a redirect to the redirect_uri to start the Brankas Tap flow in your system and end-user UI.

Monitor Status updates

Real time status are sent via the callback webhook saved on the Brankas Dashboard. Refer to the list of status codes here. Common codes are:

Codes Description
Login End users has successfully log in
Received Retrieval of statement data has started
Records_available At least one statement data detected
Completed Retrieval complete and data is available in Brankas Dashboard

Pull the data to your system You can pull data shared to your system once the status reads Completed. Call /v1//balance endpoint

curl -X GET 'https://statement.sandbox.bnk.to/v1/balance \
-H 'Content-Type: application/json' \
-H 'x-api-key: <API_KEY>'

You can also call for a single statement by passing it as a query param on the API endpoint.

.../v1/balance?balance_ids=3924c485-ea2d-4b7f-b780-2744a02e0794