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 - Authorization

The Account Information and Programmable Card API 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

Open API - Accounts

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 (Accounts)

2020-11-13

2020-11-10

2020-09-08

2020-07-21

2021-10-01


Get Accounts

GET /za/pb/v1/accounts

Obtain a list of accounts in associated profile.

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 Account Balance

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

Obtain a specified account's 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 Account Transactions

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

Obtain a specified account's 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
    }
}

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Open API - Programmable Cards API

The Programmable card API API allows Investec SA Private Banking clients to access their programmable card functionality via an API.

It can be used to retrieve account information such as:

Release Notes (Cards)


Get Cards

GET /za/v1/cards

Obtain cards associated with the account.

Example Request

GET https://openapi.investec.com/za/v1/cards HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "cards": [
            {
                "CardKey": "1010101",
                "CardNumber": "402167XXXXXX1111",
                "IsProgrammable": true,
                "Status": "Active",
                "CardTypeCode": "VGC",
                "AccountNumber": "10011001100",
                "AccountId": "177778438355553632224",
            },
            {
                "CardKey": "1020202",
                "CardNumber": "402167XXXXXX2222",
                "IsProgrammable": true,
                "Status": "Active",
                "CardTypeCode": "VGC",
                "AccountNumber": "10011001100",
                "AccountId": "177778438355553632224",
            },
            {
                "CardKey": "1030303",
                "CardNumber": "402167XXXXXX3333",
                "IsProgrammable": true,
                "Status": "Active",
                "CardTypeCode": "VGC",
                "AccountNumber": "10011001100",
                "AccountId": "177778438355553632224",
            }
        ]
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Function (saved) code

GET /za/v1/cards/{cardkey}/code

Obtain code currently saved to the specific card.

Example Request:

GET https://openapi.investec.com/za/v1/cards/{cardkey}/code HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/code',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "codeId": "3BB77753-R2D2-4U2B-1A2B-4C213E7D0AC3",
            "code": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};",
            "createdAt": "2021-10-12T09:12:06.695Z",
            "updatedAt": "2021-10-12T09:12:06.695Z",
            "publishedAt": "2021-10-12T09:12:16.557Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Function (published) code

GET /za/v1/cards/{cardkey}/publishedcode

Obtain code currently published to the specific card.

Example Request:

GET https://openapi.investec.com/za/v1/cards/{cardkey}/publishedcode HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{card_id}/publishedcode',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "codeId": "3BB77753-R2D2-4U2B-1A2B-4C213E7D0AC3",
            "code": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};",
            "createdAt": "2021-10-12T09:12:06.695Z",
            "updatedAt": "2021-10-12T09:12:06.695Z",
            "publishedAt": "2021-10-12T09:12:16.557Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Update Function Code (Without publishing to card)

POST /za/v1/cards/{cardkey}/code

Save specified code to the specific card.
Note: This allows you to save/stage the code to the card without publishing it. This implies that the code will not execute when a card transaction occurs.

Example Request:

POST https://openapi.investec.com/za/v1/cards/{cardkey}/code HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json

{
    "code": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};"
}
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/code',
   type: 'POST',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   data: {
    "code": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};"
  }
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "codeId": "3BB77753-R2D2-4U2B-1A2B-4C213E7D0AC3",
            "code": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};",
            "createdAt": "2021-10-12T09:12:06.695Z",
            "updatedAt": "2021-10-12T09:12:06.695Z",
            "publishedAt": "2021-10-12T09:12:16.557Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.
code body string required The javascript code that will be published to the card.

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Publish Saved Code

POST /za/v1/cards/{cardkey}/publish

Publish specified code to the specific card.
*Note: This will mark the saved code as the published code ready for execution. Remember to specify the {codeid} obtained from the Get Function (saved) code *

Example Request:

POST https://openapi.investec.com/za/v1/cards/{cardkey}/publish HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json

{
    "codeid": "{codeid}",
    "code": " "
}
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/publish',
   type: 'POST',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   data: {
    "codeid": "{codeid}",
    "code": " "
  }
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "codeId": "3BB77753-R2D2-4U2B-1A2B-4C213E7D0AC3",
            "code": " ",
            "createdAt": "2021-10-12T09:12:06.695Z",
            "updatedAt": "2021-10-12T09:12:06.695Z",
            "publishedAt": "2021-10-12T09:12:16.557Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.
