Balance Retrieval API v1.0.0

Brankas Retrieval endpoints enable fintechs and financial service providers to leverage customer transaction montly & running balance information and deliver highly personalized financial services and applications.

  • Host https://balance.sandbox.bnk.to

API Reference Overview

Send a balance retrieval initiation request

Initiates a balance retrieval request

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"
	}'

HTTP Request

POST https://balance.sandbox.bnk.to/v1/balance-init

Body Parameters

Name Type Description
country string Country is the country code (ID, PH, TH)
bank_codes []BankCode BankCodes used to specify the list of bank to be shown to user
external_id string ExternalID represent an id that is passed by the api consumer to track the request
app_redirect_uri string AppRedirectURI is the URL that end users need to be redirected after the successful balance retrieval operation
organization_display_name string OrganizationDisplayName is a name of the organization that send the request and will be displayed when processing the balance request
app_redirect_error_uri string AppRedirectErrorURI is the URL that end users need to be redirected for the failure on balance retrieval operation
app_redirect_duration string AppRedirectDuration is the time (in seconds) the user should be redirected upon balance retrieval operation finish.
remember_me bool RememberMe shows the remember_me option when performing the balance-retrieval flow if it is set to true, otherwise won’t show remember me option
link_id string LinkID is the identifier that maps to the bank and generated after a credential is stored in browser
auto_consent bool AutoConsent is a flag that skip the consent on PIDP flow and it is disabled by default
Enums
BankCode

BankCode is the internal code (enum) used by the service to target a specific bank for the statement retrieval request.

Value Description
UNKNOWN_BANK
MANDIRI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Mandiri
BCA_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
BNI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Negara Indonesia (BNI)
BRI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Rakyat Indonesia (BRI)
BCA_CORPORATE Bank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
DUMMY_BANK_PERSONAL Bank code to instruct the statement retrieval service to target the sandboxed Brankas dummy bank for test calls
BDO_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Banco De Oro Unibank (BDO)
BPI_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Bank of the Philippines Islands (BPI)
KASIKORNBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Kasikornbank.
PNB_PERSONAL Bank code to retrieve retail bank account transaction data for Philippine National Bank
UNIONBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Union Bank
UNIONBANK_CORPORATE Bank code to retrieve retail bank account transaction data for Union Bank
METROBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Metropolitan Bank
RCBC_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Rizal Commercial Banking Corporation

Responses

Response body

Name Type Description
balance_id string BalanceID is the unique ID assigned to the balance initiation request
redirect_uri string RedirectURI is the URL that end users need to be redirected to in order to continue the balance-retrieval operation

Example:

{
  "balance_id": "string",
  "redirect_uri": "string"
}

Response codes

Status Description
200 A successful response.
404 Returned when the resource is not found.

Send a balance retrieval request

Initiates a balance retrieval request.

curl -X POST \
	https://balance.sandbox.bnk.to/v1/balance \
	-H 'x-api-key: USE_YOUR_API_KEY' \
	-d '{
		"bank_code": "BankCode",
		"credential": {
			"credential_type": "CredentialType",
			"identifier": "string",
			"secret": "string"
		},
		"period_days": "int32",
		"start_date": "string",
		"end_date": "string",
		"account_number": "string",
		"api_credential": {
			"corporate_id": "string",
			"identifier": "string",
			"secret": "string"
		},
		"external_id": "string",
		"channel": "string",
		"client_key_id": "string",
		"": "map[string]string"
	}'

HTTP Request

POST https://balance.sandbox.bnk.to/v1/balance

Body Parameters

