NAV Navbar
javascript

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.

IMAGE ALT TEXT HERE

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

main.js

beforeTransaction and afterTransaction are required

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

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

main.js requires two methods for card transaction interception:

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:

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

2020-11-10

2020-09-08

2020-07-21

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)

Supported Scope(s)

Enrolment

In order to obtain you OAuth credentials, simply:

  1. Login to Investec Online.
  2. Navigate to the Programmable Banking landing page.
  3. Select the Open API tab.
  4. 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