codeid body string required Refers to the codeid of the saved code which can be obtained from the Get Function (saved) Code endpoint.
code body string required Although this is a required field you can leave it blank " "

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Execute Function Code (Simulation)

POST /za/v1/cards/{cardkey}/code/execute

Publish specified code to the specific card.
Note: This allows you to push code to the specified card. After successfully publishing the code it will execute the next time a card transaction occurs.

Example Request:

POST https://openapi.investec.com/za/v1/cards/{cardkey}/execute HTTP/1.1
Authorization: Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c
Host: openapi.investec.com
Accept: application/json

{
    "simulationcode": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};",
    "centsAmount": "10100",
    "currencyCode": "zar",
    "merchantCode": 7996,
    "merchantCity": "Durban",
    "countryCode": "ZA"
}
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/execute',
   type: 'POST',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   data: {
    "code": "// This function runs during the card transaction authorization flow.\n// It has a limited execution time, so keep any code short-running.\nconst beforeTransaction = async (authorization) => {\n    console.log(authorization);\n    return true;\n};\n\n// This function runs after a transaction.\nconst afterTransaction = async (transaction) => {\n    console.log(transaction)\n};\n\n// This function runs after a transaction.\nconst afterDecline = async (transaction) => {\n    console.log(transaction)\n};",
    "centsAmount": "10100",
    "currencyCode": "zar",
    "merchantCode": 7996,
    "merchantCity": "Durban",
    "countryCode": "ZA"
  }
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": [
            {
                "executionId": "ABB8854D-B3A4-4450-BB9D-915206E8D156",
                "rootCodeFunctionId": "96A88E6A-E343-4051-9674-7C58B4CC1A58",
                "sandbox": true,
                "type": "before_transaction",
                "authorizationApproved": true,
                "logs": [
                    {
                        "createdAt": "2021-10-15T03:48:14.771Z",
                        "level": "info",
                        "content": "{\"accountNumber\":\"10011001100\",\"dateTime\":\"2021-10-15T03:48:13.147Z\",\"centsAmount\":10100,\"currencyCode\":\"zar\",\"type\":\"card\",\"reference\":\"simulation\",\"card\":{\"id\":\"1010101\"},\"merchant\":{\"category\":{\"code\":\"7996\",\"key\":\"amusement_parks_carnivals\",\"name\":\"Amusement Parks/Carnivals\"},\"name\":\"uShaka Marine World\",\"city\":\"Durban\",\"country\":{\"code\":\"ZA\",\"alpha3\":\"ZAF\",\"name\":\"South Africa\"}}}"
                    }
                ],
                "smsCount": 0,
                "emailCount": 0,
                "pushNotificationCount": 0,
                "createdAt": "2021-10-15T03:48:14.184Z",
                "startedAt": "2021-10-15T03:48:14.183Z",
                "completedAt": "2021-10-15T03:48:14.899Z",
                "updatedAt": "2021-10-15T03:48:14.184Z",
                "Error": null
            },
            {
                "executionId": "688357B2-1F2B-49F7-A739-3D9DAF87CD84",
                "rootCodeFunctionId": "96A88E6A-E343-4051-9674-7C58B4CC1A58",
                "sandbox": true,
                "type": "after_transaction",
                "authorizationApproved": null,
                "logs": [
                    {
                        "createdAt": "2021-10-15T03:48:15.712Z",
                        "level": "info",
                        "content": "{\"accountNumber\":\"10011001100\",\"dateTime\":\"2021-10-15T03:48:14.920Z\",\"centsAmount\":10100,\"currencyCode\":\"zar\",\"type\":\"card\",\"reference\":\"simulation\",\"card\":{\"id\":\"1010101\"},\"merchant\":{\"category\":{\"code\":\"7996\",\"key\":\"amusement_parks_carnivals\",\"name\":\"Amusement Parks/Carnivals\"},\"name\":\"uShaka Marine World\",\"city\":\"Durban\",\"country\":{\"code\":\"ZA\",\"alpha3\":\"ZAF\",\"name\":\"South Africa\"}}}"
                    }
                ],
                "smsCount": 0,
                "emailCount": 0,
                "pushNotificationCount": 0,
                "createdAt": "2021-10-15T03:48:15.082Z",
                "startedAt": "2021-10-15T03:48:15.082Z",
                "completedAt": "2021-10-15T03:48:15.826Z",
                "updatedAt": "2021-10-15T03:48:15.082Z",
                "Error": null
            }
        ]
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
simulationcode body string required The javascript code that will be published to the card.

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Executions

