Investec Open API

This is a wrapper for the Investec Open API https://developer.investec.com/programmable-banking/

Please note

The API is currently in public beta, and might change (adding more functionality or changing existing behavior). I will try and keep this updated as changes are released.

Unfortunately I am unable to assist with gaining access to the beta program.

Installation

The package can be installed by adding investec_open_api to your list of dependencies in mix.exs:

def deps do
  [
    {:investec_open_api, git: "https://gitlab.com/theodowling/elixir-investec-open-api"}
  ]
end

After you added this to your dependencies, remember to run mix deps.get

Considerations

There are two ways to authenticate using this package.

you can add your client_id and client_secret in the config of the application allowing you to start an authenticate client directly with InvestecOpenApi.new/0
store the client_id and client_secret somewhere else, and manually use it every time you want to start a new client using InvestecOpenApi.new(client_id, client_secret)

[Optional] Adding `client_id` and `client_secret` in your config

If you want to only authenticate the same account each time, you can add the following to your config:

config :investec_open_api,
  client_id: "thisIsmysecretclientId",
  client_secret: "verySuperSecureSecret"

Usage

Start an authenticated session/client

If you have your client_id and client_secret in your config (see above for details) you can use this:

iex> {:ok, client} = InvestecOpenApi.new()
{:ok,
 %InvestecOpenApi.Client{
   access_token: "your_new_access_token",
   client_id: "thisIsmysecretclientId",
   client_secret: "verySuperSecureSecret",
   expires_at: 1594999999,
   method: :token
 }}

Otherwise you can always pass the credentials directly:

iex> {:ok, client} = InvestecOpenApi.new(your_client_id, your_client_secret)
{:ok,
 %InvestecOpenApi.Client{
   access_token: "your_new_access_token",
   client_id: "your_client_id",
   client_secret: "your_client_secret",
   expires_at: 1594999999,
   method: :token
 }}

You can now use this authenticated client/session to call any of the available methods exposed through the Investec Open API.

Currently the following methods are available:

1. Get Accounts

Use an authenticated client to get the list of accounts

# First create a client
iex> {:ok, client} = InvestecOpenApi.new()

# You can then use this client to get list of accounts:
iex> {:ok, accounts, client} = InvestecOpenApi.list_accounts(client)
iex> accounts
[
  %InvestecOpenApi.Accounts{account_id: "172878438321553632224",
  account_name: "Mr John Doe",
  account_number: "10010206147",
  product_name: "Private Bank Account",
  reference_name: "My Investec Private Bank Account"}
]

See InvestecOpenApi.Accounts for more information

2. Get Account Transactions

Use an authenticated client an an account to get list of the transactions on the account

# First create a client
iex> {:ok, client} = InvestecOpenApi.new()

# Use this client to get list of accounts - pattern matching on the first one:
iex> {:ok, [account | _], client} = InvestecOpenApi.list_accounts(client)

# Use this client to get list of transactions for the given account:
iex> {:ok, transactions, client} = InvestecOpenApi.list_account_transactions(client, account)

# Get the first transaction
iex> List.first(transactions)
%InvestecOpenApi.Accounts.Transaction{
  account_id: "172878438321553632224",
  action_date: "2020-06-18",
  amount: 535,
  card_number: "",
  description: "MONTHLY SERVICE CHARGE",
  posting_date: "2020-06-11",
  status: "POSTED",
  type: "DEBIT",
  value_date: "2020-06-10"
}

See InvestecOpenApi.Accounts.Transaction for more information

3. Get Account Balance

Use an authenticated client an an account to get the balance of the account

# First create a client
iex> {:ok, client} = InvestecOpenApi.new()

# Use this client to get list of accounts - pattern matching on the first one.
iex> {:ok, [account | _], client} = InvestecOpenApi.list_accounts(client)

# Use this client to get the balance for the given account:
iex> {:ok, balance, client} = InvestecOpenApi.get_account_balance(client, account)
iex> balance
%InvestecOpenApi.Accounts.Balance{
  account_id: "172878438321553632224",
  available_balance: 98857.76,
  currency: "ZAR",
  current_balance: 28857.76
}

See InvestecOpenApi.Accounts.Balance for more information

Contributing

Thanks for considering contributing to this project, and to the free software ecosystem at large!

Interested in contributing a bug report? Terrific! Please open a GitLab issue and include as much detail as you can. If you have a solution, even better -- please open a pull request with a clear description and tests.

Have a feature idea? Excellent! Please open a GitLab issue for discussion.

Want to implement an issue that's been discussed? Fantastic! Please open a GitLab pull request and write a clear description of the patch. We'll merge your PR a lot sooner if it is well-documented and fully tested.

License

This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See the LICENSE file for more details.

v0.1.0