Skip to content
FinCode

SDKs & client libraries

Official client libraries for Python, Java, Go and PHP, plus a zero-dependency TypeScript client — Bearer authentication, per-attempt timeouts, retries and typed errors built in.

This documentation covers API V1.

Client libraries

The API is plain HTTPS plus JSON, so any HTTP client works. These libraries only add what every integration eventually needs: Bearer authentication, per-attempt timeouts, retries with exponential backoff honouring Retry-After, and errors that carry the request id. Each client is an independent open-source repository with its own test suite and CI; the TypeScript one also ships as a single file with no dependencies.

LanguagePackageRuntimeRepository
TypeScript / JavaScriptfincode.tsNode 18+, Bun, Deno, browsersfincode.ts (single file)
PythonfincodePython 3.9+ (standard library)WilliamWangL/fincode-python
Javaio.github.williamwangl:fincode-javaJDK 11+ (JDK HttpClient)WilliamWangL/fincode-java
Gogithub.com/WilliamWangL/fincode-goGo 1.22+ (standard library)WilliamWangL/fincode-go
PHPfincode/fincode-phpPHP 8.1+ (ext-curl)WilliamWangL/fincode-php
AI coding tools (MCP)fincode-mcpNode 18+ (Cursor, Claude Code)fincode-mcp on npm

Install

TypeScript is a single file you copy into your project; the other languages install from GitHub with their native tooling; the MCP server runs from npx with no install step at all.

bash
# TypeScript / JavaScript - single file, no dependencies
curl -O https://fincode.ecommica.com/sdk/fincode.ts

# MCP server - configure it in your AI tool and let npx fetch it
npx -y fincode-mcp

# Python
pip install "git+https://github.com/WilliamWangL/fincode-python.git"

# Java - install the client into your local Maven repository
git clone https://github.com/WilliamWangL/fincode-java.git
cd fincode-java && mvn install

# Go
go get github.com/WilliamWangL/fincode-go

# PHP
composer config repositories.fincode vcs https://github.com/WilliamWangL/fincode-php
composer require fincode/fincode-php:^1.0

Quickstart

Construct one client per process and reuse it. Every call resolves to the { data, meta } envelope; meta.request_id identifies the call in support conversations.

import { FinCode } from "./fincode";

const fincode = new FinCode({ apiKey: process.env.FINCODE_API_KEY! });

const { data, meta } = await fincode.iban.validate("DE89370400440532013000");

console.log(data.valid);       // true
console.log(data.bank_code);   // "37040044"
console.log(meta.request_id);  // "req_1a2b3c4d"

Configuration

Only the API key is required. Timeouts and retries have production-friendly defaults, and every option can be overridden per client. Java exposes them through FinCodeClient.builder(), Go through fincode.With... options, and PHP through constructor arguments.

OptionDefaultDescription
apiKey / api_keyrequiredKey with the sk_ prefix, sent as Authorization: Bearer.
baseUrl / base_urlhttps://api.ecommica.com/v1Base URL including the version segment.
timeoutMs / timeout10000 msPer-attempt timeout; a timeout is retried like a network error.
maxRetries2Retries after the first attempt for 429, 502, 503, 504 and network errors.
fetchglobalThis.fetchCustom transport for tests or proxies (TypeScript only).

Method reference

Each method maps to one REST endpoint and resolves to the { data, meta } envelope. TypeScript uses camelCase, Python, Java and Go use the same camelCase names, and PHP exposes them as properties — the arguments are identical everywhere. For anything else, call request(method, path, query, body) directly.

MethodREST endpoint
fincode.iban.validate(iban)GET /v1/iban/validate?iban=
fincode.iban.lookup(iban)GET /v1/iban/{iban}
fincode.swift.get(code)GET /v1/swift/{code}
fincode.routing.get(number)GET /v1/routing/{number}
fincode.sortCode.get(code) / sort_codeGET /v1/sort-code/{code}
fincode.bsb.get(code)GET /v1/bsb/{code}
fincode.ifsc.get(code)GET /v1/ifsc/{code}
fincode.cnaps.get(code)GET /v1/cnaps/{code}
fincode.bin.get(bin)GET /v1/bin/{bin}
fincode.banks.list({ country, cursor, limit })GET /v1/banks
fincode.banks.search(q, { country, cursor, limit })GET /v1/banks/search?q=
fincode.banks.get(id)GET /v1/banks/{id}
fincode.banks.bySlug(slug) / by_slugGET /v1/banks/by-slug/{slug}
fincode.banks.branches(id, { q, city, cursor, limit })GET /v1/banks/{id}/branches
fincode.countries.list() / get(code)GET /v1/countries, /v1/countries/{code}
fincode.countries.ibanFormat(code) / iban_formatGET /v1/countries/{code}/iban-format
fincode.lookup.get(q)GET /v1/lookup?q=

Errors and retries

Non-2xx responses raise FinCodeError with the machine-readable code, the HTTP status and the request id. 429, 502, 503 and 504 — and network failures or timeouts — are retried with exponential backoff (honouring Retry-After) before the error surfaces. Other 4xx validation errors are never retried.

import { FinCodeError } from "./fincode";

try {
  await fincode.swift.get("NOPE");
} catch (error) {
  if (error instanceof FinCodeError) {
    console.error(error.code);       // "INVALID_SWIFT"
    console.error(error.status);     // 422
    console.error(error.requestId);  // "req_5e6f7a8b"
  }
  throw error;
}

Pagination

Directory collections are cursor paginated: pass meta.next_cursor back as cursor, and stop when it is null. Each client ships a helper that walks every page — iter_pages (Python), paginate (Java), Paginate (Go) and iterPages (PHP).

const banks = [];
let cursor: string | null | undefined;

do {
  const page = await fincode.banks.list({ country: "US", limit: 100, cursor });
  banks.push(...page.data);
  cursor = page.meta.next_cursor;
} while (cursor);

Request IDs

Every response — success or failure — carries a request id in meta.request_id or error.request_id. Log it next to your own correlation id: it links the call to the server-side log entry, which is what support needs to reproduce an issue.

Versioning and support

Every client targets API V1 (base path /v1) and is versioned in lockstep with it. Payloads are additive within V1 — new fields may appear at any time — so read by key instead of by position and ignore unknown fields. Breaking changes ship under a new version prefix, and each repository is tagged per release so you can pin a tag in your lockfile. File issues at the repository of the client you use.