Name Type Description
bank_code BankCode BankCode is the internal code (enum) used by the service to target a specific bank for the balance retrieval request (BCA, etc).
credential Credential Credential is the user internet banking account credentials or BalanceService token id.
period_days int32 PeriodDays is the filter to search transactions that occurred over a given period. note: the behaviour of the search is depends upon each bank site.
start_date string StartDate is the start date of the balance request Date/Time ranges should follow the YYYY-MM-DD convention
end_date string EndDate is the end date of the balance request Date/Time ranges should follow the YYYY-MM-DD convention
account_number string AccountNumber is the bank account number
api_credential APICredential APICredential are the credentials to access the bank API
external_id string ExternalID is an optional param. It’s a unique value provided by a 3rd party platform, which enables Brankas to associate it with balance retrieval requests.
channel string Channel is an optional param. The parameter value identifies the Channel via API call is initiated. Possible Values: WEB,MOBILE
client_key_id string ClientKeyId is an identifier that specifies the respective key that need to be used in order to decrypt the credentials. The key must’ve been generated/uploaded already in order to know what the key identifier is. If the key is empty, that denotes the client credentials are in plain text if the key_id has a value, that denotes the client credentials are encrypted, and that will be decrypted before using the same.
map[string]string AdditionalFields are list of key value pair which is optional. This can be used to pass bank specific fields that differs from bank to bank
Objects
Credential
Name Type Description
credential_type CredentialType CredentialType is the type of the credential the identifier matches, e.g email
identifier string Identifier is the unique identifier for the credential (ie, a phone number, email, token, etc).
secret string Secret is the secret to exchange for validating the credential. If type is TOKEN, this can be empty
APICredential
Name Type Description
corporate_id string CorporateID is the banks unique id for the organization. if the bank provides a partner_id, then it should be used instead.
identifier string Identifier is the unique identifier for the credential
secret string Secret is the secret for the credential
Enums
BankCode

BankCode is the internal code (enum) used by the service to target a specific bank for the statement retrieval request.

Value Description
UNKNOWN_BANK
MANDIRI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Mandiri
BCA_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
BNI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Negara Indonesia (BNI)
BRI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Rakyat Indonesia (BRI)
BCA_CORPORATE Bank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
DUMMY_BANK_PERSONAL Bank code to instruct the statement retrieval service to target the sandboxed Brankas dummy bank for test calls
BDO_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Banco De Oro Unibank (BDO)
BPI_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Bank of the Philippines Islands (BPI)
KASIKORNBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Kasikornbank.
PNB_PERSONAL Bank code to retrieve retail bank account transaction data for Philippine National Bank
UNIONBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Union Bank
UNIONBANK_CORPORATE Bank code to retrieve retail bank account transaction data for Union Bank
METROBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Metropolitan Bank
RCBC_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Rizal Commercial Banking Corporation
CredentialType

CredentialType is the credential type.

Value Description
EMAIL
Type_MSISDN
TOKEN
CLIENT_CREDENTIAL

Responses

Response body

Name Type Description
request_id string RequestID is the unique system generated identifier assigned to this specific balance retrieval request. Once a balance has been retrieved and stored, it can then be queried later on from storage by using this as the identifier
status Status Status is the current balance retrieval status
site_response string SiteResponse is any relevant text returned by the target bank’s online banking portal as part of the balance retrieval request
challenge Challenge Challenge is an optional challange information from the bank website to be used for next 2FA request.
Objects
Challenge
Name Type Description
type ChallengeType
data bytes
Enums
Status
Value Description
UNKNOWN_Status Unknown balance retrieval status
INITIATED The balance request is initiated
CONSENT_GRANTED The balance request is currently grated with consent by end user
AUTH_IN_PROGRESS The balance request authentication in progress
AWAITING_TFA Awaiting TFA authentication to gain access to the user’s online banking account
TFA_IN_PROGRESS The balance request authentication in progress
RETRIEVAL_IN_PROGRESS The balance retrieval in progress
AUTH_FAILED The balance request authentication failed while attempting to log into the user’s online banking account as part of the balance retrieval process.
FAILED The requested balance couldn’t be retrieved successfully.
SUCCESS The requested balance was successfully retrieved
CANCELLED The balance request was cancelled
INACTIVATED The balance request inactivated upon waiting for user input
PURGED The balance data such as accounts and transactions are purged from brankas system
ChallengeType

ChallengeType for captcha or OTP challenge

Value Description
TEXT TEXT are challenges that are generally represented as strings.
IMAGE IMAGE are image-based challenges, for example a captcha image.
IN_APP IN_APP are challenges that happens offline and asynchronously outside our control for example, approvals from a user’s mobile device.
SMS SMS are SMS-based challenge codes.
MGENCODE MGENCODE or Mobile Generated Code, are usually challenge codes generated by bank applications.
HYBRID HYBRID are bank-specific challenge types, for example, BCA requires a mix of the different types.
PIN PIN are mostly static pin codes from banks, eg Metrobank’s passcode.

Example:

{
  "request_id": "string",
  "status": "Status",
  "site_response": "string",
  "challenge": {
    "type": "ChallengeType",
    "data": "bytes"
  }
}

