🌟 Community-Powered Repository 🌟

This repository is crafted with ❤️ by our talented community members. It's a space for everyone to use, contribute to, and share. While it aligns with the spirit of our community, please note that this repo is not directly endorsed or supported by Investec. Always exercise caution and discretion when using or contributing to community-driven projects.

InvestecOpenApi Client

A simple client wrapper for the Investec Open API.

Features:

Authorize access via OAuth
Retrieve accounts
Retrieve transactions per account
Retrieve balances per account
Transfer between accounts

Requirements

Ruby 2.7.0 or higher

Installation

Add this line to your application's Gemfile:

gem 'investec_open_api'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install investec_open_api

Configuration

To configure the client, create a new file in the root of your directory called .env and place the following:

API_KEY='YOUR API KEY'
CLIENT_ID='YOUR CLIENT ID'
CLIENT_SECRET='YOUR CLIENT SECRET'

Note: you will need to register to get the above credentials. Follow the steps in Enrolment in the documentation. You can also test in sandbox mode (see Running in Sandbox Mode).

Once you have set this up, configure the client using:

InvestecOpenApi.configuration do |config|
    config.api_key       = ENV['API_KEY']
    config.client_id     = ENV['CLIENT_ID']
    config.client_secret = ENV['CLIENT_SECRET']
    config.base_url      = ENV['BASE_URL'] # optional
end

For Rails apps, create a new initializer called investec_open_api.rb in config/initializers:

Usage

To use the wrapper, create an instance of InvestecOpenApi::Client and then authenticate with your credentials:

client = InvestecOpenApi::Client.new
client.authenticate!

Accounts

Calling accounts returns all of the associated accounts:

accounts = client.accounts
my_account = accounts.first

List transactions for an account

You can list your transactions by passing the account id into the transactions method:

# The dates are optional
client.transactions(my_account.id, { fromDate: "2024-01-01", toDate: "2024-01-31" })

To list pending transactions use the following:

# The dates are optional
client.pending_transactions(my_account.id, { fromDate: "2024-01-01", toDate: "2024-01-31" })

Get Balance for an account

Pass the account_id into the balance method to get the latest account balances:

client.balance(my_account.id)

Inter-account transfers

To transfer between accounts, create a InvestecOpenApi::Models::Transfer object and pass it into the transfer_multiple method:

transfer = InvestecOpenApi::Models::Transfer.new(
  beneficiary_account_id,
  1000.00, # amount as a Float
  "My reference - of the account transferring from",
  "Their reference - of the account transferring to"
)
client.transfer_multiple(
  my_account.id,
  [ transfer ],
  profile_id # optional
)

Error Handling

The client raises specific exceptions for different error scenarios. Always wrap API calls in error handling:

Custom Exception Classes

InvestecOpenApi::AuthenticationError - Raised when OAuth authentication fails
InvestecOpenApi::ValidationError - Raised when required parameters are missing or invalid
InvestecOpenApi::NotFoundError - Raised when a requested resource is not found
InvestecOpenApi::APIError - Raised for general API errors
InvestecOpenApi::RateLimitError - Raised when rate limits are exceeded

Example: Handling Errors

client = InvestecOpenApi::Client.new

begin
  client.authenticate!
rescue InvestecOpenApi::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
  # Handle authentication error
end

begin
  transactions = client.transactions(account_id)
rescue InvestecOpenApi::ValidationError => e
  puts "Invalid parameters: #{e.message}"
  # Handle validation error
rescue InvestecOpenApi::NotFoundError => e
  puts "Account not found: #{e.message}"
  # Handle not found error
rescue InvestecOpenApi::APIError => e
  puts "API error occurred: #{e.message}"
  # Handle general API error
end

begin
  transfer = InvestecOpenApi::Models::Transfer.new(
    beneficiary_id,
    1000.00,
    "my ref",
    "their ref"
  )
rescue InvestecOpenApi::ValidationError => e
  puts "Invalid transfer parameters: #{e.message}"
  # Handle validation error
end

Thread Safety

Important: The client instance caches a Faraday connection object. If you're using this client in a multi-threaded environment (such as a Rails application), ensure that each thread has its own instance of InvestecOpenApi::Client:

# ✅ Correct: Each thread gets its own client
threads = 5.times.map do
  Thread.new do
    client = InvestecOpenApi::Client.new
    client.authenticate!
    # Use the client...
  end
end
threads.each(&:join)

# ❌ Incorrect: Sharing a single client across threads
client = InvestecOpenApi::Client.new
client.authenticate!
threads = 5.times.map do
  Thread.new do
    # Don't do this - connection caching is not thread-safe
    client.accounts
  end
end
threads.each(&:join)

Running in Sandbox mode

To run in sandbox mode, use the following configuration:

InvestecOpenApi.configuration do |config|
  config.api_key = "eUF4elFSRlg5N3ZPY3lRQXdsdUVVNkg2ZVB4TUE1ZVk6YVc1MlpYTjBaV010ZW1FdGNHSXRZV05qYjNWdWRITXRjMkZ1WkdKdmVBPT0="
  config.client_id = "yAxzQRFX97vOcyQAwluEU6H6ePxMA5eY"
  config.client_secret = "4dY0PjEYqoBrZ99r"
  config.base_url = "https://openapisandbox.investec.com/"
end

You can now test the API without affecting your actual account.

License

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