Programmable Banking

Example conditional transaction approval

// Check with my API before approving transaction
const beforeTransaction = async (authorization) => {
    const response = await fetch('https://postman-echo.com/get?foo1=bar1&foo2=bar2', {
        method: 'GET',
        headers: {'Content-Type': 'application/json'}
    });
    const json = await response.json();
    // foo and bar available via json.args
    console.log(json.args);
    return json.args.foo1 === 'bar1';
};

const afterTransaction = async (transaction) => {
    // do something after the `transaction` is approved or declined
};

Above code's simulated output

{
    "beforeTransaction": {
        "time": null,
        "output": {
            "sandbox": true,
            "type": "before_transaction",
            "authorizationApproved": true,
            "logs": [
                {
                    "foo1": "bar1",
                    "foo2": "bar2"
                }
            ],
            "createdAt": "/Date(1592426721179)/",
            "startedAt": "/Date(1592426721179)/",
            "completedAt": "/Date(1592426722389)/",
            "updatedAt": "/Date(1592426721179)/",
            "error": null
        }
    },
    "afterTransaction": {
    ...
}

Build your own rules and limits with securely hosted Javascript functions that execute before and after your card transactions. Limit your fast-food spend, track your coffee intake on the fly - anything goes.

Niche developer banking, built with the community

Investec Private Bank offers distinctive banking for distinguished individuals. Software development is a profession of the future, and Investec and OfferZen are working together with the community on a mission to enable developers to access the world of banking.

Prerequisite

This documentation assumes that you have a basic understanding of Javascript and, are aware of the consequences of executing programmatic logic against your card transactions, e.g. resulting in a transaction being decline as a result of logic you have programmed against your Investec credit card.

Features included

Online JS IDE/code editor based on Monaco Editor, the code editor that powers VS Code
Two hooks which you can access with every card transaction, beforeTransaction and afterTransaction
Intercept card transaction and decline based on your "code" with beforeTransaction hook
Publish "code" to securely hosted VM instance
Perform transaction simulation using online simulator
Enable/disable the code executing against a specific card
Access to the card authorization object and meta-data
Run code after a processed using the afterTransaction() function. for instance: post your transaction to an app you built
Call external an APIs using node-fetch

main.js

beforeTransaction and afterTransaction are required

// main.js
const beforeTransaction = async () => {
    // ..
}

const afterTransaction = async () => {
    // ..
}

main.js requires two methods for card transaction interception:

beforeTransaction
afterTransaction

Note that the beforeTransaction method has a limited window of 2 seconds to execute hence needs to be fast. afterTransaction has a much larger window limit of 15 seconds which gives you more time to communicate with internal and external resources.

main.js

Before transaction

Every time you execute a transaction from your Investec card, the beforeTransaction method intercepts the authorization object before it is approved by Investec.

Within this method, you can apply logic to either decline or approve the transaction based on data from the card authorization itself, or via external data sources fetched via http. Please note that you MUST return a boolean in order for this method to work.

Approve authorization

Approve a transaction

// main.js
const beforeTransaction = async () => {
    // always APPROVE
    return true;
}

return true will approve an authorization.

Decline authorization

Decline a transaction

// main.js
const beforeTransaction = async () => {
    // always DECLINE
    return false;
}

return false will decline a authorization.

Apply conditional logic within before transaction method

Apply conditional to a transaction

// main.js
const beforeTransaction = async (authorization) => {
    return authorization.centsAmount < 5000; // authorization.amount is in cents
}

Apply conditional logic within before transaction method Say you wanted to decline any transaction that is R50.00 and above - if the authorization.centsAmount is less than R50.00, then approve. Else decline the transaction.

TIP: Use console.log(authorization) to see available properties of the authorization that are accessible.

After transaction

Log transaction object to console

// main.js
const afterTransaction = async (transaction) => {
    console.log(transaction);
}

The afterTransaction method is executed once the beforeTransaction method has completed and returned a response. This method has a much longer window of time for your to interact/communicate with data sources such as updating a external DB.

env.json

Define a environment variable in env,json

{
    "foo": "bar"
}

Within env.json, you are able to save variable - a variable whose value is set outside main.js. An environment variable is made up of a name/value pair, and any number may be created and available for reference at a point in time within main.js.

To reference a value define in env.js within main.js, you can access all your variables via process.env.

main.js

Access environment variable within main.js

// main.js
const afterTransaction = async (transaction) => {
    // console log the foo key's value
    console.log(process.env.foo);
}

Once a environment variable has been defined and saved, you can access it from within main.js.

Simulating a transaction

use reference to identify simulated transactions

// main.js
const afterTransaction = async (transaction) => {
    if(transaction.reference === 'simulation') {
        // this is a simulated transaction
    }
}

You can differentiate between a simulated transaction and a production transaction by the transaction reference

main.js

Open API

Introduction

The Account Information API allows Investec SA Private Banking clients to access their account and transactional information (read-only) via an API.

It can be used to retrieve account information such as:

Account details
Balances
Account transactions

There are many possible use cases for the Account Information API: from extracting the data to aggregate it with financial data from other banking institutions to personal money management tools.

Release Notes

2020-11-13

Enhancement: Included transaction type filter to Get Account Transactions

2020-11-10

Enhancement: Included postedOrder to Get Account Transactions
Enhancement: Included transactionType to Get Account Transactions

2020-09-08

Fix: Implemented CORS support
Fix: Implemented multi User-Agent support

2020-07-21

Enhancement: Included transactionDate to Get Account Transactions
Enhancement: Included date range filter to Get Account Transactions

Authorization

The Account Information API's endpoints are protected by the OAuth 2.0 Authorization Framework: https://tools.ietf.org/html/rfc6749

Supported Grant Type(s)

client_credentials

Supported Scope(s)

accounts

Enrolment

In order to obtain you OAuth credentials, simply:

Login to Investec Online.
Navigate to the Programmable Banking landing page.
Select the Open API tab.
Select the Enroll button.

Get Access Token

Example Request


POST https://openapi.investec.com/identity/v2/oauth2/token HTTP/1.1
Authorization: Basic e2NsaWVudElkfTp7c2VjcmV0fQ==
Host: openapi.investec.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json


$.ajax({
   url: 'https://openapi.investec.com/identity/v2/oauth2/token',
   type: 'POST',
   contentType: 'application/x-www-form-urlencoded',
   data: 'grant_type=client_credentials&scope=accounts',
   headers: {
      'Authorization': 'Basic e2NsaWVudElkfTp7c2VjcmV0fQ=='
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response


{
    "access_token": "Ms9OsZkyrhBZd5yQJgfEtiDy4t2c",
    "token_type": "Bearer",
    "expires_in": 1799,
    "scope": "accounts"
}

POST /identity/v2/oauth2/token

Obtain an access token

HTTP Status Codes

HTTP Status	Description
200 - OK	The requested operation was successfully completed
400 - Bad Request	The requested operation will not be carried out
401 - Unauthorized	The requested operation was refused access
500 - Internal Server Error	The requested operation failed to execute

Get Accounts

Example Request


GET https://openapi.investec.com/za/pb/v1/accounts HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json


$.ajax({
   url: 'https://openapi.investec.com/za/pb/v1/accounts',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response


{
    "data": {
        "accounts": [
            {
                "accountId": "172878438321553632224",
                "accountNumber": "10010206147",
                "accountName": "Mr John Doe",
                "referenceName": "My Investec Private Bank Account",
                "productName": "Private Bank Account"
            }
        ]
    },
    "links": {
        "self": "https://openapi.investec.com/za/pb/v1/accounts"
    },
    "meta": {
        "totalPages": 1
    }
}

GET /za/pb/v1/accounts

Obtain a list of accounts.

HTTP Status Codes

HTTP Status	Description
200 - OK	The requested operation was successfully completed
400 - Bad Request	The requested operation will not be carried out
401 - Unauthorized	The requested operation was refused access
500 - Internal Server Error	The requested operation failed to execute

Get Account Transactions

Example Request


GET https://openapi.investec.com/za/pb/v1/accounts/{accountId}/transactions?fromDate={fromDate}&toDate={toDate}&transactionType={transactionType} HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json


$.ajax({
   url: 'https://openapi.investec.com/za/pb/v1/accounts/{accountId}/transactions?fromDate={fromDate}&toDate={toDate}&transactionType={transactionType}',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response


{
    "data": {
        "transactions": [
            {
                "accountId": "172878438321553632224",
                "type": "DEBIT",
                "transactionType": "FeesAndInterest",
                "status": "POSTED",
                "description": "MONTHLY SERVICE CHARGE",
                "cardNumber": "",
                "postedOrder": 13379,
                "postingDate": "2020-06-11",
                "valueDate": "2020-06-10",
                "actionDate": "2020-11-10",
                "transactionDate": "2020-06-10",
                "amount": 535.0,
                "runningBalance": 28857.76
            },
            {
                "accountId": "172878438321553632224",
                "type": "CREDIT",
                "transactionType": "FeesAndInterest",
                "status": "POSTED",
                "description": "CREDIT INTEREST",
                "cardNumber": "",
                "postedOrder": 13378,
                "postingDate": "2020-06-11",
                "valueDate": "2020-06-10",
                "actionDate": "2020-11-10",
                "transactionDate": "2020-06-10",
                "amount": 31.09,
                "runningBalance": 29392.76
            }
        ]
    },
    "links": {
        "self": "https://openapi.investec.com/za/pb/v1/accounts/{accountId}/transactions?fromDate={fromDate}&toDate={toDate}&transactionType={transactionType}"
    },
    "meta": {
        "totalPages": 1
    }
}

GET /za/pb/v1/accounts{accountId}/transactions?fromDate={fromDate}&toDate={toDate}&transactionType={transactionType}

Obtain a specified account's transactions.

Parameters

Name	In	Type	Required	Description
fromDate	query	ISO8601 formatted date string	optional	Refers to the date range filter's start date. Will default to today's date, minus 180 days, if not specified.
toDate	query	ISO8601 formatted date string	optional	Refers to the date range filter's end date. Will default to today's date if not specified.
transactionType	query	string	optional	Refers to the transaction type filter's value.

HTTP Status Codes

HTTP Status	Description
200 - OK	The requested operation was successfully completed
400 - Bad Request	The requested operation will not be carried out
401 - Unauthorized	The requested operation was refused access
500 - Internal Server Error	The requested operation failed to execute

Get Account Balance

Example Request


GET https://openapi.investec.com/za/pb/v1/accounts/{accountId}/balance HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json


$.ajax({
   url: 'https://openapi.investec.com/za/pb/v1/accounts/{accountId}/balance',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response


{
    "data": {
        "accountId": "172878438321553632224",
        "currentBalance": 28857.76,
        "availableBalance": 98857.76,
        "currency": "ZAR"
    },
    "links": {
        "self": "https://openapi.investec.com/za/pb/v1/accounts/{accountId}/balance"
    },
    "meta": {
        "totalPages": 1
    }

GET /za/pb/v1/accounts{accountId}/balance

Obtain a specified account's balance.

HTTP Status Codes

HTTP Status	Description
200 - OK	The requested operation was successfully completed
400 - Bad Request	The requested operation will not be carried out
401 - Unauthorized	The requested operation was refused access
500 - Internal Server Error	The requested operation failed to execute