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
andafterTransaction
- 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.
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.
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
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 |