💳How to use the programmable card API

The Programmable Card API allows you to access programmable card functionality via an API. The features available via the online IDE are also available via the API.

Using Postman

If you’re new to APIs and want to get familiar with using the endpoints, we recommend you create a Postman account (it's free) and use the Postman collections provided to test things out.

Investec Programmable Banking Postman Collection

Once you’ve signed up for an account, head over to these collections and make sure you fork the Programmable Card API collection.

Before querying the API, ensure that you have authenticated: How to authenticate against the Investec API

1. Get your cards with Postman

This will return all the cards associated with your account.

1. Navigate to the Card folder and the GET Cards query.

2. Hit Send to make a call to the API endpoint.

https://openapi.investec.com/za/v1/cards

1. Take note of the cardkey value that is returned. When deploying custom code to your card, you will need to use this variable.

💳 GET Cards example response

{
   "data": {
       "cards": [
           {
               "CardKey": "1234567",
               "CardNumber": "123456XXXXXX1234",
               "IsProgrammable": true,
               "Status": "Active",
               "CardTypeCode": "VBC",
               "AccountNumber": "11111111111",
               "AccountId": "1111111111222222222233333",
               "EmbossedName": "T TEST"
           },
       ]
   },
   "links": {
       "self": null
   },
   "meta": {
       "totalPages": 1
   }
}

2. Update function code on your card with Postman

This will save code your card without publishing it.

1. Navigate to the Card folder and the POST Update Function code query.

2. Insert your cardkey variable from the previous query under the Params tab on the query page.

3. Replace the body of the request with the code you would like. Below is an example for you to use. The snippet declines card purchases that are made in bakeries (using a specified merchant code) transactions and that are over the R50 (or 5000 cents) limit.

```
{
    "code": "const beforeTransaction = async (authorization) => { if (authorization.merchant.category.key === 'bakeries') { return authorization.centsAmount < 5000 } return true}"
}
```

1. Hit Send to make a call to the API endpoint.

https://openapi.investec.com/za/v1/cards/:cardkey/code

1. The codeID returned from the response is uniquely generated every time you post/save code to your card, which you will need for your next API call.

↪️ Update Function Code example response

{
   "data": {
       "result": {
           "codeId": "d11bd10e-7cba-1f11-a111-c11e11a1e111",
           "code": "const beforeTransaction = async (authorization) => { if (authorization.merchant.category.key === 'bakeries') { return authorization.centsAmount < 5000 } return true}",
           "createdAt": "2023-04-05T09:33:11.925Z",
           "updatedAt": "2023-04-05T09:33:11.925Z",
           "publishedAt": "2023-04-05T09:33:11.925Z",
           "error": null
       }
   },
   "links": {
       "self": null
   },
   "meta": {
       "totalPages": 1
   }
}

3. Publish code to your card using Postman

This will publish and activate the code you have saved to your card.

1. Navigate to the Card folder and the POST Publish Saved Code query.

2. Insert your cardkey variable from the previous query under the Params tab on the query page.

3. Replace the body of the code with the following as seen below. Make sure you use the codeID from your previous query.

{
   "codeid": "d11bd10e-7cba-1f11-a111-c11e11a1e111",
   "code": ""
}

1. Hit Send to make a call to the API

https://openapi.investec.com/za/v1/cards/:cardkey/publish

👨‍💻 Publish Saved Code example response

{
    "data": {
        "result": {
            "codeId": "d11bd10e-7cba-1f11-a111-c11e11a1e111",
            "code": "const beforeTransaction = async (authorization) => { if (authorization.merchant.category.key === 'bakeries') { return authorization.centsAmount < 5000 } return true}",
            "createdAt": "2023-04-05T12:36:43.209Z",
            "updatedAt": "2023-04-05T12:36:43.209Z",
            "publishedAt": "2023-04-05T12:36:56.272Z",
            "error": null
        }
    },
    "links": {
        "self": null
    },
    "meta": {
        "totalPages": 1
    }
}

4. Simulate a transaction using Postman

This will run a simulation of your code for testing before you publish code.

1. Navigate to the Card folder and the POST Execute Function Code query.

2. Insert your cardkey variable from the previous query under the Params tab on the query page.

3. Replace the body of the code with the code you want to simulate. The below code snippet simulates and declines card purchases that are made in bakeries (using a specified merchant code) transactions and that are over the R50 (or 5000 cents) limit.

{
    "simulationcode": "const beforeTransaction = async (authorization) => { if (authorization.merchant.category.key === 'bakeries') { return authorization.centsAmount < 5000 } return true }",
    "centsAmount": "5050",
    "currencyCode": "zar",
    "merchantCode": 5462,
    "merchantName": "The Coders Bakery",
    "merchantCity": "Cape Town",
    "countryCode": "ZA"
}

1. Hit Send to make a call to the API

https://openapi.investec.com/za/v1/cards/:cardkey/code/execute

🤑 Simulate a transaction example response

cURL code snippets

Get cards

curl --location 'https://openapi.investec.com/za/v1/cards' \
--header 'Accept: application/json'

Update function code

curl --location 'https://openapi.investec.com/za/v1/cards//code' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--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};"
}'

Publish code

curl --location 'https://openapi.investec.com/za/v1/cards//publish' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "codeid": "2d73122b-8beb-4faa-8256-0228ec811f72",
    "code": " "
}'

Simulate a transaction

curl --location 'https://openapi.investec.com/za/v1/cards//code/execute' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "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,
    "merchantName": "USkaka",
    "merchantCity": "Durban",
    "countryCode": "ZA"
}'