GET /za/v1/cards/{cardkey}/code/executions Fetches the logs of the simulated as well as the actual transactions for the spesific card

Example Request:

GET https://openapi.investec.com/za/v1/cards/{cardkey}/code/executions HTTP/1.1
Host: openapi.investec.com
Content-Type: application/json
Authorization: Bearer V61dgYGhIFfr8NAkMwzJcZbeeiVZ
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/code/executions',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   }
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "executionItems": [
                {
                    "executionId": "5514C8A1-63BB-48FF-979A-F56660510FEC",
                    "rootCodeFunctionId": "96A88E6A-E343-4051-9674-7C58B4CC1A58",
                    "sandbox": true,
                    "type": "after_transaction",
                    "authorizationApproved": null,
                    "logs": [
                        {
                            "createdAt": "2021-10-14T12:55:29.814Z",
                            "level": "info",
                            "content": "{\"accountNumber\":\"10011001100\",\"dateTime\":\"2021-10-14T12:55:30.000Z\",\"centsAmount\":63943,\"currencyCode\":\"zar\",\"type\":\"card\",\"reference\":\"51387120\",\"card\":{\"id\":\"1010101\",\"display\":\"402167XXXXXX1111\"},\"merchant\":{\"category\":{\"code\":\"5912\",\"key\":\"drug_stores_and_pharmacies\",\"name\":\"Drug Stores and Pharmacies\"},\"name\":\"CORNERSTONE PHARMACY H\",\"city\":\"ROODEPOORT\",\"country\":{\"code\":\"ZA\",\"alpha3\":\"ZAF\",\"name\":\"South Africa\"}}}"
                        }
                    ],
                    "smsCount": 0,
                    "emailCount": 0,
                    "pushNotificationCount": 0,
                    "createdAt": "2021-10-14T12:55:29.118Z",
                    "startedAt": "2021-10-14T12:55:29.118Z",
                    "completedAt": "2021-10-14T12:55:29.858Z",
                    "updatedAt": "2021-10-14T12:55:29.118Z"
                },
                {
                    "executionId": "FECF32DE-77E6-4EEF-918E-E536B093336A",
                    "rootCodeFunctionId": "96A88E6A-E343-4051-9674-7C58B4CC1A58",
                    "sandbox": true,
                    "type": "before_transaction",
                    "authorizationApproved": null,
                    "logs": [
                        {
                            "createdAt": "2021-10-14T12:55:27.354Z",
                            "level": "info",
                            "content": "{\"accountNumber\":\"10011001100\",\"dateTime\":\"2021-10-14T12:55:28.000Z\",\"centsAmount\":63943,\"currencyCode\":\"zar\",\"type\":\"card\",\"reference\":\"51387120\",\"card\":{\"id\":\"1010101\",\"display\":\"402167XXXXXX1111\"},\"merchant\":{\"category\":{\"code\":\"5912\",\"key\":\"drug_stores_and_pharmacies\",\"name\":\"Drug Stores and Pharmacies\"},\"name\":\"CORNERSTONE PHARMACY H\",\"city\":\"ROODEPOORT\",\"country\":{\"code\":\"ZA\",\"alpha3\":\"ZAF\",\"name\":\"South Africa\"}}}"
                        }
                    ],
                    "smsCount": 0,
                    "emailCount": 0,
                    "pushNotificationCount": 0,
                    "createdAt": "2021-10-14T12:55:26.679Z",
                    "startedAt": "2021-10-14T12:55:26.679Z",
                    "completedAt": "2021-10-14T12:55:27.394Z",
                    "updatedAt": "2021-10-14T12:55:26.679Z"
                }
            ],
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Environment Variables

GET /za/v1/cards/{cardkey}/environmentvariables Gets the key value pairs of user defined variables securely stored against a spesific card

Example Request:

