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.
On this page
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.
| Language | Package | Runtime | Repository |
|---|---|---|---|
| TypeScript / JavaScript | fincode.ts | Node 18+, Bun, Deno, browsers | fincode.ts (single file) |
| Python | fincode | Python 3.9+ (standard library) | WilliamWangL/fincode-python |
| Java | io.github.williamwangl:fincode-java | JDK 11+ (JDK HttpClient) | WilliamWangL/fincode-java |
| Go | github.com/WilliamWangL/fincode-go | Go 1.22+ (standard library) | WilliamWangL/fincode-go |
| PHP | fincode/fincode-php | PHP 8.1+ (ext-curl) | WilliamWangL/fincode-php |
| AI coding tools (MCP) | fincode-mcp | Node 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.
# 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.0Quickstart
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.
| Option | Default | Description |
|---|---|---|
| apiKey / api_key | required | Key with the sk_ prefix, sent as Authorization: Bearer. |
| baseUrl / base_url | https://api.ecommica.com/v1 | Base URL including the version segment. |
| timeoutMs / timeout | 10000 ms | Per-attempt timeout; a timeout is retried like a network error. |
| maxRetries | 2 | Retries after the first attempt for 429, 502, 503, 504 and network errors. |
| fetch | globalThis.fetch | Custom 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.
| Method | REST 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_code | GET /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_slug | GET /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_format | GET /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.