Mercantile Discount Bank API integration (Israel OpenBanking)

Deliverables checklist

• OpenAPI 3.1 / Swagger spec covering every integrated Mercantile endpoint
• Protocol & auth report: identification flow, OTP step-up, refresh chain, certificate pinning notes
• Runnable Python (FastAPI) and Node.js (NestJS) source for login, account, statement, FX and securities calls
• Replay test fixtures, Postman collection and CI smoke tests
• Compliance pack: Bank of Israel OpenBanking IL alignment, Israeli Privacy Protection Law notes, retention & logging guidance

API example: statement export

// POST /api/v1/mercantile/statement
// Auth: Bearer <ACCESS_TOKEN> (refreshed via /auth/refresh)
{
  "account_id": "MERC-ILS-12-345-6789",
  "from_date": "2026-01-01",
  "to_date":   "2026-03-31",
  "currency":  "ILS",
  "include":   ["debits","credits","standing_orders","fx"],
  "page_size": 200,
  "cursor":    null
}

// 200 OK
{
  "account_id": "MERC-ILS-12-345-6789",
  "balance": { "available": 18420.55, "current": 18420.55, "ccy": "ILS" },
  "items": [
    {"id":"tx_8821","date":"2026-03-28","amount":-249.90,
     "merchant":"Shufersal","mcc":"5411","channel":"card","fx":null},
    {"id":"tx_8820","date":"2026-03-27","amount":12000.00,
     "counterparty":"Salary - Acme Ltd","channel":"transfer","fx":null}
  ],
  "next_cursor": "eyJvZmZzZXQiOjIwMH0="
}

API example: securities portfolio

// GET /api/v1/mercantile/portfolio?account_id=...
// Returns positions across TASE and overseas custody
{
  "as_of": "2026-04-28T07:00:00+03:00",
  "positions": [
    {"isin":"IL0006046119","symbol":"DSCT","qty":120,
     "avg_cost":17.84,"market":21.05,"ccy":"ILS"},
    {"isin":"US0378331005","symbol":"AAPL","qty":18,
     "avg_cost":172.10,"market":188.30,"ccy":"USD"}
  ],
  "cash":[{"ccy":"ILS","amount":2410.00},
          {"ccy":"USD","amount":300.00}]
}

API example: webhook for Didi-style insights

// Outbound POST to your /webhooks/insight
{
  "event":"insight.double_charge",
  "account_id":"MERC-ILS-12-345-6789",
  "tx_ids":["tx_8788","tx_8789"],
  "merchant":"Cellcom",
  "amount":119.00,"ccy":"ILS",
  "confidence":0.94,
  "detected_at":"2026-04-27T19:42:11+03:00",
  "signature":"hmac-sha256:..."
}

Technical implementation notes

• Identification: ID number + password + OTP (SMS / push); biometric unlock on the device side. We expose a token endpoint that abstracts the multi-step exchange.
• Transport: TLS 1.3, certificate pinning on mobile clients; eIDAS-style signed requests for OpenBanking IL endpoints.
• Pagination: cursor-based for statement and securities; backfill respects the bank’s 18-month default window.
• Idempotency: every write call (transfer, FX, scheduled order) carries an Idempotency-Key; duplicates return the original response.
• Errors: typed error envelope (error.code, error.kind, error.retryable), with mapped reasons for OTP timeout, daily-limit, KYC-tier and currency-mismatch.

Data flow / architecture

Mercantile App / OpenBanking IL endpoints  →  our adapter (auth, signing, retry)  →  normalisation layer (ISO 20022-ish + ISIN/MCC)  →  your destination (ledger, CRM, data warehouse, BI). Consent records, request hashes and response checksums are written to an append-only audit log so every customer pull is reproducible.

• Ingestion: pull (cron) or webhook (push)
• Storage: encrypted at rest, customer-scoped keys
• Access: row-level scoped tokens per consent
• Output: REST, GraphQL, or warehouse export (BigQuery / Snowflake / Postgres)

About us

We are an independent technical service studio focused on App interface integration and authorised API integration. Our engineers come from Israeli and EU banks, payment gateways, and protocol-analysis backgrounds, and we ship end-to-end financial APIs under security and compliance constraints.

• Retail banking, brokerage, expense management and cross-border payments
• Bank of Israel OpenBanking IL / Berlin Group NextGenPSD2 mappings
• Custom Python / Node.js / Go SDKs and replay-based test harnesses
• Full pipeline: protocol analysis → build → validation → compliance
• Source code delivery from $300 — receive runnable API source code and full documentation; pay after delivery upon satisfaction
• Pay-per-call API billing — access our hosted API and pay only per call, no upfront cost; ideal for teams that prefer usage-based pricing

Contact

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

Contact page

We engage only with explicit customer authorisation or under documented authorised APIs. NDAs available on request.

Engagement workflow

1. Scope confirmation: target endpoints (login, statements, FX, securities, mortgage, insights) and consent model.
2. Protocol analysis & API design (2–5 business days).
3. Build and internal validation against replay fixtures (3–8 business days).
4. Docs, samples, OpenAPI spec, Postman collection, test cases (1–2 business days).
5. Typical first delivery: 5–15 business days; OpenBanking IL certificate enrolment may extend timelines.

FAQ

What do you need from me?

How long does delivery take?

How do you handle compliance?

Do you support Hebrew-language fields?