Brankas Brankas

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.bnk.to

  • Base Path v1

Send a balance retrieval initiation request

Initiates a balance retrieval request

curl -X POST \
	https://balance.bnk.to/v1/balance-init \
	-H 'Authorization: Bearer USE_YOUR_TOKEN' \
	-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.bnk.to/v1/balance-init

Body Parameters

NameTypeDescription
countrystringCountry is the country code (ID, PH, TH)
bank_codes[]BankCodeBankCodes used to specify the list of bank to be shown to user
external_idstringExternalID represent an id that is passed by the api consumer to track the request
app_redirect_uristringAppRedirectURI is the URL that end users need to be redirected after the successful balance retrieval operation
organization_display_namestringOrganizationDisplayName is a name of the organization that send the request and will be displayed when processing the balance request
app_redirect_error_uristringAppRedirectErrorURI is the URL that end users need to be redirected for the failure on balance retrieval operation
app_redirect_durationstringAppRedirectDuration is the time (in seconds) the user should be redirected upon balance retrieval operation finish.
remember_meboolRememberMe 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_idstringLinkID is the identifier that maps to the bank and generated after a credential is stored in browser
auto_consentboolAutoConsent 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.

ValueDescription
UNKNOWN_BANK
MANDIRI_PERSONALBank code to retrieve retail bank account transaction data for Bank Mandiri
BCA_PERSONALBank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
BNI_PERSONALBank code to retrieve retail bank account transaction data for Bank Negara Indonesia (BNI)
BRI_PERSONALBank code to retrieve retail bank account transaction data for Bank Rakyat Indonesia (BRI)
BCA_CORPORATEBank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
DUMMY_BANK_PERSONALBank code to instruct the statement retrieval service to target the sandboxed Brankas dummy bank for test calls
BDO_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Banco De Oro Unibank (BDO)
BPI_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Bank of the Philippines Islands (BPI)
KASIKORNBANK_PERSONALBank code to retrieve retail bank account transaction data for Kasikornbank.
PNB_PERSONALBank code to retrieve retail bank account transaction data for Philippine National Bank
UNIONBANK_PERSONALBank code to retrieve retail bank account transaction data for Union Bank
UNIONBANK_CORPORATEBank code to retrieve retail bank account transaction data for Union Bank
METROBANK_PERSONALBank code to retrieve retail bank account transaction data for Metropolitan Bank
RCBC_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Rizal Commercial Banking Corporation

Responses

Response body

NameTypeDescription
balance_idstringBalanceID is the unique ID assigned to the balance initiation request
redirect_uristringRedirectURI 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

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

Send a balance retrieval request

Initiates a balance retrieval request.

curl -X POST \
	https://balance.bnk.to/v1/balance \
	-H 'Authorization: Bearer USE_YOUR_TOKEN' \
	-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.bnk.to/v1/balance

Body Parameters

NameTypeDescription
bank_codeBankCodeBankCode is the internal code (enum) used by the service to target a specific bank for the balance retrieval request (BCA, etc).
credentialCredentialCredential is the user internet banking account credentials or BalanceService token id.
period_daysint32PeriodDays 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_datestringStartDate is the start date of the balance request Date/Time ranges should follow the YYYY-MM-DD convention
end_datestringEndDate is the end date of the balance request Date/Time ranges should follow the YYYY-MM-DD convention
account_numberstringAccountNumber is the bank account number
api_credentialAPICredentialAPICredential are the credentials to access the bank API
external_idstringExternalID 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.
channelstringChannel is an optional param. The parameter value identifies the Channel via API call is initiated. Possible Values: WEB,MOBILE
client_key_idstringClientKeyId 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]stringAdditionalFields 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
NameTypeDescription
credential_typeCredentialTypeCredentialType is the type of the credential the identifier matches, e.g email
identifierstringIdentifier is the unique identifier for the credential (ie, a phone number, email, token, etc).
secretstringSecret is the secret to exchange for validating the credential. If type is TOKEN, this can be empty
APICredential
NameTypeDescription
corporate_idstringCorporateID is the banks unique id for the organization. if the bank provides a partner_id, then it should be used instead.
identifierstringIdentifier is the unique identifier for the credential
secretstringSecret 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.

