# Overview The Card API enables you to programmatically manage **Private Banking**, **Business & Commercial**, and **Corporate** banking cards. With this API, you can: - Get a list of your cards and card details - Create virtual cards - Get the code that is published to your cards - Save and publish new code to your cards - Run card simulations to test saved code - Check logs of simulated and real transactions on your cards - Manage environmental variables - Get a reference set of merchant codes - Get a reference set of currencies and countries and the associated codes. # Authentication

View Authentication details

- Investec API authentication uses **OAuth 2.0 client credentials** (`client_id` and `client_secret`), with the addition of an `x-api-key`. - Log in to Investec Online to obtain your `client_id` and `client_secret` and to generate your `x-api-key` with the scopes you require. **1. Get an access token** - To get an access token, you must exchange your `client_id`, `client_secret` and `x-api-key` for the token ```bash curl --location 'https://openapi.investec.com/identity/v2/oauth2/token' \ --header 'x-api-key: <>' \ --header 'Authorization: Basic <>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` **Headers explained:** - `x-api-key`: API key generated on Investec Online - `Authorization`: Base64-encoded `client_id:client_secret`. Take your `client_id` and `client_secret` and base64 encode them to provide a value for basic authorization. - `Content-Type`: Indicates the request body format **2. Use the token for all API requests** - Use the access token that you receive in all subsequent API requests - Access tokens are **valid for 30 minutes** and must be refreshed when expired ```bash curl --location 'https://openapi.investec.com/...' \ --header 'Authorization: Bearer <>' ``` **Notes** - Ensure your API key has the required scopes - you can set these when you create the key on Investec Online.

# Quickstarts

View Quickstart (cURL)

This Quickstart walks you through making your first successful API call to the Card API. By the end of this guide, you will: - Authenticate using OAuth 2.0 client credentials and your x-api-key - Call the Get Cards endpoint - Receive an HTTP 200 OK response with a list of cards linked to your profile **Before you start** Make sure you have the following: - An Investec profile that is activated for Investec Developer on Investec Online - You have your client-Id and client-secret from Investec Online and you have created an x-api-key with the **cards** scope. - An API client such as Postman, Curl or your own application code. **Step 1: Get an access token** The Card API uses OAuth 2.0 with the client credentials grant type. To get a bearer token, exchange your client_id, client_secret, and x-api-key for an access token. You must include: - HTTP Basic Auth using client_id:client_secret - Your x-api-key - grant_type= client_credentials **Token request** ```bash curl --location 'https://openapi.investec.com/identity/v2/oauth2/token' \ --header 'x-api-key: <>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic <>' \ --data-urlencode 'grant_type=client_credentials' ``` **What this does** - Authenticates your application - Returns a short-lived access token called a bearer token (valid for 30 minutes) - Confirms your credentials and API key are valid **Successful response example** ```json { "access_token": "qwertyuiop123456789", "token_type": "Bearer", "expires_in": 1799, "scope": "cards" } ``` **Step 2: Get your cards** Once you have your bearer token, call the Get Cards endpoint: GET/za/v1/cards **Request example** ```bash curl --location 'https://openapi.investec.com/za/v1/cards' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <>' ``` **What a successful call looks like** If everything is set up correctly, you will receive HTTP 200 OK and a JSON response containing the cards associated with your account. **Successful response example** ```json { "data": { "cards": [ { "CardKey": "1010101", "CardNumber": "402167XXXXXX1111", "IsProgrammable": true, "Status": "Active", "CardTypeCode": "VGC", "AccountNumber": "10011001100", "AccountId": "177778438355553632224" } ] }, "links": { "self": "https://openapi.investec.com/za/v1/cards" }, "meta": { "totalPages": 1 } } ``` **This confirms that:** - Your authentication flow is working - Your API key has the correct scope - You can successfully access Card API data. **Step 3: How to debug your first call** **Common issues on a first call** | Issue | Guidance | |-------|----------| | Token request fails | Ensure you are using HTTP Basic Auth and that the x-api-key is included | | 401 response | Check that your credentials are correct | | 403 response | Confirm your API key includes the `cards` scope |

View Quickstart (Postman)

[Open the collection in postman](https://www.postman.com/investec-open-api/programmable-banking/collection/hl5nm0u/investec-programmable-card) [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/bd209d71-564d-4379-b464-a8f75dd84db8?action=collection%2Ffork&collection-url=entityId%3Dbd209d71-564d-4379-b464-a8f75dd84db8%26entityType%3Dcollection%26workspaceId%3D905c2bab-81a1-4297-8b70-2456c776a7a0) The instructions below will guide you through the process of authenticating and getting your cards in Postman. Before you start, **fork** the appropriate collection, and work on the fork now available in My Workspace. **1. Authenticate** 1. Head over to the **Variables** tab to set your environment variables 2. Insert your client ID, client secret, and x-api-key. 3. Navigate to the Auth folder, and the POST Authentication query (URL: https://openapi.investec.com/identity/v2/oauth2/token). - Under **Authorization**: The Auth type is set to Basic Auth - Under **Headers**: Your headers include the x-api-key header which uses the key you just filled in. - Under **Body**: In the request body, the grant-type field has the value client_credentials 4. Hit send on the request. In response to your client id, secret and x-api-key, the endpoint will respond with a secure token, called a bearer token, and the period for which the token is valid (30 minutes). Navigate back to the Variables table and **paste your token into the token field**. **2. Get your cards** 1. Navigate to the Cards folder and the GET Cards 2. Hit send to make a call to the Cards API endpoint (no additional parameters need to be set) The JSON response will include the cards associated with your account, including information such as the cardKey, card number, status, and card type.

# Release notes

Description of API changes

To be added