investec-api

investec-api

An NPM module to interact with Investec's Open API

Usage

(This module has types, so intellisense is your friend).

Set up client

import { Client } from "investec-api";
const client = await Client.create(id, secret, apiKey, baseUrl?);

Param	Required	Description
id	true	Your API key ID issued by Investec.
secret	true	The corresponding API key secret.
apiKey	true	The corresponding API key.
baseUrl	false	Optional base URL that will be used when interacting with the Investec Open API. If none is passed, then "https://openapi.investec.com" is used.

This creates an access token that the client will use to interact with the API.

If you start to get errors about the token no longer being valid, simply call:

await client.authenticate();

Response validation

Every API response is checked against a zod schema derived from Investec's OpenAPI specs, since the spec and the live API have been known to drift.

const client = await Client.create(id, secret, apiKey, baseUrl, {
  validation: "warn", // "warn" (default) | "strict" | "off"
  onValidationWarning: (endpoint, issues) => {
    // default logs to console.warn
  },
});

• warn (default): mismatches are reported (endpoint + field path) and the data is returned as-is.
• strict: mismatches throw an InvestecValidationError.
• off: no validation.

Unknown extra fields never warn; only missing or wrongly-typed known fields do.

Accounts (Private Banking)

List accounts

const accounts = await client.getAccounts();

This returns an array of Account objects.

Breaking change: getAccounts no longer takes a realm. Business (CIB) accounts are a separate domain with their own shape and endpoints; use client.getBusinessAccounts() instead.

Account functions

On an Account object, you can:

Get Balance

const balance = await account.getBalance();

Get transactions

const transactions = await account.getTransactions({
  fromDate: string;
  toDate: string;
  transactionType: string;
  includePending: boolean;
});

Get pending transactions

const pendingTransactions = await account.getPendingTransactions();

Get documents

const documents = await account.getDocuments("2023-04-01", "2023-06-01");

Get document (PDF)

const pdf = await account.getDocument(documentType, documentDate); // Buffer

Transfer

const transfer = await account.transfer(
  [
    {
      account: Account;
      amount: number;
      myReference: string;
      theirReference: string;
    }
  ],
  profileId? // optional; defaults to the account's own profileId
);

Payments

const payment = await account.pay([
  {
    beneficiary: InvestecBeneficiary;
    myReference: string;
    theirReference: string;
    amount: number;
    // optional, for payments requiring authorisation
    // (ids come from client.getAuthorisationSetupDetails):
    authorisation?: { aId?: string; bId?: string; periodId?: string };
    fasterPayment?: boolean;
   }
]);

Beneficiaries

List beneficiaries

const beneficiaries = await client.getBeneficiaries();

List beneficiary categories

const beneficiaryCategories = await client.getBeneficiaryCategories(profileId?);

The live API requires a profileId (the spec doesn't document it); when omitted, the default profile is looked up and used.

Profiles

List profiles

const profiles = await client.getProfiles();

List profile accounts

const accounts = await client.getProfileAccounts(profileId);

Get authorisation setup details

const details = await client.getAuthorisationSetupDetails(profileId, accountId);

List profile beneficiaries

const beneficiaries = await client.getProfileBeneficiaries(profileId, accountId);

Business Banking (CIB)

List business accounts

const accounts = await client.getBusinessAccounts(); // BusinessAccount[]

Business account transactions

const transactions = await businessAccount.getTransactions({
  fromDate?: string;
  toDate?: string;
  page?: number;
});

Initiate payment

Takes a PAIN.001 (ISO 20022) remittance payload and an idempotency key.

const { paymentId } = await client.initiateBusinessPayment(
  {
    format: "XMLPain NEWSTDD",
    payload: {
      body: {
        content: base64EncodedPain001File,
        contentEncoding: "base64",
      },
    },
  },
  idempotencyKey
);

Payment status

const status = await client.getBusinessPaymentStatus(paymentId);

List companies

const companies = await client.getBusinessCompanies();

Cards

List cards

const cards = await client.getCards();

Create virtual card

const virtualCard = await Card.createVirtualCard(client, {
  accountNumber: string;
  embossName: string;
  embossName2?: string;
});

Get Card countries

const countries = await Card.getCountries();

Get Card currencies

const countries = await Card.getCurrencies();

Get Card merchants

const countries = await Card.getMerchants();

Card functions

On a Card object, you can:

Get card detail

const detail = await card.getDetail();

Get card detail with sensitive information

Requires an RSA (2048) key pair; the API encrypts card number, expiry date and CVV with your public key (returned in ExtendedDetails).

const detail = await card.getSensitiveDetail({
  keyId: number;
  identifier: string;
  appName: string;
  modulus: string;
  exponent: string;
});

Toggle programmable feature

const enabled = await card.toggleProgrammableFeature(true | false);

Get Saved code

const savedCode = await card.getSavedCode();

Get published code

const publishedCode = await card.getPublishedCode();

Update saved code

const updatedCode = await card.updateSavedCode(code: string);

Publish saved code

const publishedCode = await card.publishSavedCode(codeId: string, code?: string);

Simulate functions execution

const execution = await card.simulateFunctionExecution({
  code: string;
  centsAmount: string;
  currencyCode: string;
  merchantCode: number;
  merchantCity: string;
  countryCode: string;
});

Get previous executions

const executions = await card.getExecutions();

List environment variables

const variables = await card.getEnvironmentVariables();

Update environment variables

const variables = await card.updateEnvironmentVariables({...});

Investec Programmable Banking Docs

You can read more about Investec's Programmable Banking here.

This library is merely an interface to the above.