GitHub - fintoc-com/fintoc-ruby: The official Ruby library for the Fintoc API

Fintoc meets Ruby

You have just found the Ruby-flavored client of Fintoc. It mainly consists of a port (more of a carbon copy, really) of fintoc-python.

Why?

You can think of Fintoc API as a piscola. And the key ingredient to a properly made piscola are the ice cubes. Sure, you can still have a piscola without ice cubes. But hey… that’s not enjoyable -- why would you do that? Do yourself a favor: go grab some ice cubes by installing this refreshing library.

Fintoc meets Ruby

How to Install

Add this line to your application's Gemfile:

And then execute:

$ bundle install

Or install it yourself as:

$ gem install fintoc

Quickstart

Get your API key and link your bank account using the Fintoc dashboard.
Open your command-line interface.
Write a few lines of Ruby code to see your bank movements.

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
link = client.v1.links.get('link_token')
account = link.find(type: 'checking_account')

# Get the last 30 movements
movements = account.movements.list

# Or get all the movements since a specific date
movements = account.movements.list(since: '2020-08-15')

And that’s it!

Client Architecture

The Fintoc Ruby client is organized into separate clients that mirror the official API structure:

API V1 Client

The API client currently provides access to part of the Movements API:

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Link management
links = client.v1.links.list
link = client.v1.links.get('link_token')
client.v1.links.delete('link_id')

# Account access
account = link.find(id: account_id)

API V2 Client

The API V2 client currently provides access to part of the Transfers API:

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Entities
entities = client.v2.entities.list
entity = client.v2.entities.get('entity_id')

# Accounts
accounts = client.v2.accounts.list
account = client.v2.accounts.get('account_id')
account = client.v2.accounts.create(entity_id: 'entity_id', description: 'My Account')
client.v2.accounts.update('account_id', description: 'Updated')

# Account Numbers
account_numbers = client.v2.account_numbers.list
account_number = client.v2.account_numbers.get('account_number_id')
account_number = client.v2.account_numbers.create(account_id: 'account_id', description: 'Main')
client.v2.account_numbers.update('account_number_id', description: 'Updated')

# Transfers
transfers = client.v2.transfers.list
transfer = client.v2.transfers.get('transfer_id')
transfer = client.v2.transfers.create(
  amount: 1000,
  currency: 'CLP',
  account_id: 'account_id',
  counterparty: {...}
)
client.v2.transfers.return('transfer_id')

# Simulate
simulated_transfer = client.v2.simulate.receive_transfer(
  account_number_id: 'account_number_id',
  amount: 1000,
  currency: 'CLP'
)

# Account Verifications
account_verifications = client.v2.account_verifications.list
account_verification = client.v2.account_verifications.get('account_verification_id')
account_verification = client.v2.account_verifications.create(account_number: 'account_number')

# TODO: Movements

Backward compatibility

The methods of the previous Fintoc::Client class implementation are kept for backward compatibility purposes.

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

link = client.get_link('link_token')
links = client.get_links
client.delete_link(link.id)
account = client.get_account('link_token', 'account_id')

Documentation

This client does not support all Fintoc API endpoints yet. For complete information about the API, head to the docs.

Examples

Movements API Examples

Get accounts

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
link = client.v1.links.get('link_token')
puts link.accounts

# Or... you can pretty print all the accounts in a Link

link = client.v1.links.get('link_token')
link.show_accounts

If you want to find a specific account in a link, you can use find. You can search by any account field:

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
link = client.v1.links.get('link_token')
account = link.find(type: 'checking_account')

# Or by number
account = link.find(number: '1111111')

# Or by account id
account = link.find(id: 'sdfsdf234')

You can also search for multiple accounts matching a specific criteria with find_all:

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
link = client.v1.links.get('link_token')
accounts = link.find_all(currency: 'CLP')

To update the account balance you can use update_balance:

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
link = client.v1.links.get('link_token')
account = link.find(number: '1111111')
account.update_balance

Get movements

require 'fintoc'
require 'time'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
link = client.v1.links.get('link_token')
account = link.find(type: 'checking_account')

# You can get the account movements since a specific DateTime
yesterday = DateTime.now - 1
account.movements.list(since: yesterday)

# Or you can use an ISO 8601 formatted string representation of the Date
account.movements.list(since: '2020-01-01')

# You can also set how many movements you want per_page
account.movements.list(since: '2020-01-01', per_page: 100)

Calling movements.list without arguments gets the last 30 movements of the account

Transfers API Examples

Entities

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Get all entities
entities = client.v2.entities.list

# Get a specific entity
entity = client.v2.entities.get('entity_id')

You can also list entities with pagination:

# Get entities with pagination
entities = client.v2.entities.list(limit: 10, starting_after: 'entity_id')

Accounts

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Create an account
account = client.v2.accounts.create(
  entity_id: 'entity_id',
  description: 'My Business Account'
)

# Get a specific account
account = client.v2.accounts.get('account_id')

# List all accounts
accounts = client.v2.accounts.list

