tokenio-client

Production-grade TypeScript client for the Token.io Open Banking platform.

16 APIs — full TypeScript types — automatic OAuth2 token caching — retry with jitter — HMAC webhook verification — ESM + CJS

Installation

npm install tokenio-client
# or
pnpm add tokenio-client
# or
yarn add tokenio-client

Node.js ≥ 18 required (uses native fetch, crypto.subtle, crypto.getRandomValues).

Quick Start

import { TokenioClient } from "tokenio-client";

const client = new TokenioClient({
  clientId: process.env.TOKENIO_CLIENT_ID!,
  clientSecret: process.env.TOKENIO_CLIENT_SECRET!,
  // environment: "production",  // defaults to "sandbox"
});

// Initiate a payment
const payment = await client.payments.initiate({
  initiation: {
    bankId: "ob-modelo",
    amount: { value: "10.50", currency: "GBP" },
    creditor: { accountNumber: "12345678", sortCode: "040004", name: "Acme Ltd" },
    remittanceInformationPrimary: "Invoice #42",
    callbackUrl: "https://yourapp.com/payment/return",
    returnRefundAccount: true,
  },
});

// Handle the auth flow
if (payment.requiresRedirect()) {
  console.log("Redirect PSU to:", payment.redirectUrl);
} else if (payment.requiresEmbeddedAuth()) {
  console.log("Collect fields:", payment.embeddedAuthFields);
}

// Poll to final (prefer webhooks in production)
const final = await client.payments.pollUntilFinal(payment.id, {
  intervalMs: 2_000,
  timeoutMs: 60_000,
});
console.log("Payment status:", final.status);

API Coverage

| Namespace | Methods | |---|---| | client.payments | initiate, get, list, getWithTimeout, provideEmbeddedAuth, generateQRCode, pollUntilFinal | | client.vrp | createConsent, getConsent, listConsents, revokeConsent, listConsentPayments, createPayment, getPayment, listPayments, confirmFunds | | client.ais | listAccounts, getAccount, listBalances, getBalance, listTransactions, getTransaction, listStandingOrders, getStandingOrder | | client.banks | listV1, listV2, listCountries | | client.refunds | initiate, get, list | | client.payouts | initiate, get, list | | client.settlement | createAccount, listAccounts, getAccount, listTransactions, getTransaction, createRule, listRules, deleteRule | | client.transfers | redeem, get, list | | client.tokens | list, get, cancel | | client.tokenRequests | store, get, getResult, initiateBankAuth | | client.accountOnFile | create, get, delete | | client.subTpps | create, list, get, delete | | client.authKeys | submit, list, get, delete | | client.reports | listBankStatuses, getBankStatus | | client.webhooks | setConfig, getConfig, deleteConfig, parse, parseOrThrow, typed decoders | | client.verification | initiate |

Variable Recurring Payments (VRP)

// 1. Create consent
const consent = await client.vrp.createConsent({
  bankId: "ob-modelo",
  currency: "GBP",
  creditor: { accountNumber: "12345678", sortCode: "040004", name: "Acme" },
  maximumIndividualAmount: "500.00",
  periodicLimits: [
    { maximumAmount: "1000.00", periodType: "MONTH", periodAlignment: "CALENDAR" },
  ],
  callbackUrl: "https://yourapp.com/vrp/return",
});

// 2. Redirect PSU to authorize
if (consent.requiresRedirect()) {
  redirect(consent.redirectUrl!);
}

// 3. Confirm funds (optional)
const hasFunds = await client.vrp.confirmFunds(consent.id, "49.99");

// 4. Initiate payment against authorized consent
const payment = await client.vrp.createPayment({
  consentId: consent.id,
  amount: { value: "49.99", currency: "GBP" },
  remittanceInformationPrimary: "Monthly subscription",
});

Webhook Verification

const client = new TokenioClient({
  staticToken: "...",
  webhookSecret: process.env.TOKENIO_WEBHOOK_SECRET,
});

// Express handler
app.post("/webhooks/tokenio", express.raw({ type: "application/json" }), async (req, res) => {
  const sig = req.headers["x-token-signature"] as string;
  const result = await client.webhooks.parse(req.body, sig);

  if (!result.ok) {
    res.status(401).json({ error: result.error });
    return;
  }

  const { event } = result;

  switch (event.type) {
    case "payment.completed": {
      const data = client.webhooks.decodePaymentData(event);
      await handlePaymentCompleted(data.paymentId, data.status);
      break;
    }
    case "vrp.completed": {
      const data = client.webhooks.decodeVRPData(event);
      await handleVRPCompleted(data.vrpId, data.consentId);
      break;
    }
  }

  res.status(200).json({ received: true });
});

Error Handling

All methods throw TokenioError on failure:

import { TokenioError } from "tokenio-client";

try {
  const payment = await client.payments.get(paymentId);
} catch (err) {
  if (err instanceof TokenioError) {
    switch (err.code) {
      case "not_found":
        return null;
      case "rate_limit_exceeded":
        await sleep((err.retryAfter ?? 5) * 1000);
        return retry();
      case "unauthorized":
        throw new Error("Check your API credentials");
      default:
        logger.error("Token.io error", { code: err.code, status: err.status, traceId: err.requestId });
        throw err;
    }
  }
  throw err;
}

Error properties

| Property | Type | Description | |---|---|---| | code | ErrorCode | Machine-readable code | | message | string | Human-readable description | | status | number | HTTP status (0 for client-side) | | requestId | string? | X-Request-ID trace header | | retryAfter | number? | Retry-After header in seconds | | isRetryable | boolean | True for 429/5xx | | isNotFound | boolean | True for 404 | | isUnauthorized | boolean | True for 401 | | isRateLimited | boolean | True for 429 |

Configuration

new TokenioClient({
  clientId: "...",          // OAuth2 client ID
  clientSecret: "...",      // OAuth2 client secret
  staticToken: "...",       // Bypass OAuth2 (tests only)
  environment: "sandbox",   // "sandbox" | "production"
  baseUrl: "...",           // Override API URL
  timeoutMs: 30_000,        // Per-request timeout
  maxRetries: 3,            // Max retries on 5xx/429
  retryWaitMinMs: 500,      // Min retry backoff
  retryWaitMaxMs: 5_000,    // Max retry backoff
  webhookSecret: "...",     // HMAC webhook secret
  logger: myLogger,         // Custom logger
})

Telemetry

Attach a global handler to receive telemetry events:

(globalThis as any).__tokenioTelemetry = (event) => {
  metrics.histogram("tokenio.request.duration", event.duration, {
    method: event.method,
    path: event.path,
    status: String(event.status),
  });
};

Event fields: event, method, path, status, duration (ms), timestamp.

Testing

import { vi } from "vitest";
import { TokenioClient, clearTokenCache } from "tokenio-client";

beforeEach(() => {
  clearTokenCache();
  vi.stubGlobal("fetch", vi.fn(async () =>
    new Response(JSON.stringify({
      payment: { id: "pm:test", status: "INITIATION_COMPLETED" }
    }), { status: 200, headers: { "content-type": "application/json" } })
  ));
});

it("gets a payment", async () => {
  const client = new TokenioClient({ staticToken: "test-token" });
  const payment = await client.payments.get("pm:test");
  expect(payment.id).toBe("pm:test");
  expect(payment.isFinal()).toBe(true);
});

License

MIT — see LICENSE.