Getting Started With Statement

Integrating with our Statement APIs is straightforward, but there are three distinct ways of initiating statement retrievals in our system. Choosing which is most suitable depends on your system capabilities and how you want to engage with end-users.

We’ve created this guide to help you get started. If you have any queries or issues, please get in touch.

Sandbox and Live Modes

There are two modes when using Statement - Sandbox and Live.

  • Sandbox: This mode allows you to simulate calling the APIs but does not connect to an actual 3rd party integration. Instead, it will utilise a dummy data set to return example responses. This is the default mode when you first sign up with Brankas.

  • Live: This mode will allow you to perform statement retrievals on actual 3rd part integrations. To access this mode, you will need to have gone through our Go-Live requirements.

We expect the Sandbox mode to be used in a test environment when first integrating Brankas APIs. Toggling to Live mode in a production environment will involve supplying a Live Mode API key and dropping the sandbox. portion of the host url.

Mode API Base URL
Sandbox https://statement.sandbox.bnk.to
Live https://statement.bnk.to

Our guide will assume the use of Sandbox mode in all examples.

Create New API Key

When using requesting API, you need to create API key, to create it, please follow this step by step guide:

  1. Login to the Brankas Control Centre - https://dashboard.brank.as/
  2. On the sidebar, select the “API Keys” menu option
    • Note: If you are looking to generate a Live Mode API key, select Live Mode from the nav bar dropdown. You will need to have completed our go-live requirements before this option is activated. Please contact our Sales team for further information.
  3. Input your user account password and click “Create API Key”

With Brankas Tap

Use our Tap UX flow to guide end-users through the statement retrieval journey. We are constantly tweaking and reviewing Tap to improve customer conversion and reduce error rates.

Tap can be customised to match your branding

The following steps describe the order of execution of our APIs using cURL commands. You should change this to whatever implementation language you are using.

Step 1: Create a Statement Retrieval session

From your system, you simply need to call the /v1/statement-init endpoint with some inital parameters. Remember to set the x-api-key header with your generated API key.

curl -X POST 'https://statement.sandbox.bnk.to/v1/statement-init' \
-H 'Content-Type: application/json' \
-H 'x-api-key: <API_KEY>' \
-d '{
  "country": "PH",
  "organization_display_name": "Brankas Statement",
  "app_redirect_uri": "http://brank.as/statement"
}'

Setting Redirects

You can customise where the Tap UI redirects the end-user after a success/failed retrieval.

  • app_redirect_uri - Set this to redirect after a successful retrieval. It is also used as the failed redirect if app_redirect_error_uri is not set.
  • app_redirect_error_uri - Set this to redirect after a failed retrieval
  • app_redirect_duration - How long to wait before our Tap UI redirects to either the success or failed URI’s. Default is 60 seconds.

Enabling Corporate Accounts

Enable the option for end users to share statements from their corporate accounts. With this set, end users are able to select either from personal or corporate accounts.

{
...
  "corporate": true
}

Enabling Remember Me

If you want to allow end-users to save their credentials for later use, we have a remember me flag that can be set during initialisation.

When this flag is set, Tap will give the user the option to securely store their credentials on their device so they can be submitted automatically the next time the statement flow is triggered.

{
  ...
  "remember_me": true
}

Providing reference IDs

If there is a reference ID you would like to associate with a particular statement retrieval, you can pass this in with the external_id field. We will return this field with any data retrieval from our system.

{
  ...
  "external_id": "unique_client_ref_ID_1234",
}

Restricting bank selections

If you need to restrict the list of integrations listed on the bank selection screen, you can pass in a bank_codes array with the list of bank codes. You can find our complete list of supported bank codes here

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

Note: For Sandbox mode, you can only specific DUMMY_BANK_PERSONAL as a valid bank code.

Step 2: Redirect the end-user to the Tap URL

