Finicity::Ruby

Welcome to finicity-ruby gem. This gem is built to communicate easily with Finicity's Aggregation API. It only uses the JSON representation of the API. Pull requests are welcome to help improving the gem.

• Installation
• Setup
• Usage
  • Institutions
    • List
    • Get specific Institution (with login Credentials)
  • Customers
    • Add new customer
    • List all customers
    • Delete customer
  • Accounts
    • Discover and add all accounts
    • Discover and add all accounts (with MFA)
    • List accounts
    • Get specific account
    • Delete specific account
    • Refresh accounts
    • Refresh accounts (with MFA)
    • Activate accounts
    • Update account credentials
  • Transactions
    • List all transactions
    • List all transactions for specific account
    • Load historic transactions
• Contributing
• License

The gem is available through Rubygems and can be installed via:

$ gem install finicity-ruby

or add it to your Gemfile like this:

gem "finicity-ruby"

Then, in your config/initializers/ add finicity.rb file with corresponding values. Right now we are using redis to store the temp app token which used with each request. In the future, we are going to support multiple options to store token like memory, file & redis. Meanwhile just set the redis_url config into your redis host url.

Finicity.configure do |config|
  config.redis_url      = "redis://127.0.0.1:6379"
  config.app_key        = "xxxxxxxxxxxxxxxx"
  config.partner_id     = "xxxxxxxxxxxxxxxx"
  config.partner_secret = "xxxxxxxxxxxxxxxx"
  config.app_type       = "testing" # or "active" for production apps.
  config.verbose        = false
  config.max_retries    = 1 # How many times do you want to retry the request in case timeout failures.
end

To get all institutions

response = Finicity::Client.institution.list
response.status_code # 200
response.success? # true
response.body.institutions # returns all institutions [{name: "Royal Bank of Canada", id: "1411", ...]

To search for specific institution

Finicity::Client.institution.list(search: "Royal Bank of Canada")

Using the id you just got from the list above, you can find any specific institution

response = Finicity::Client.institution.get("107132")
response.body.institution.login_credentials # [{id: 1231, name: "username", description: "Please enter your username", ...]

Finicity requires username to add a new customer. The response will contain the customer ID to be used for subsequent calls.

response = Finicity::Client.customer.add("YetAnotherBatman")
customer_id = response.body.customer.id

To list all created customers from Finicity.

Finicity::Client.customer.list

Using the customer_id you just got after you add the customer.

Finicity::Client.scope(customer_id).delete

To discover & add the accounts into your customer, you've to authenticate it using the institution#login_credentials.

institution_id = 101732
credentials = [{id: 101732001, name: "Banking Userid", value: "Azzurrio"}, { id: "101732002", name: "Banking Password", value: "LetMePass"]
Finicity::Client.scope(customer_id).account.add_all(institution_id, credentials)

In case you get a MFA required. You can submit the answer into add_all_mfa. The mfa_session will be provided in add_all response headers.

response = Finicity::Client.scope(customer_id).account.add_all(institution_id, credentials)
response.status_code # 203
mfa_session = response.headers["MFA-session"] # e86jnv923nsas4
response.body.questions # [{ text: "What's your super hero?" }]
answers = [{ text: "What's your super hero?", answer: "Batman" }]
Finicity::Client.scope(customer_id).account.add_all_mfa(institution_id, mfa_sessiom, answers)

Finicity::Client.scope(customer_id).account.list

Finicity::Client.scope(customer_id).account.get("236534") # using account id

Finicity::Client.scope(customer_id).account.delete(account_id)

After adding the accounts you have to refresh them so you can have access into their transactions.

Finicity::Client.scope(customer_id).account.refresh(institution_login_id)

In case you get MFA, just like as add_all_mfa

Finicity::Client.scope(customer_id).account.refresh(institution_login_id, mfa_session, answers)

Sometimes you get accounts with type unknown, so you need to activate those accounts with the correct types.

accounts = [{id: 12412, type: "savings"}, {id: 15434, type: "creditCard"}]
Finicity::Client.scope(customer_id).account.activate(institution_id, accounts)

In case account credentials have been changed, you can you get credentials and update them after populating the values correct credentials.

Finicity::Client.scope(customer_id).account.credentials(account_id) # To be used for updating credentials
Finicity::Client.scope(customer_id).account.update_credentials(account_id, credentials)

This one will get all transactions for the given customer. You have to specify the date range using from: and to: named parameters.

Finicity::Client.scope(customer_id).transaction.list(from: 6.months.ago, to: Date.today)

In case you only need transactions for specific account. You have to provide the account_id as extra parameter.

Finicity::Client.scope(customer_id).transaction.list_for_account(account_id, from: 6.months.ago, to: Date.today)

This's a feature in Finicity API which gives you the ability to access +6 months transactions. This could be only used per account and it's an interactive request, which means MFA challenge could be appeared.

Finicity::Client.scope(customer_id).transaction.load_historic(account_id)
Finicity::Client.scope(customer_id).transaction.load_historic_mfa(account_id, mfa_session, answers)

Bug reports and pull requests are welcome on GitHub at https://github.com/Fundthrough/finicity-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.