Response codes

Status Description
200 A successful response.
404 Returned when the resource is not found.

Send a Balance list request

Retrive the Balance list request.

curl -X GET \
	https://balance.sandbox.bnk.to/v1/get_balance \
	-H 'x-api-key: USE_YOUR_API_KEY'

HTTP Request

GET https://balance.sandbox.bnk.to/v1/get_balance

Responses

Response body

Name Type Description
balances []BalanceResponse Balances are the balance that match the filters of a request.
next_page_token string NextPageToken represents the pagination token to retrieve the next page of results. If the value is “”, it means no further results for the request.
message string Message is any message from the server that are not treated as an error.
total_count int32 TotalCount of the statements matched by the query filters
previous_page_token string PreviousPageToken represents the pagination token to retrieve the previous page of results. If the value is “”, it means no further results for the request.
Objects
BalanceResponse
Name Type Description
status Status Status is the status of the request.
request_id string RequestID is the ID of the request.
created_at Timestamp Created is the request created time.
bank_code BankCode BankCode is the BankCode related of the request.
accounts []BalanceListData Accounts holds account information.
error string Error is the error information for failed request.
update Timestamp Update is the updation timestamp.
site_response string SiteResponse is an optional text response from the bank website.
Timestamp
Name Type Description
seconds int64
nanos int32
BalanceListData
Name Type Description
account BalanceListDataAccount Account holds account information.
balance BalanceListDataBalance Balance holds balance information.
BalanceListDataAccount
Name Type Description
type AccountType Type is type of the account
account_number string AccountNumber is the account number.
holder_name string HolderName is the name who own the card.
BalanceListDataBalance
Name Type Description
current Amount Curent is current balance.
periodic_balance []PeriodicBalance PeriodicBalance holds information about balance per month.
periodic_balance_range PeriodicBalanceRange PeriodicBalanceRange denotes the balance retrieval period
Amount
Name Type Description
cur CurrencyISO4217 Cur is the currency of the amount using its ISO 4217 code.
num string Num is the actual numeric value of the amount. Note: When there are separators in the currency, we store the decimals as digits in the string. So, PHP 100.00 would be represented as “amount.cur”: “PHP” and “amount.num”: “10000”.
decimal Decimal Decimal is the actual amount value with decimal points
PeriodicBalance
Name Type Description
month string Month is the month of the balance.
year string Year is the year of the balance.
start_balance Amount StartBalance is the staring amount at the begining of the month.
end_balance Amount EndBalance is the End balance at the end of the month.
average_monthly_balance Amount AverageMonthlyBalance is the monthly average balance for the given month
PeriodicBalanceRange
Name Type Description
total_months int32 TotalMonths is the number of months the balance data is available
range string Range is the period of balance data, Ex: Jan 2021 to Mar 2021
Decimal
Name Type Description
places int32 Places denotes the number of decimal points included with the amount
num string Num is the actual amount value with decimal points It is the decimal representation of the Num field as PHP 100.00 only for Indonesia, Philippine and Thailand
Enums
Status
Value Description
UNKNOWN_Status Unknown balance retrieval status
INITIATED The balance request is initiated
CONSENT_GRANTED The balance request is currently grated with consent by end user
AUTH_IN_PROGRESS The balance request authentication in progress
AWAITING_TFA Awaiting TFA authentication to gain access to the user’s online banking account
TFA_IN_PROGRESS The balance request authentication in progress
RETRIEVAL_IN_PROGRESS The balance retrieval in progress
AUTH_FAILED The balance request authentication failed while attempting to log into the user’s online banking account as part of the balance retrieval process.
FAILED The requested balance couldn’t be retrieved successfully.
SUCCESS The requested balance was successfully retrieved
CANCELLED The balance request was cancelled
INACTIVATED The balance request inactivated upon waiting for user input
PURGED The balance data such as accounts and transactions are purged from brankas system
BankCode

BankCode is the internal code (enum) used by the service to target a specific bank for the statement retrieval request.