The response to the /v1/statement-init request will be a statement_id and a redirect_uri.

  • statement_id - A unique id to this particular statement 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.
{
    "statement_id": "c9a5cea3-3b66-44b7-a1d4-2f87672bef9a",
    "redirect_uri": "https://tap.staging.bnk.to?app=statement&statement_id=c9a5cea3-3b66-44b7-a1d4-2f87672bef9a&country=PH&organization_display_name=Brankas+Statement..."
}

Within your system and end-user UI, you should trigger a redirect to the redirect_uri to start the Tap flow.

Step 3: Listen to Status updates

As an end-user journeys through the statement retrieval steps, we will send real-time updates via any set callback webhooks. A full list of status codes are found here. The most notible codes are:

  • LOGIN - Login to the integration was successful
  • RECEIVED - We’re starting the retrieval
  • RECORDS_AVAILABLE - We’ve detected at least one available statement
  • COMPLETED - Retrieval is finished and the data is available on our system

Make sure you have a valid callback URL set in our admin portal settings page:

Step 4: Pull the statement data into your system

Once you have recieved the COMPLETED status on our callback, you can pull the data. Call the /v1/statements endpoint

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

This will return all statement data for your Organisation

Pull a single statement_id

If you want to focus on a single statement retrieval, you can pass it as a query param on the API endpoint

.../v1/statements?statement_ids=3924c485-ea2d-4b7f-b780-2744a02e0794

With only Core APIs

You can use our low level Statement APIs to build your own custom flow for creating and navigating statement retrievals. It is expected that you will be creating your own UI or other mechanism to allow end-users to securely submit consent, credentials and two-factor authentication tokens.

Third party integrations can be unpredictable, so ensure you are reacting to Status and Error codes dynamically

Step 1: Create a Statement Retrieval session

Call the /v1/statement-retrieval endpoint from your system. This will initialise a Statement retrieval session. Remember to set the x-api-key header with your generated API key.

curl -X POST 'https://statement.sandbox.bnk.to/v1/statement-retrieval' \
-H 'Content-Type: application/json' \
-H 'x-api-key: <API_KEY>' \
-d '{
  "bank_code": "BPI_PERSONAL",
  "credential": {
    "identifier": "userid",
    "secret": "password"
  },
}'

Some key things to note on this API call:

  • You need to include a bank_code. You can find our complete list of supported bank codes here
  • The credential object is required. It should contain the identifier and secret to access the end-users selected bank integration (ie. the specified bank_code)
    • There is another credential attribute, credential_type, which tells the Statement service how to handle the identifier/secret submitted. The majority of credentials use email or username with a password, so the default credential_type is EMAIL. For these types, the attribute can safely be ommitted.

Providing reference IDs

If there is a reference ID you would like to associate with a particular statement retrieval, you can pass this in with the external_id field. We will return this field with any data retrieval from our system.

{
  ...
  "external_id": "unique_client_ref_ID_1234",
}

Restricting Statement data to a certain time period

If you are looking to retrieve statement data between two time periods, you can specify a start and end date. In this scenario, we will return any statement data found between those two dates only, which could be 0 records.

{
  ...
  "start_date": "2021-07-15",
  "end_date": "2021-07-01",
}

Step 2: Listen for a TFA_AWAIT or LOGIN Status update

Once the initial request is submitted, we will respond with a statement_id and a status.

  • statement_id - A unique id to this particular statement retrieval session. This is useful to associate with a particular user on your system for later reconciliation.

For the status, depending on what is returned, your system should respond differently.

  • INITIATED - Nothing to do, you should wait for a COMPLETED webhook call. See ‘Step 5’ below.
  • PENDING - Nothing to do, we’re still connecting with the third-party integration. See ‘Step 3’ below.
  • LOGIN_ERROR - Most likely the end-user credentials are wrong. The response will include a site_response field, which can provide more information directly from the third-party integration.
  • TFA_AWAIT - The third-party integration is waiting for a two-factor authentication token to be submitted by the end-user. See ‘Step 4’ below.