# Update an account
updated_account = client.v2.accounts.update('account_id', description: 'Updated Description')

Account Numbers

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Create an account number
account_number = client.v2.account_numbers.create(
  account_id: 'account_id',
  description: 'Main account number'
)

# Get a specific account number
account_number = client.v2.account_numbers.get('account_number_id')

# List all account numbers
account_numbers = client.v2.account_numbers.list

# Update an account number
updated_account_number = client.v2.account_numbers.update(
  'account_number_id',
  description: 'Updated account number'
)

Transfers

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Create a transfer
transfer = client.v2.transfers.create(
  amount: 10000,
  currency: 'CLP',
  account_id: 'account_id',
  counterparty: {
    name: 'John Doe',
    rut: '12345678-9',
    email: 'john@example.com',
    bank: 'banco_de_chile',
    account_type: 'checking_account',
    account_number: '1234567890'
  }
)

# Get a specific transfer
transfer = client.v2.transfers.get('transfer_id')

# List all transfers
transfers = client.v2.transfers.list

# Return a transfer
returned_transfer = client.v2.transfers.return('transfer_id')

Simulate

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Simulate receiving a transfer
simulated_transfer = client.v2.simulate.receive_transfer(
  account_number_id: 'account_number_id',
  amount: 5000,
  currency: 'CLP'
)

Account Verifications

require 'fintoc'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

# Create an account verification
account_verification = client.v2.account_verifications.create(account_number: 'account_number')

# Get a specific account verification
account_verification = client.v2.account_verifications.get('account_verification_id')

# List all account verifications
account_verifications = client.v2.account_verifications.list

Idempotency Keys

The Fintoc API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is particularly useful when creating transfers, account numbers, accounts, or other resources where you want to avoid duplicates due to network issues.

To use idempotency keys, provide an idempotency_key parameter when making POST/PATCH requests:

Idempotency Examples

Account Methods with Idempotency Key

Create and update methods support the use of idempotency keys to prevent duplication:

require 'fintoc'
require 'securerandom'

client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')

idempotency_key = SecureRandom.uuid
account = client.v2.accounts.create(
  entity_id: 'entity_id', description: 'My Business Account', idempotency_key:
)

idempotency_key = SecureRandom.uuid
updated_account = client.v2.accounts.update(
  'account_id', description: 'Updated Description', idempotency_key:
)

Simulation of transfers can also be done with idempotency key:

idempotency_key = SecureRandom.uuid
account.simulate_receive_transfer(amount: 1000, idempotency_key:)

Account Number Methods with Idempotency Key

Create and update methods support the use of idempotency keys as well:

idempotency_key = SecureRandom.uuid
account_number = client.v2.account_numbers.create(
  account_id: 'account_id', description: 'Main account number', idempotency_key:
)

idempotency_key = SecureRandom.uuid
updated_account_number = client.v2.account_numbers.update(
  'account_number_id', description: 'Updated description', idempotency_key:
)

Simulation of transfers can also be done with idempotency key:

account_number.simulate_receive_transfer(amount: 1000, currency: 'MXN', idempotency_key:)

Transfer Methods with Idempotency Key

Creating and returning transfers support the use of idempotency keys:

idempotency_key = SecureRandom.uuid
transfer = client.v2.transfers.create(
  amount: 10000, currency: 'CLP', account_id: 'account_id', counterparty: { ... }, idempotency_key:
)

idempotency_key = SecureRandom.uuid
returned_transfer = client.v2.transfers.return('transfer_id', idempotency_key:)

Returning a transfer as an instance method also supports the use of idempotency key:

idempotency_key = SecureRandom.uuid
transfer.return_transfer(idempotency_key:)

Simulation with Idempotency Key

For simulating transfers, the use of idempotency keys is also supported:

idempotency_key = SecureRandom.uuid
simulated_transfer = client.v2.simulate.receive_transfer(
  account_number_id: 'account_number_id', amount: 5000, currency: 'CLP', idempotency_key:
)

Account Verification with Idempotency Key

idempotency_key = SecureRandom.uuid
account_verification = client.v2.account_verifications.create(
  account_number: 'account_number', idempotency_key:
)

About idempotency keys

Idempotency keys can be up to 255 characters long
Use consistent unique identifiers for the same logical operation (e.g. order IDs, transaction references). If you set them randomly, we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
The same idempotency key will return the same result, including errors
Keys are automatically removed after 24 hours
Only POST and PATCH requests currently support idempotency keys
If parameters differ with the same key, an error will be raised

For more information, see the Fintoc API documentation on idempotent requests.

Development

Dependencies

This gem supports Ruby 2.3+ but development requires modern tooling:

Ruby: 2.3+ (3.2+ recommended for development)
Bundler: 2.7+ (for development)
Git: For version control

Setup

# Clone the repository
git clone https://github.com/fintoc-com/fintoc-ruby.git
cd fintoc-ruby

# Install dependencies (requires Bundler 2.7+)
bundle install

# Run tests
bundle exec rspec

# Run linting
bundle exec rubocop

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fintoc-com/fintoc-ruby.