GET https://openapi.investec.com/za/v1/cards/{cardkey}/environmentvariables HTTP/1.1
Host: openapi.investec.com
Content-Type: application/json
Authorization: Bearer V61dgYGhIFfr8NAkMwzJcZbeeiVZ
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/environmentvariables',
   type: 'GET',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   }
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "variables": {},
            "createdAt": "2021-10-12T09:12:06.742Z",
            "updatedAt": "2021-10-12T09:12:06.742Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Replace Environment Variables

POST /za/v1/cards/{cardkey}/environmentvariables Sets the environment variables stored agains a spesific card.
Note: This replaces all variables and does not allow for patching

Example Request:

POST https://openapi.investec.com/za/v1/cards/{cardkey}/environmentvariables HTTP/1.1
Host: openapi.investec.com
Content-Type: application/json
Authorization: Bearer 8WqIBAVADiQxwtl8GvE1cAZAQhNK
Content-Length: 92

{
    "variables": {
        "test1": "value11",
        "test2": "value22"
        }
}
$.ajax({
   url: 'https://openapi.investec.com/za/v1/cards/{cardkey}/environmentvariables',
   type: 'POST',
   headers: {
      'Authorization': 'Bearer Ms9OsZkyrhBZd5yQJgfEtiDy4t2c'
   },
   data: {
    "variables": {
        "test1": "value11",
        "test2": "value22"
        }
    }   
   success: function (result) {
       console.log(JSON.stringify(result));
   }
});

Example Response

{
    "data": {
        "result": {
            "variables": {
                "test1": "value11",
                "test2": "value22"
            },
            "createdAt": "2021-10-15T05:18:09.891Z",
            "updatedAt": "2021-10-15T05:18:09.891Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

Parameters

Name In Type Required Description
cardkey query string required The CardKey obtained from the get cards call.
variables body string optional A json object representing the key/value pairs

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Countries

GET /za/v1/cards/countries Gets a reference set of countries

Example Request:

GET https://openapi.investec.com/za/v1/cards/countries HTTP/1.1
Host: openapi.investec.com
Authorization: Bearer S4gK4r6Llqvt0AwEOMron3AHkl6u
var settings = {
  "url": "https://openapi.investec.com/za/v1/cards/countries",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer S4gK4r6Llqvt0AwEOMron3AHkl6u"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
    "data": {
        "result": [
            {
                "Code": "ZA",
                "Name": "South Africa"
            },
            {
                "Code": "GB",
                "Name": "United Kingdom of Great Britain and Northern Ireland (the)"
            },
            {
                "Code": "undefined",
                "Name": "undefined"
            }
        ]
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Currencies

GET /za/v1/cards/currencies Gets a reference set of currencies

Example Request:

GET https://openapi.investec.com/za/v1/cards/currencies HTTP/1.1
Host: openapi.investec.com
Authorization: Bearer S4gK4r6Llqvt0AwEOMron3AHkl6u
var settings = {
  "url": "https://openapi.investec.com/za/v1/cards/currencies",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer S4gK4r6Llqvt0AwEOMron3AHkl6u"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
    "data": {
        "result": [
            {
                "Code": "ZAR",
                "Name": "South African Rand"
            },
            {
                "Code": "GBP",
                "Name": "British Pound"
            },
            {
                "Code": "USD",
                "Name": "United States Dollar"
            },
            {
                "Code": "EUR",
                "Name": "Euro"
            }
        ]
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute

Get Merchants

GET /za/v1/cards/merchants Get a reference set of merchant category codes and descriptions

Example Request:

GET https://openapi.investec.com/za/v1/cards/merchants HTTP/1.1
Host: openapi.investec.com
Authorization: Bearer S4gK4r6Llqvt0AwEOMron3AHkl6u
var settings = {
  "url": "https://openapi.investec.com/za/v1/cards/merchants",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer S4gK4r6Llqvt0AwEOMron3AHkl6u"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
    "data": {
        "result": [
            {
                "Code": "7623",
                "Name": "A/C, Refrigeration Repair"
            },
            {
                "Code": "8931",
                "Name": "Accounting/Bookkeeping Services"
            },
            {
                "Code": "7311",
                "Name": "Advertising Services"
            }
        ]
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

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
429 - Too Many Requests To many requests in quick succession, Retry the request.
500 - Internal Server Error The requested operation failed to execute