ValueDescription
UNKNOWN_BANK
MANDIRI_PERSONALBank code to retrieve retail bank account transaction data for Bank Mandiri
BCA_PERSONALBank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
BNI_PERSONALBank code to retrieve retail bank account transaction data for Bank Negara Indonesia (BNI)
BRI_PERSONALBank code to retrieve retail bank account transaction data for Bank Rakyat Indonesia (BRI)
BCA_CORPORATEBank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
DUMMY_BANK_PERSONALBank code to instruct the statement retrieval service to target the sandboxed Brankas dummy bank for test calls
BDO_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Banco De Oro Unibank (BDO)
BPI_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Bank of the Philippines Islands (BPI)
KASIKORNBANK_PERSONALBank code to retrieve retail bank account transaction data for Kasikornbank.
PNB_PERSONALBank code to retrieve retail bank account transaction data for Philippine National Bank
UNIONBANK_PERSONALBank code to retrieve retail bank account transaction data for Union Bank
UNIONBANK_CORPORATEBank code to retrieve retail bank account transaction data for Union Bank
METROBANK_PERSONALBank code to retrieve retail bank account transaction data for Metropolitan Bank
RCBC_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Rizal Commercial Banking Corporation
CredentialType

CredentialType is the credential type.

ValueDescription
EMAIL
Type_MSISDN
TOKEN
CLIENT_CREDENTIAL

Responses

Response body

NameTypeDescription
request_idstringRequestID 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
statusStatusStatus is the current balance retrieval status
site_responsestringSiteResponse is any relevant text returned by the target bank’s online banking portal as part of the balance retrieval request
challengeChallengeChallenge is an optional challange information from the bank website to be used for next 2FA request.
Objects
Challenge
NameTypeDescription
typeChallengeType
databytes
Enums
Status
ValueDescription
UNKNOWN_StatusUnknown balance retrieval status
INITIATEDThe balance request is initiated
CONSENT_GRANTEDThe balance request is currently grated with consent by end user
AUTH_IN_PROGRESSThe balance request authentication in progress
AWAITING_TFAAwaiting TFA authentication to gain access to the user’s online banking account
TFA_IN_PROGRESSThe balance request authentication in progress
RETRIEVAL_IN_PROGRESSThe balance retrieval in progress
AUTH_FAILEDThe balance request authentication failed while attempting to log into the user’s online banking account as part of the balance retrieval process.
FAILEDThe requested balance couldn’t be retrieved successfully.
SUCCESSThe requested balance was successfully retrieved
CANCELLEDThe balance request was cancelled
INACTIVATEDThe balance request inactivated upon waiting for user input
PURGEDThe balance data such as accounts and transactions are purged from brankas system
ChallengeType

ChallengeType for captcha or OTP challenge

ValueDescription
TEXTTEXT are challenges that are generally represented as strings.
IMAGEIMAGE are image-based challenges, for example a captcha image.
IN_APPIN_APP are challenges that happens offline and asynchronously outside our control for example, approvals from a user’s mobile device.
SMSSMS are SMS-based challenge codes.
MGENCODEMGENCODE or Mobile Generated Code, are usually challenge codes generated by bank applications.
HYBRIDHYBRID are bank-specific challenge types, for example, BCA requires a mix of the different types.
PINPIN 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

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

Send a Balance list request

Retrive the Balance list request.

curl -X GET \
	https://balance.bnk.to/v1/get_balance \
	-H 'Authorization: Bearer USE_YOUR_TOKEN'

HTTP Request

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

Responses

Response body

