Alatau City Bank Business API integration (kz.jysan.business)

1. Daily statement sync into 1C / SAP

Context: Kazakhstan SMEs running 1C:Бухгалтерия or local SAP rollouts need every morning's bank movements posted into the GL. Data: /statements?from=…&to=… returning per-account JSON lines with currency, counterparty IBAN, narrative and document number. OpenData mapping: end-of-day account information service (AIS) pattern from the NPCK Open Banking System pilot, feeding the booking currency directly into the ERP.

2. Approval workflow for SME payments

Context: a CFO and accountant must both sign a vendor payout. Data: payment-initiation request, dual-signatory authorization tokens, SMS confirmation hash, and settlement webhook. OpenData mapping: a payment-initiation service (PIS) flow that reuses the in-app SMS-code authorization, exposed as POST /payments + POST /payments/{id}/sign with status callbacks.

3. TOLE QR reconciliation for retail chains

Context: cafés and delivery operators using Alatau City Bank TOLE need per-shift POS totals tied back to bank settlement. Data: QR order ID, terminal, gross, fee, settlement timestamp, and customer bonus / installment flags. OpenData mapping: a merchant-acquirer feed exposed over GET /tole/settlements, joined to the storefront's order ledger for shrinkage and loyalty analytics.

4. Multi-currency cash position for trading firms

Context: an importer in Almaty operating KZT, USD, EUR and RUB accounts wants intraday net positions. Data: balances and pending transfers across all five supported currencies, plus FX rate snapshots. OpenData mapping: aggregated AIS endpoint GET /accounts with currency facets, refreshed via signed webhook on every booking.

5. Compliance & audit pack generator

Context: a quarterly external audit requires statements, certificates and counterparty books for several legal entities. Data: signed PDF statements per account, payment authorization audit trail, and tariff plan history. OpenData mapping: a regulator-ready evidence bundle, packaged as a single ZIP through POST /audit-bundle for the auditor's secure portal.

Auth handshake (OAuth 2.0 + SMS step-up)

// Step 1 — token exchange under customer authorization
POST /api/v1/alatau-business/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<CONSENT_CODE>
&client_id=<PARTNER_ID>
&client_secret=<PARTNER_SECRET>
&redirect_uri=https://partner.example/cb

// 200 OK
{
  "access_token": "eyJhbGciOi…",
  "refresh_token": "rt_…",
  "expires_in": 1800,
  "scope": "accounts statements payments tole"
}

Statement query (paged, multi-currency)

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

{
  "account_iban": "KZ86JSAN…",
  "currency": "KZT",
  "from_date": "2026-04-01",
  "to_date":   "2026-04-30",
  "cursor":    null,
  "page_size": 200
}

// Response (truncated)
{
  "items": [
    {"id":"tx_91…","booked_at":"2026-04-02T09:14:00+05:00",
     "amount":"-184500.00","currency":"KZT",
     "counterparty":{"name":"TOO Astana Logistics","iban":"KZ58HSBK…"},
     "narrative":"Invoice 2026/041","status":"BOOKED"}
  ],
  "next_cursor": "c_4f9a…"
}

TOLE QR settlement webhook

POST https://partner.example/hooks/tole
X-OFL-Signature: sha256=… (HMAC over raw body)
Content-Type: application/json

{
  "event": "tole.settlement.posted",
  "merchant_id": "ACB-7741",
  "terminal_id": "TOLE-2210-A",
  "order_id": "QR-2026-05-03-000812",
  "gross": "12990.00",
  "fee":   "129.90",
  "net":   "12860.10",
  "currency": "KZT",
  "settled_at": "2026-05-03T11:02:14+05:00",
  "loyalty": {"bonus_kzt":"259.80","installment":false}
}

// Recommended handler: verify HMAC, ack 2xx within 5s,
// then enqueue for downstream POS reconciliation.

Regulatory alignment

Integrations are built under documented customer authorization and the Concept for the Development of Open API and Open Banking 2023–2025 approved by the National Bank of the Republic of Kazakhstan, jointly with the Agency for Regulation and Development of the Financial Market. Where applicable we follow the NPCK Open Banking System patterns piloted with second-tier banks (Bank RBK, Altyn Bank, Home Credit Bank, Bank CenterCredit, Otbasy Bank) for current-account information exchange.

Data protection & controls

Personal financial data is handled under the Republic of Kazakhstan Law on Personal Data and its Protection. Concrete controls we ship: short-lived access tokens, scope-bound consent records, immutable consent and access logs, encrypted credential vaults, IP allow-listing on partner gateways, and data-minimization on statement and TOLE feeds (we expose only the fields the use case actually needs).

Deliverables checklist

• OpenAPI / Swagger specification per module (accounts, statements, payments, TOLE)
• Protocol & auth flow report covering OAuth, SMS step-up and request signing
• Runnable reference implementation in Python (FastAPI) and Node.js (NestJS)
• Postman collection, contract tests and a Dockerized sandbox
• Compliance pack: consent template, retention policy, audit-log schema

Engagement workflow

1. Scope confirmation: which modules (e.g. statement only, or full PIS + TOLE)
2. Protocol analysis & API design (2–5 business days)
3. Build & internal validation against test accounts (3–8 business days)
4. Docs, samples and contract tests (1–2 business days)
5. Hand-off + 30-day support window for hot-fixes

About OpenFinance Lab

We are an independent technical studio focused on App interface integration, OpenData and OpenFinance. The team includes engineers with experience in payment gateways, SME ERP rollouts and protocol analysis across Central Asia and beyond. We follow Kazakhstan Open API guidance, EU OpenBanking patterns and EAEU privacy practice, and we ship end-to-end financial APIs under security and compliance constraints.

• SME banking, acquiring, payroll, and cross-border clearing
• Enterprise API gateways and security reviews
• Custom Python / Node.js / Go SDKs and test harnesses
• Source code delivery from $300 — runnable API source plus full documentation; pay after delivery upon satisfaction
• Pay-per-call API billing — access our hosted API and pay only per call, no upfront cost

Contact

For quotes or to submit your target app and requirements, open our contact page:

Contact page