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 :)