Value Description
UNKNOWN_BANK
MANDIRI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Mandiri
BCA_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
BNI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Negara Indonesia (BNI)
BRI_PERSONAL Bank code to retrieve retail bank account transaction data for Bank Rakyat Indonesia (BRI)
BCA_CORPORATE Bank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
DUMMY_BANK_PERSONAL Bank code to instruct the statement retrieval service to target the sandboxed Brankas dummy bank for test calls
BDO_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Banco De Oro Unibank (BDO)
BPI_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Bank of the Philippines Islands (BPI)
KASIKORNBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Kasikornbank.
PNB_PERSONAL Bank code to retrieve retail bank account transaction data for Philippine National Bank
UNIONBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Union Bank
UNIONBANK_CORPORATE Bank code to retrieve retail bank account transaction data for Union Bank
METROBANK_PERSONAL Bank code to retrieve retail bank account transaction data for Metropolitan Bank
RCBC_PERSONAL Bank code to retrieve retail bank account statements / transaction histories from the Rizal Commercial Banking Corporation
AccountType

AccountType is the account type enum.

Value Description
UNKNOWN_AccountType Indicates that the bank account type is either undefined or neither a Checking on Saving account
CHECKING Indicates that the bank account is a Checking Account
SAVINGS Indicates that the bank account is a Savings Account
CurrencyISO4217

CurrencyISO4217 iso is the 3 digit currency that will be used as standard currency type on fast checkout. see: https://en.wikipedia.org/wiki/ISO_4217

Value Description
UNKNOWN_CURRENCY
AFN
EUR
ALL
DZD
USD
AOA
XCD
ARS
AMD
AWG
AUD
AZN
BSD
BHD
BDT
BYR
BZD
XOF
BMD
BTN
BOV
BAM
BWP
NOK
BRL
SGD
BGN
BIF
KHR
XAF
CAD
CVE
KYD
CLP
CNY
COP
KMF
CDF
NZD
CRC
HRK
CUC
CZK
DKK
DJF
DOP
EGP
ERN
ETB
FKP
FJD
XPF
GMD
GEL
GHS
GIP
GTQ
GBP
GNF
GYD
HNL
HKD
HUF
ISK
INR
IDR
IRR
IQD
IMP
ILS
JMD
JPY
JEP
JOD
KZT
KES
KPW
KRW
KWD
KGS
LAK
LBP
LSL
LRD
LYD
CHF
MKD
MGA
MWK
MYR
MVR
MRO
MUR
MXN
MDL
MNT
MAD
MZN
MMK
NAD
NPR
ANG
NIO
NGN
OMR
PKR
PGK
PYG
PEN
PHP
PLN
QAR
RON
RUB
RWF
WST
STD
SAR
RSD
SCR
SLL
SBD
SOS
ZAR
SSP
LKR
SHP
SDG
SRD
SZL
SEK
SYP
TWD
TJS
TZS
THB
TOP
TTD
TND
TRY
TMT
UGX
UAH
ARE
UYU
UZS
VUV
VEF
VND
YER
ZRN
ZMW

Example:

{
  "balances": [
    {
      "status": "Status",
      "request_id": "string",
      "created_at": {
        "seconds": "int64",
        "nanos": "int32"
      },
      "bank_code": "BankCode",
      "accounts": [
        {
          "account": {
            "type": "AccountType",
            "account_number": "string",
            "holder_name": "string"
          },
          "balance": {
            "current": {
              "cur": "CurrencyISO4217",
              "num": "string",
              "decimal": {
                "places": "int32",
                "num": "string"
              }
            },
            "periodic_balance": [
              {
                "month": "string",
                "year": "string",
                "start_balance": {
                  "cur": "CurrencyISO4217",
                  "num": "string",
                  "decimal": {
                    "places": "int32",
                    "num": "string"
                  }
                },
                "end_balance": {
                  "cur": "CurrencyISO4217",
                  "num": "string",
                  "decimal": {
                    "places": "int32",
                    "num": "string"
                  }
                },
                "average_monthly_balance": {
                  "cur": "CurrencyISO4217",
                  "num": "string",
                  "decimal": {
                    "places": "int32",
                    "num": "string"
                  }
                }
              }
            ],
            "periodic_balance_range": {
              "total_months": "int32",
              "range": "string"
            }
          }
        }
      ],
      "error": "string",
      "update": {
        "seconds": "int64",
        "nanos": "int32"
      },
      "site_response": "string"
    }
  ],
  "next_page_token": "string",
  "message": "string",
  "total_count": "int32",
  "previous_page_token": "string"
}

Response codes

Status Description
200 A successful response.
404 Returned when the resource is not found.