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.