Step 3: Listen for initialise updates

If the status is PENDING, it means we are still connecting to the integration. If you have registered a webhook (see ‘Step 5’ below), you can listen for a change of status that matches the statement_id and have your system process it.

Alternatively, poll the /v1/statements endpoint with the statement_id as a query parameter to get the latest status

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

Response will be along the lines of:

{
    "statement_id": "<the-statement-id>",
    "status": "TFA_AWAIT"
}

You can then respond to the status accordingly. Note: the response may include additonal data depending on the stage the retrieval is at.

Step 4: Submit TFA Tokens

For statuses that are TFA_AWAIT, we need the end-user to submit the two-factor authentication token. This is normally a 6-digit pin, but can vary between integrations (e.g some Indonesian banks require alpha-numeric captcha codes).

Call the /v1/tfa endpoint with the TFA code submitted by the end-user to your system.

curl -X POST 'https://statement.sandbox.bnk.to/v1/tfa' \
-H 'Content-Type: application/json' \
-H 'x-api-key: <API_KEY>' \
-d '{
  "purpose": "BankCredentialLogin",
  "purpose_id": "<the-statement-id>",
  "token": "<TFA-TOKEN>"
}'

If this was successful, the status of the statement request will change. You can refer to ‘Step 3’ above on how to listen for the updates.

Step 5: Listen to Status updates

As an end-user journeys through the statement retrieval steps, we can send real-time updates via any set callback webhooks. A full list of status codes are found here. The most notible codes are:

  • LOGIN - Login to the integration was successful
  • RECEIVED - We’re starting the retrieval
  • RECORDS_AVAILABLE - We’ve detected at least one available statement
  • COMPLETED - Retrieval is finished and the data is available on our system

Make sure you have a valid callback URL set in our admin portal settings page:

Step 6: Pull the statement data into your system

Once you have recieved the COMPLETED status on our callback, you can pull the data. Call the /v1/statements endpoint

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

This will return all statement data for your Organisation

Pull a single statement_id

If you want to focus on a single statement retrieval, you can pass it as a query param on the API endpoint

.../v1/statements?statement_ids=3924c485-ea2d-4b7f-b780-2744a02e0794

The Static Links feature is a simple way to engage with end-users and collect statement data. We have created this with a focus on interacting with our Admin portal UI.

You can create Static Links via our API, but it’s not the recommended approach

Step 1: Create a Brankas account and log into the Dashboard

Navigate to https://brank.as/sign-up and create an account.

After, you can log into our control centre dashboard here: https://dashboard.brank.as/ and navigate to the Statement UI: https://dashboard.brank.as/statement From there, you can select the STATIC LINKS tab.

On that tab, you can click the Create Static Link button

  • Organisation - This is the text displayed inside Tap during the end-user flow
  • Logo URL - Optionally set a logo to be displayed in the Tap flow
  • Redurect URL - Optionally set a URL to redirect the end-user when the Tap flow completes (for both success/failed states)
  • Supported Banks - Select the country you want to use the Static Link in and it will show a selection of integrations available. You can choose which ones will be displayed to the end-user during the Tap flow.
  • Link Expiration (optional)
    • Duration - You can set a time limit for how long the static link is active.
    • No. of Transactions - You can limit the number of times the static link can be used.

Once you have entered the details, you can click Create Link and a unique URL will be generated.

You can see a list of all generated Static Links for you organisation on the summary page. You can copy the URL’s by clicking on the ‘copy’ icon beside each URL.

With the url, you can share it via any platform e.g SMS, chat messengers, Facebook, email. End-users will click on it and launch into the Tap flow.

When end-users open the Tap flow, the first screen will be a landing page where they can add a reference ID. This ID would be supplied by your organisation so you can associate the Static Link with that particular end-user, or promotional campaign.