NameTypeDescription
balances[]BalanceResponseBalances are the balance that match the filters of a request.
next_page_tokenstringNextPageToken represents the pagination token to retrieve the next page of results. If the value is “”, it means no further results for the request.
messagestringMessage is any message from the server that are not treated as an error.
total_countint32TotalCount of the statements matched by the query filters
previous_page_tokenstringPreviousPageToken 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
NameTypeDescription
statusStatusStatus is the status of the request.
request_idstringRequestID is the ID of the request.
created_atTimestampCreated is the request created time.
bank_codeBankCodeBankCode is the BankCode related of the request.
accounts[]BalanceListDataAccounts holds account information.
errorstringError is the error information for failed request.
updateTimestampUpdate is the updation timestamp.
site_responsestringSiteResponse is an optional text response from the bank website.
Timestamp
NameTypeDescription
secondsint64
nanosint32
BalanceListData
NameTypeDescription
accountBalanceListDataAccountAccount holds account information.
balanceBalanceListDataBalanceBalance holds balance information.
BalanceListDataAccount
NameTypeDescription
typeAccountTypeType is type of the account
account_numberstringAccountNumber is the account number.
holder_namestringHolderName is the name who own the card.
BalanceListDataBalance
NameTypeDescription
currentAmountCurent is current balance.
periodic_balance[]PeriodicBalancePeriodicBalance holds information about balance per month.
peridic_balance_rangePeriodicBalanceRangePeriodicBalanceRange denotes the balance retrieval period
Amount
NameTypeDescription
curCurrencyISO4217Cur is the currency of the amount using its ISO 4217 code.
numstringNum 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”.
PeriodicBalance
NameTypeDescription
monthstringMonth is the month of the balance.
yearstringYear is the year of the balance.
start_balanceAmountStartBalance is the staring amount at the begining of the month.
end_balanceAmountEndBalance is the End balance at the end of the month.
average_monthly_balanceAmountAverageMonthlyBalance is the monthly average balance for the given month
PeriodicBalanceRange
NameTypeDescription
total_monthsint32TotalMonths is the number of months the balance data is available
rangestringRange is the period of balance data, Ex: Jan 2021 to Mar 2021
Enums
Status
ValueDescription
UNKNOWN_StatusUnknown balance retrieval status
INITIATEDThe balance request is initiated
CONSENT_GRANTEDThe balance request is currently grated with consent by end user
AUTH_IN_PROGRESSThe balance request authentication in progress
AWAITING_TFAAwaiting TFA authentication to gain access to the user’s online banking account
TFA_IN_PROGRESSThe balance request authentication in progress
RETRIEVAL_IN_PROGRESSThe balance retrieval in progress
AUTH_FAILEDThe balance request authentication failed while attempting to log into the user’s online banking account as part of the balance retrieval process.
FAILEDThe requested balance couldn’t be retrieved successfully.
SUCCESSThe requested balance was successfully retrieved
CANCELLEDThe balance request was cancelled
INACTIVATEDThe balance request inactivated upon waiting for user input
PURGEDThe 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.

ValueDescription
UNKNOWN_BANK
MANDIRI_PERSONALBank code to retrieve retail bank account transaction data for Bank Mandiri
BCA_PERSONALBank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
BNI_PERSONALBank code to retrieve retail bank account transaction data for Bank Negara Indonesia (BNI)
BRI_PERSONALBank code to retrieve retail bank account transaction data for Bank Rakyat Indonesia (BRI)
BCA_CORPORATEBank code to retrieve retail bank account transaction data for Bank Central Asia (BCA)
DUMMY_BANK_PERSONALBank code to instruct the statement retrieval service to target the sandboxed Brankas dummy bank for test calls
BDO_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Banco De Oro Unibank (BDO)
BPI_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Bank of the Philippines Islands (BPI)
KASIKORNBANK_PERSONALBank code to retrieve retail bank account transaction data for Kasikornbank.
PNB_PERSONALBank code to retrieve retail bank account transaction data for Philippine National Bank
UNIONBANK_PERSONALBank code to retrieve retail bank account transaction data for Union Bank
UNIONBANK_CORPORATEBank code to retrieve retail bank account transaction data for Union Bank
METROBANK_PERSONALBank code to retrieve retail bank account transaction data for Metropolitan Bank
RCBC_PERSONALBank code to retrieve retail bank account statements / transaction histories from the Rizal Commercial Banking Corporation
AccountType

AccountType is the account type enum.

ValueDescription
UNKNOWN_AccountTypeIndicates that the bank account type is either undefined or neither a Checking on Saving account
CHECKINGIndicates that the bank account is a Checking Account
SAVINGSIndicates 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

ValueDescription
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"
            },
            "periodic_balance": [
              {
                "month": "string",
                "year": "string",
                "start_balance": {
                  "cur": "CurrencyISO4217",
                  "num": "string"
                },
                "end_balance": {
                  "cur": "CurrencyISO4217",
                  "num": "string"
                },
                "average_monthly_balance": {
                  "cur": "CurrencyISO4217",
                  "num": "string"
                }
              }
            ],
            "peridic_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

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