# BankConnect: Uploading using Python Package

FinBox provides an official python package for the BankConnect product. This package has functions to upload statement PDF Files and get enriched data.

# Requirements

The package currently supports Python 3.4+

# Installing Package

To use the package, install it using pip / pip3

pip3 install finbox_bankconnect

Now in your python code you can import the package as follows:

import finbox_bankconnect as fbc

# Authentication

You can set your unique API Key by setting the api_key value as follows:

fbc.api_key = "YOUR_API_KEY"

# `Entity` class

The python package will provide you with an Entity class, all actions like uploading or fetching information will be done using an instance of this Entity class.

Creating Entity Instance

Instance of Entity can be created only via static methods: get and create, not by constructor.

# Creating new Entity (`get` method)

To create a new entity, use the create method as follows:

entity = fbc.Entity.create()

Here entity is an instance of the Entity class.

In case you want to create an entity instance with a link_id, you can also provide an optional link_id string in create method as follows:

entity = fbc.Entity.create(link_id="YOUR_LINK_ID")

Lazy operations

This python package uses a lazy approach for actions, hence an actual Entity on the server will not get created until or unless some action is taken, for example uploading statement. This is also true for fetching as well until data is requested, no request over the network will be made even though you defined an entity instance.

# Fetching already created Entity (`create` method)

To fetch an entity using entity_id, use the get method as follows:

entity = fbc.Entity.get(entity_id="uuid4_for_entity")

# Entity Properties

Each entity instance has two read-only properties that can be accessed at any time:

# `entity_id`

This gives a unique identifier for an entity. The table below indicates the results of fetching entity_id in different cases:

Instance creation case	PDF uploaded	Result
`get`	Yes/No	`entity_id` used while calling `get` method
`create` with `link_id`	Yes	`entity_id` of newly created Entity after upload
`create` with `link_id`	No	`entity_id` of Entity created against the `link_id`
`create` without `link_id`	Yes	`entity_id` of newly created Entity after upload
`create` without `link_id`	No	throws `ValueError`

# `link_id`

This gives the link_id string value. The table below indicates the results of fetching link_id in different cases:

Instance creation case	PDF uploaded	Result
`get`	Yes/No	`link_id` after fetching from server, if no `link_id` exists give `None`
`create` with `link_id`	Yes/No	`link_id` provided in `create` method
`create` without `link_id`	Yes	`None`
`create` without `link_id`	No	throws `ValueError`

# Exceptions

In both the properties, whenever server is being contacted and in case it could not reach, it will throw ServiceTimeOutError (finbox_bankconnect.custom_exceptions.ServiceTimeOutError).
In case get method was used, link_id was being fetched and entity_id doesn't existed on our server then it will throw EntityNotFoundError (finbox_bankconnect.custom_exceptions.EntityNotFoundError).

# Using Properties

To use properties, you can simply treat them as read-only members of Entity instance as follows:

# printing link_id and entity_id, where entity is instance of Entity class
print(entity.link_id)
print(entity.entity_id)

# Uploading Statement

For any entity instance at any point, a PDF statement can be uploaded using the upload_statement method of entity instance. Its syntax is follows:

is_authentic = entity.upload_statement("path/to/file", bank_name="axis")

bank_name in the input should be a valid bank name identifier (See this for list of valid bank name identifiers).

The function returns a boolean value is_authentic that is True if no fraud were detected in the initial check (pre-transaction-level checks) otherwise False.

The function also sets entity_id property in the instance in case the instance was created via the create method.

In case PDF is password protected then you can specify the optional pdf_password field:

is_authentic = entity.upload_statement("path/to/file", pdf_password="PDF_PASSWORD", bank_name="axis")

In case you don't know the bank beta of the statement, you can skip the bank_name field :

is_authentic = entity.upload_statement("path/to/file")
# or with password
is_authentic = entity.upload_statement("path/to/file", pdf_password="PDF_PASSWORD")

# Exceptions

In case there is any problem with arguments passed, it throws ValueError and if a problem occurs in reading the file, it throws standard python file exceptions.
In case server could not be reached, it throws ServiceTimeOutError (finbox_bankconnect.custom_exceptions.ServiceTimeOutError).
In case invalid bank name identifier was specified in bank_name field, it throws InvalidBankNameError (finbox_bankconnect.custom_exceptions.InvalidBankNameError).
In case password provided was incorrect and the PDF was password protected, it throws PasswordIncorrectError (finbox_bankconnect.custom_exceptions.PasswordIncorrectError).
In case PDF was not parsable, i.e. was corrupted or had only images or very less text, it throws UnparsablePDFError (finbox_bankconnect.custom_exceptions.UnparsablePDFError)
In case bank_name was not specified, and our server could not detect the bank, it will throw CannotIdentityBankError (finbox_bankconnect.custom_exceptions.CannotIdentityBankError)
If due to any other reason, the file could not be processed by us, it will throw FileProcessFailedError (finbox_bankconnect.custom_exceptions.FileProcessFailedError)

# Identity

To fetch identity information for an entity use the get_identity method.

identity_dict = entity.get_identity()

It returns the identity dict for the last uploaded / updated account within the entity. The dictionary has the account_id and extracted identity keys like address, etc. as shown in a sample dictionary value below:

{
    "account_id": "uuid4_for_account",
    "account_number": "Account Number Extracted",
    "address": "Address extracted",
    "name": "Name Extracted"
}

NOTE

If the value was not previously retrieved, it will poll and check for progress, and then fetch and cache the retrieved value for next usage.

# Arguments

This method also has following optional arguments:

Argument	Type	Description	Default
reload	Boolean	If provided as `True`, it will ignore the cached value, and again make an API call and re-fetch the values	`False`

# Exceptions

In case the create method was used while creating the entity instance and the entity object was not created on the server yet, it throws ValueError.
In case server could not be reached, it throws ServiceTimeOutError (finbox_bankconnect.custom_exceptions.ServiceTimeOutError).
In case entity_id cannot be found in our server, it throws EntityNotFoundError (finbox_bankconnect.custom_exceptions.EntityNotFoundError)
In case the identity could not be extracted by us, it will throw ExtractionFailedError (finbox_bankconnect.custom_exceptions.ExtractionFailedError)

# Advanced Settings Caution

Other than api_key, following values can also be modified globally as per requirement:

Property	Description	Default Value
`max_retry_limit`	To set the maximum times library will retry if server was unavailable or unreachable	2
`poll_timeout`	To set the timeout time (in seconds) after which `ServiceTimeOutError` will be thrown in case of fetching functions	2
`poll_interval`	To set the polling intervals (in seconds) after which the library will try to make an API call	10
`api_version`	To set the API version to use	v1
`base_url`	In case you are using a proxy and want to change the base url for REST API calls that python library makes	https://apis.bankconnect.finbox.in

Changing base_url property

In case you are using a proxy, and changed the base_url property, just keep in mind that the library will internally make an API call in the following format:

base_url/bank-connect/api_version/<endpoints>

Example for changing polling interval to 1 second:

fbc.poll_interval = 1

# BankConnect: Uploading using Python Package

# Requirements

# Installing Package

# Authentication

# Entity class

# Creating new Entity (get method)

# Fetching already created Entity (create method)

# Entity Properties

# entity_id

# link_id

# Exceptions

# Using Properties

# Uploading Statement

# Exceptions

# Identity

# Arguments

# Exceptions

# Advanced Settings Caution

# `Entity` class

# Creating new Entity (`get` method)

# Fetching already created Entity (`create` method)

# `entity_id`

# `link_id`