TOM Bank Hadi API integration services (OpenBanking Türkiye)

Deliverables checklist

• OpenAPI 3.1 / Swagger specification for every TOM Bank Hadi endpoint we expose
• Protocol & auth flow report (mTLS pinning, device-id, OTP, biometric step-up, refresh tokens)
• Runnable source for login, statement, transfer and Hadi Black card APIs (Python & Node.js)
• Postman collection, automated tests and a small sandbox harness
• Compliance brief: BDDK IT, KVKK (Turkish data protection), BKM ÖHVPS 2.0 mapping, retention policy
• Migration guide if you later want to plug into the official BKM/CBRT open banking gateway

Why teams pick this stack

Turkish banking apps look simple on the surface but carry a heavy authentication chain — KKB-derived device binding, MASAK anti-money-laundering checks, multiple OTP channels, and BKM-issued certificates for inter-bank routing. We have already mapped these for participation banks (faizsiz bankacılık) and extend the same playbook to TOM Bank Hadi so engineering teams do not spend a quarter reinventing it.

Output is a clean API gateway your existing ERP, accounting tool or CRM can call. We also add per-user consent records aligned with the BKM Open Banking Gateway (GATE) certification programme so the same code path can later be re-pointed at official channels with minimal rework.

API example: authenticated login (pseudocode)

// Step 1: bind device + initiate session (mirrors app behaviour)
POST /api/v1/tom-hadi/auth/login
Content-Type: application/json
X-Device-Id: <hashed device fingerprint>
User-Agent: TomHadi-Integration/1.0

{
  "msisdn": "+9053xxxxxxxx",
  "password": "<client-encrypted>",
  "otp_channel": "sms"
}

// Step 2: confirm OTP, receive short-lived access + refresh token
POST /api/v1/tom-hadi/auth/otp
{ "otp": "######", "session_id": "..." }

→ 200 OK
{
  "access_token": "...",          // 15 min TTL
  "refresh_token": "...",         // rotating, mTLS-bound
  "consent_id": "...",            // stored against BDDK consent record
  "scopes": ["accounts.read","cards.read","transfers.write"]
}

API example: statement export (pseudocode)

POST /api/v1/tom-hadi/statement
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

{
  "account_id": "TR98-0021-...-001",
  "from_date": "2026-04-01",
  "to_date":   "2026-04-30",
  "channels":  ["EFT","FAST","CARD","BILL"],
  "format":    "json",            // or "csv","xlsx","pdf"
  "currency":  "TRY"
}

Response (truncated):
{
  "page": 1,
  "next_cursor": "eyJvZmZzZXQiOjEwMH0",
  "items": [{
    "id": "txn_018f...",
    "ts": "2026-04-12T09:14:22+03:00",
    "amount": -245.90,
    "currency": "TRY",
    "channel": "FAST",
    "counterparty": { "iban": "TR..", "name": "A101 Yeni Mağaz." },
    "category": "groceries",
    "cashback": { "amount": 24.59, "bucket": "hadi_black_grocery" }
  }]
}

API example: transfer webhook (pseudocode)

// Webhook delivered to your endpoint when a 24/7 EFT/Havale settles
POST https://your-app.example/webhooks/tom-hadi
X-OFL-Signature: sha256=...
Idempotency-Key: 8f...

{
  "event": "transfer.settled",
  "transfer_id": "tr_01J7...",
  "from_account": "TR98-0021-...-001",
  "to_account":   "TR12-0067-...-902",
  "amount": 1500.00,
  "currency": "TRY",
  "channel": "FAST",
  "settled_at": "2026-04-30T22:11:04+03:00",
  "consent_id": "..."
}

// Errors follow RFC 7807 Problem+JSON
{ "type": "https://errors.openfinance-lab.com/tom-hadi/limit-exceeded",
  "title": "Daily FAST limit exceeded",
  "status": 422,
  "detail": "Account capped at 30,000 TRY/day for FAST." }

Compliance & privacy

Every TOM Bank Hadi integration we ship is anchored to Turkish law. The CBRT published the "Guideline on Data Sharing Services in Payment Services" on 30 December 2022, defining API standards and security measures for open banking. Banks must complete BKM ÖHVPS 2.0 certification through the BKM GATE server, with the compliance window most recently extended to 31 December 2025. The Banking Regulation and Supervision Agency (BDDK) supervises IT and operational risk, while KVKK (Law No. 6698) governs personal data. Cross-border deployments additionally align with EU PSD2/PSD3 expectations and GDPR.

On top of this, Law No. 7545 (effective March 2025) layered new cybersecurity duties for regulated institutions. We map each TOM Bank Hadi endpoint to these regimes: explicit consent capture, scoped tokens, audit logs that survive 10 years, MASAK transaction screening hooks, and data-minimisation defaults so screen-derived fields never leak beyond the agreed scope.

Typical modules

• Account login, OTP, biometric step-up & refresh-token rotation
• Balance, transaction and statement export (JSON/CSV/XLSX/PDF)
• Hadi Black card statements, cashback ledger, cash advance utilisation
• EFT / FAST / Havale transfer initiation with idempotency keys
• Term participation accounts, Mega Daily Account, FX and gold trades
• Bill payment instructions, A101 cash in/out events, consent & audit log API

About us

OpenFinance Lab is an independent studio focused on fintech and open-data API integration. Our team includes engineers from banks, payment gateways, mobile protocol analysis, and cloud platforms. We have shipped end-to-end integrations on participation banks, conventional banks, BNPL, and e-money wallets across Türkiye, the EU and the Gulf, and we know how BDDK IT, BKM ÖHVPS 2.0, KVKK, PSD2 and GDPR interact in practice.

• Payments, digital banking, participation finance and cross-border clearing
• Enterprise API gateways, mTLS, device binding and security reviews
• Custom Python / Node.js / Go SDKs and test harnesses
• Full pipeline: protocol analysis → build → validation → compliance review
• Source code delivery from $300 — runnable code and full documentation; pay after delivery upon satisfaction
• Pay-per-call API billing — call our hosted endpoints, no upfront fee, ideal for usage-based pricing

Contact

For quotes or to submit your TOM Bank Hadi requirements (consent scope, regions, expected call volume), open our contact page:

Contact page

Working under NDA is standard. We can sign Turkish-language NDAs and accept payment in TRY, USD or EUR.

Engagement workflow

1. Scope confirmation: consent scope, target endpoints (login, transactions, Hadi Black, term accounts, transfers).
2. Protocol analysis & API design (2–5 business days, complexity-dependent).
3. Build & internal validation against a test Hadi account (3–8 business days).
4. Documentation, samples and test cases (1–2 business days).
5. Typical first delivery: 5–15 business days; BDDK-aligned audits or BKM GATE alignment may extend timelines.

FAQ

Which TOM Bank Hadi data can you actually expose through an API?

Is this compliant with Turkish open banking and BDDK rules?

How long does delivery take?

Source code or hosted API — which engagement model fits best?