barrymichaeldoyle / investec-openapi

A JavaScript/TypeScript wrapper to get up and running fast with Investec's Open API for programmable banking.

Investec Programmable Banking Open API Wrapper

A JavaScript/TypeScript wrapper to get up and running fast with Investec's Open API for programmable banking.

Installation

Using npm:

npm install investec-openapi

Using yarn:

yarn add investec-openapi

Usage

Setup:

import api from 'investec-openapi'

api.configure({
  proxyUrl: 'see_docs_below_(for_web_apps)',
  clientId: 'YourClientId_do_not_share'
  secret: 'YourSecret_do_not_share',
  errorCallback: (err) => {
    // Handle errors with getting an access token
    // The err object is either an Error or an HTTP Response from the OAuth server
    console.error(err)
  }
})

The errorCallback is optional. Errors will be logged to std.err if it is not provided.

Get Data:

const fetchData = async () => {
  const accounts = await api.getAccounts()
  console.log(accounts) // prints accounts linked to account

  const accountBalance = await api.getAccountBalance({ accountId: '12345' })
  console.log(accountBalance) // prints account balance

  const accountTransactions = await api.getAccountTransactions({
    accountId: '12345',
    fromDate: '2020-01-20',
    toDate: '2020-01-30'
  })
  console.log(accountTransactions) // prints account transactions for given date range
}

OR:

const fetchData = async () => {
  // prints accounts linked to account
  api.getAccounts().then(accounts => console.log(accounts))

  // prints account balance
  api.getAccountBalance({ accountId: '12345' })
    .then(accountBalance => console.log(accountBalance))

  // prints account transactions for given date range
  api.getAccountTransactions({
    accountId: '12345',
    fromDate: '2020-01-20',
    toDate: '2020-01-30'
  }).then(accountTransactions => console.log(accountTransactions))
}

Documentation

api is a class that once configured will generate an access_token behind the scenes and replace it with a new one once it's within a minute of expiring with no work required on your end.

This wrapper supports getAccounts, getAccountBalance and getAccountTransactions as documented in the Investec Developer Documentation with TypeScript definitions included.

---

api.configure(config)

Sets up api class with credentials to acquire and refresh access_token. Can be called again to change credentials and refresh access_token for new credentials. Other API calls will wait until access_token is set (by calling this function) before running.

config parameters:

proxyUrl - optional (default '')

Note for Web Apps: Without a proxyUrl, you'll experience CORS issues. If anyone has an ideas on how to bypass this more cleanly, let me know! We could probably do with adding a dedicated proxy server, in the meantime you can use this 'https://young-thicket-56542.herokuapp.com/'. Sometimes the Heroko app needs to spin up initially so the first load may take longer than usual. The heroku app is a clone of https://cors-anywhere.herokuapp.com/ from this SO post: https://stackoverflow.com/a/43268098/2111515.

clientId - required

Get this from https://login.secure.investec.com/io/programmable-banking/cards/overview

secret - required

Get this from https://login.secure.investec.com/io/programmable-banking/cards/overview

---

api.getAccounts()

Returns list of accounts with details for configured credentials.

Response:

{
  data: {
    accounts: {
      accountId: string
      accountNumber: string
      accountName: string
      referenceName: string
      productName: string
    }[]
  }
  links: {
    self: string
  }
  meta: {
    totalPages: number
  }
}

---

api.getAccountBalance(accountId)

Returns account balance details for selected account.

request parameters:

accountId - string required

Response:

{
  data: {
    accountId: string
    currentBalance: number
    availableBalance: number
    currency: string
  }
  links: {
    self: string
  }
  meta: {
    totalPages: number
  }
}

---

api.getAccountTransactions(accountId)

Returns list of transaction details for selected account.

request parameters:

accountId - string required

fromDate - string optional - Date value in ISO 8601 (i.e. '2020-01-20')

toDate - string optional - Date value in ISO 8601 (i.e. '2020-01-20')

Response:

{
  data: {
    transactions: {
      accountId: string
      type: string
      status: string
      description: string
      cardNumber: string
      postingData: string
      valueDate: string
      actionDate: string
      amount: number
    }[]
  }
  links: {
    self: string
  }
  meta: {
    totalPages: number
  }
}

---

Hope you find this useful! Please give a star and feel free to contribute or log issues and feature requests!

And if you want to say thanks, then go ahead:



Otherwise you could just say thanks to me on the offerzen-community slack @barrymichaeldoyle :)

investec-openapi's Issues

fetch is not defined when running from node

Hi there, I'm having some trouble getting this module to work in nodejs.

There seems to be a dependency on node-fetch which isn't coming through
when installed via npm. Nor is the dependency explicitly required in the compiled output.

I tried running the example in the README in both plain node and tsc and I get the same error:

ReferenceError: fetch is not defined
    at InvestecOpenAPI.<anonymous> (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:173:25)
    at step (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:33:23)
    at Object.next (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:14:53)
    at ./node_modules/investec-openapi/lib/InvestecOpenAPI.js:8:71
    at new Promise (<anonymous>)
    at __awaiter (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:4:12)
    at InvestecOpenAPI.getAccessToken (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:161:16)
    at InvestecOpenAPI.<anonymous> (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:128:55)
    at step (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:33:23)
    at Object.next (./node_modules/investec-openapi/lib/InvestecOpenAPI.js:14:53)

I'm not familiar with the TS & Node compatible package structure these days, so I'm
not sure where to start.