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 it has been processed using the afterTransaction() function. for instance: post your transaction to an app you built
Call external 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 - 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)

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

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:

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

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

2021-10-01

Fix: The runningBalance on transactions shows (-) if it is a negative balance Get Account Transactions

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:

Obtain a list of cards
Get code saved to the card
Get code published to the card
Save code to the card
Publish saved code
Execute (Simulation)
Get all executions (Simulations and Actual)
Get environment variables
Overwrite environment variables
Get countries
Get currencies
Get merchant categories

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