API Changelog
Complete changelog for Kang Open Banking API. Track new endpoints, breaking changes, deprecations, and version history.
Version History
All API changes are documented here within 48 hours of deployment, as required by ORDER P7. Newest first. Breaking changes are flagged. Subscribe via developers@kangopenbanking.com.
v4.53.0 — 2026-07-15
Type: minor · Breaking: no
Card Issuing v3 — Nium becomes the default virtual, digital and physical card issuer with Kora as automatic fallback. Adds cards-v3 (CRUD + lifecycle), cards-v3-reveal (step-up MFA PAN/CVV reveal, PCI SAQ-A compliant), and cards-v3-webhook (HMAC-verified normalized ingestion). Consumer PWA rebuilt with Nium-first UX, form-factor selection, physical card order & tracking. Homepage adds a dedicated Card Issuing section. Additive only — legacy virtual-cards and virtual-cards-v2 endpoints remain read-only for one minor version (Standing Orders 1, 2, 4, 6).
- New enum value on card_issuer_provider: 'nium' (Kora retained as fallback).
- New card_form_factor enum: 'virtual' | 'digital' | 'physical' with nium_card_id + wallet_tokens columns on virtual_cards.
- New card_shipments table with card_shipment_status enum for physical card tracking (manufacturing → shipped → delivered).
- Edge functions: cards-v3 (issue/list/freeze/unfreeze/terminate), cards-v3-reveal (sca_challenges verified), cards-v3-webhook (Nium + Kora signature verification, idempotent on provider+event_id).
v4.52.1 — 2026-07-01
Type: patch · Breaking: no
Nium Virtual Accounts spec regeneration. Static public/openapi.json and public/openapi.yaml now expose account_kind ('virtual' | 'global'), IBAN/BIC/routing_code, provider='nium', destination_currency='XAF', and the full 17-currency enum on GatewayVirtualAccount. Legacy `bvn` request field is now explicitly deprecated with backward-compatible acceptance. Additive only — no operationIds, existing required[], or enums removed (Standing Orders 1, 2, 4, 6).
- GatewayVirtualAccount schema: adds account_kind, iban, bic, routing_code, beneficiary_name, provider, destination_currency, mode, and expanded currency enum.
- POST /v1/gateway/virtual-accounts: request body adds account_kind, beneficiary_name, pop_code; `bvn` marked deprecated (accepted, stripped, echoed in meta.warnings[]).
- GET /v1/gateway/virtual-accounts: new optional account_kind query filter.
- nium-webhook edge function: adds handling for account.status_updated / account.suspended / account.closed events with idempotent nium_global_accounts.status writes.
v4.52.0 — 2026-06-29
Type: minor · Breaking: no
Nium integration expansion: 17 supported currencies (default destination XAF), new endpoints for Beneficiaries, Payouts, Conversions, and Requests for Information (RFI), plus Virtual vs Global account_kind. Additive only — no operationIds, schemas, security schemes, parameters, enums, or required arrays changed (Standing Orders 1, 2, 4).
- Global accounts: account_kind ('virtual' | 'global') and 17 currencies (USD, EUR, GBP, AUD, CAD, SGD, AED, JPY, INR, ZAR, HKD, CHF, NZD, SEK, NOK, DKK, CNY) with XAF as the locked destination.
- New endpoints: POST/GET /v1/gateway/nium/beneficiaries, /v1/gateway/nium/payouts, /v1/gateway/nium/conversions, /v1/gateway/nium/rfi.
- Webhook events extended: nium.payout.*, nium.conversion.*, nium.rfi.* (idempotent on event_id).
- SDKs (Node 1.2.0, Python 0.1.0, PHP 1.2.0): new BeneficiariesResource, PayoutsResource, ConversionsResource, RfiResource under the global accounts namespace.
v4.51.6 — 2026-06-29
Type: patch · Breaking: no
Documented charge.succeeded and account.updated webhook events with deterministic signed test fixtures, and shipped runnable OAuth 2.0 + PKCE authorization_code samples for Node and Python. Additive only — no operationIds, schemas, security schemes, parameters, enums, or required arrays changed (Standing Orders 1, 2, 4).
- openapi.json / openapi.yaml: webhooks{} gains charge.succeeded and account.updated entries with example payloads. x-webhook-events list extended where missing.
- public/sdk-downloads/webhook-fixtures/: signed sandbox payloads + headers + tampered counterexample for receiver / SDK verification.
- packages/sdk-node/examples/pkce-auth-code.ts and packages/sdk-python/examples/pkce_auth_code.py: runnable end-to-end PKCE samples (public client, no client_secret).
- .github/workflows/webhook-signature-smoke.yml: nightly + on-push verification that Node, Python, and PHP SDK verifiers accept canonical fixtures and reject tampered / wrong-secret payloads.
v4.51.5 — 2026-06-25
Type: patch · Breaking: no
Phase 5 consistency & hygiene. Every operation response in the production and sandbox specs now advertises X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset, and every 429 response advertises Retry-After. Money-amount string schemas were audited for the zero-decimal currency pattern (^[0-9]{1,15}$); no regressions found. Additive metadata only (Standing Orders 1, 2, 4).
- openapi.json + openapi.yaml: 3,852 rate-limit header refs added across 7,744 responses; 50 Retry-After refs added to 429 responses.
- Sandbox spec mirrors the same headers so integration tests see identical rate-limit advertising in both environments.
- Money-amount audit (Balance, GatewayCharge, GatewayFeeEstimate, money-bearing request/response schemas) confirms all amount-typed string fields keep the canonical zero-decimal pattern; flagged non-amount fields (currency, channel, balance_type) are report-only.
- Phase 5 hardening script (scripts/phase5-consistency-hygiene.mjs) and closeout (PHASE_5_CONSISTENCY_HYGIENE_CLOSEOUT.md) published at repo root.
v4.51.4 — 2026-06-25
Type: patch · Breaking: no
Phase 4 PCI / Card Data Boundary. Operations and schemas that touch cardholder data now carry an explicit x-pci-scope flag so integrators and auditors can see, at the contract level, which surfaces are in PCI DSS scope and which are not. Additive metadata only — no paths, operationIds, schemas, security schemes, parameters, enums, or required-arrays changed (Standing Orders 1, 2, 4).
- Root x-pci-scope-legend added: none | masked_pan_only | cardholder_data | sensitive_auth_data.
- POST /v1/payouts/push-to-card (payoutPushToCard) flagged x-pci-scope: cardholder_data with note documenting that PAN is forwarded to Kora and not persisted in KOB.
- POST /v1/issuing/cards/{id}/reveal (revealVirtualCard) flagged x-pci-scope: cardholder_data with note documenting that PAN/CVV originate from the Kora vault and are returned in-memory only.
- VirtualCard.card_number_masked flagged x-pci-scope: masked_pan_only with PCI DSS req 3.3 citation (first 6 / last 4).
v4.51.3 — 2026-06-25
Type: patch · Breaking: no
Phase 3 scope containment. Every tag in the public OpenAPI spec now carries an x-maturity flag (ga | preview | experimental) and an x-maturity-note so integrators can tell at a glance which surfaces are production-track versus sandbox/pilot versus experimental. Additive metadata only — no paths, operationIds, schemas, security schemes, parameters, or enum values changed (Standing Orders 1, 2, 4).
- openapi.json + openapi.yaml: x-maturity and x-maturity-note added to all tags; ga covers Monitoring, OAuth, Authentication, Security, Consent Management, AISP, PISP, KYC & Compliance, Webhooks, Admin, Communications, Directory, Bank Directory, Platform, Specification, Developer, Sandbox, Provider Webhooks (Inbound), Mobile Money, Payments, Payment Gateway, Merchants, Merchant Onboarding, Statements, Banking Operations.
- preview covers Loans, Savings, Credit Scoring, CrediQ, PostiQ, Virtual Cards, Issuing, Ledger, Interbank, ISO 20022 Standards, Bank Connectors, Pay by Bank, Settlement, Payment Facilitation, Institution, Consumer Tools, Overdraft, Approval Workflows, Operational Controls, Gateway, Budgeting, Certificates, WooCommerce.
- experimental covers Agents, USSD, QR & Offline, CEMAC Remittance.
- Root-level x-maturity-legend added so tooling can render the maturity scale without hard-coding it.
v4.51.2 — 2026-06-25
Type: patch · Breaking: no
Phase 2 authentication reality check. Developer-portal auth pages, FAPI conformance statement, and token-lifecycle reference hedged to match what the code actually implements. No spec paths, operationIds, schemas, security schemes, or enum values changed (Standing Orders 1, 2, 4).
- AuthFapi page: 'certified to FAPI 1.0 Advanced' -> 'targets FAPI 1.0 Advanced; certification in progress', with an explicit implementation-maturity notice and a Status column on client-auth types.
- ComplianceFapi statement: PAR marked partial (available, not yet mandatory), private_key_jwt marked not_supported (planned), refresh-token rotation + reuse detection marked not_supported (roadmap), mTLS marked partial (infrastructure-dependent), DCR marked partial (SSA signature verified in production only).
- AuthOAuth2 quickstart: PAR wording softened from 'must' to 'should'; refresh-token reuse-detection callout rewritten as a roadmap notice.
- token-lifecycle.md: access-token TTL corrected to 3600s; refresh-token rotation reframed as roadmap; reuse-detection section reframed as roadmap.
v4.51.1 — 2026-06-25
Type: patch · Breaking: no
Phase 1 trust & truthfulness pass. Public OpenAPI info.description rewritten to remove unverified compliance claims ("COBAC & BEAC compliant", "100/100", "Guardian/Standing Order" narration). Regulatory framing on public pages hedged to "designed for alignment; licensing in progress". No paths, operationIds, schemas, security schemes, or examples changed.
- openapi.json + openapi.yaml info.description rewritten as a factual paragraph; original prose archived to internal CHANGELOG_INTERNAL.md (not served).
- Landing page, About page, ForDevelopers page, and Compliance page hedged to remove uncertified "compliant" and "certified" claims.
- Added top-of-page disclaimer card to /compliance and /about Regulatory Framework section.
- Version bumped 4.51.0 -> 4.51.1 (patch; additive metadata only) per Standing Order 6.
v4.51.0 — 2026-06-22
Type: minor · Breaking: no
Promise to Pay (PTP) lifecycle. Additive endpoints and admin/consumer surfaces for creating, settling, partial-payment, rescheduling, sweeping, and breaking PTP arrangements, with outbound institution webhooks and detailed delivery logs.
- Added /v1/ptp/ops and /v1/ptp/settle operations covering create, partial, reschedule, sweep, and break events with idempotency keys (UUIDv4) on every state-changing call.
- New admin console /admin/promise-to-pay with webhook health panel, plus consumer surfaces /app/ptp (status, next due date, remaining balance) and inbox alerts for created/partial/rescheduled/swept/broken events.
- Outbound institution webhooks for every PTP event with HMAC-SHA256 signing, per-event subscription check, and detailed delivery logs (request id, event name, institution id, response code).
- Transactional email templates: ptp-created, ptp-partial, ptp-rescheduled, ptp-kept, ptp-broken — registered in the shared template registry.
v4.50.1 — 2026-06-05
Type: patch · Breaking: no
BEAC / COBAC compliance hardening on Nium Global Accounts. Additive: hardcoded Purpose-of-Payment whitelist, strict KYC name matching on account creation, double-spread FX transparency endpoint, exact-name UI warning. Legacy /v1/gateway/virtual-accounts (NGN/Wema) is now flagged `deprecated: true` (sunset 2027-01-01). No operationIds renamed or removed (Standing Order 1).
- POST /v1/gateway/global-accounts now REJECTS free-text `beneficiary_name` (HTTP 400 `beneficiary_name_override_forbidden`). The beneficiary is pulled from the verified KYC profile only.
- POST /v1/gateway/global-accounts accepts a new optional `pop_code` enum locked to `"Software/Digital Services"` or `"Royalties"` (BEAC Règlement 02/18/CEMAC/UMAC/CM).
- POST /v1/gateway/global-accounts/quote — new public-facing helper that returns gross → Nium FX → KOB spread → MoMo fee → Net XAF for any (currency, amount, route). Shares math with the live webhook.
- profiles.default_payout_method (KANG_WALLET | MOBILE_MONEY) backfilled from existing payout_preference; cascade resolution (account override > user default > KANG_WALLET) unchanged.
v4.50.0 — 2026-06-05
Type: minor · Breaking: no
Nium-powered Global Virtual Accounts. Additive endpoints under /v1/gateway/global-accounts that issue real USD/EUR/GBP receiving accounts, settle inbound funds in XAF via Nium FX + configurable spread, and route to either the Kang Wallet or Mobile Money (Flutterwave). Legacy /v1/gateway/virtual-accounts (NGN/Wema) unchanged in this release.
- POST /v1/gateway/global-accounts — provision USD/EUR/GBP virtual account; idempotent per (user, currency).
- GET /v1/gateway/global-accounts — list accounts, recent incoming payments, user payout defaults.
- PATCH /v1/gateway/global-accounts/payout-preference — set user-level default or per-account override (KANG_WALLET | MOBILE_MONEY).
- POST /v1/gateway/global-accounts/webhook — Nium → KOB incoming-payment webhook, HMAC-SHA256 signed (`x-nium-signature`), idempotent on `transactionId`.
v4.49.0 — 2026-05-29
Type: minor · Breaking: no
Phase 11 — integrator experience & governance. Adds enriched Postman environments (sandbox + production), admin send-test-webhook flow, institution API key admin console (create/rotate/suspend/revoke + usage), per-version OpenAPI export (JSON + YAML) with Postman 'Import Spec' UX, and ratchet tests for phases 10.2-10.5.
- Postman: Sandbox and Production environments now prefill base_url, api_key, webhook_secret, idempotency_key, accept_language, spec_url, spec_version, postman_import_url, key_issuer_url, merchant_id. README_postman.md documents the import flow.
- Admin: 'Send test webhook' button on /admin/webhook-deliveries fires a signed (HMAC-SHA256) synthetic event to any registered endpoint and records the delivery row with is_test=true. New edge function admin-send-test-webhook.
- Admin: new console /admin/institution-api-keys to create, rotate, suspend/resume, and revoke institution-scoped API keys. New edge functions api-keys-create and api-keys-suspend; reuses api-keys-rotate and api-keys-revoke. Per-key calls (24h/7d), error rate, last 429 timestamp.
- Spec: new public page /developer/spec-versions lists every ratchet/spec_version with copy-able JSON + YAML download URLs. Includes Postman 'Import → Link' instructions and copy buttons.
v4.46.0 — 2026-05-29
Type: minor · Breaking: no
Phase 10.3 — Agent banking. Adds /v1/agents/* registry, float management, cash-in/cash-out and transaction history. Cites BIS Agent Banking Guidelines (2018), Mojaloop v1.1, GSMA Agent Network Management Toolkit v2.
- Added POST /v1/agents and GET /v1/agents (geo + region discovery, country_code filter restricted to CEMAC).
- Added GET /v1/agents/{agentId} returning the agent plus embedded float balances.
- Added POST /v1/agents/{agentId}/float/topup and /float/withdraw with mandatory Idempotency-Key (UUIDv4) and 409 on insufficient float.
- Added POST /v1/agents/{agentId}/cash-in and /cash-out with X-Float-Warning: low_float response header when float drops below low_threshold.
v4.44.0 — 2026-05-29
Type: minor · Breaking: no
Phase 10.1 — CEMAC coverage & inclusion (additive). Closes audit gaps for mobile-money provider coverage, virtual-account regional examples, CEMAC identity verification, RTP SLA hints, credit-score data sources, bilingual error catalogue, and LoanScheduleItem deprecated-field cleanup.
- Extended MobileMoneyCharge.provider enum to include Airtel, ExpressUnion, and CamPost (GSMA MMA v1.2 §4.2). Added ExpressUnionPickup and CamPostAccount sibling schemas.
- Added POST /v1/verify/nin and POST /v1/verify/cni for CEMAC national identity verification (ICAO 9303; CIPRES). /v1/gateway/resolve-bvn retained for NG with RFC 8594 Deprecation + RFC 8288 Link: successor-version headers.
- Added RtpSla schema and X-Confirmation-Eta response header. next_action surfaces sub-30s p50 confirmation targets per provider (see /developer/reference/rtp-sla).
- Added CreditScore.data_sources (mobile_money_history, njangi_participation, cobac_registry, bureau_creditinfo, ...) and locale_band (cemac_v1 / fico_us / experian_eu) — COBAC R-93/13.
v4.43.0 — 2026-05-29
Type: minor · Breaking: no
High-priority gaps #6-#9 + per-tier rate-limit publication. All additive; zero removals.
- Added /v1/consents rail-agnostic consent lifecycle façade (create/get/list/revoke/extend).
- Added /v1/statements + /v1/statements/{id}/content producing ISO 20022 camt.053.001.08 XML.
- Added /v1/rate-limits publishing per-tier numbers (free, pro, enterprise).
- Added MobileMoneyErrorCode + MobileMoneyProviderError schemas; wired RFC 7807 422 envelope onto every /v1/mobile-money/* POST.
v4.41.0 — 2026-05-21
Type: minor · Breaking: no
Smart Budgeting — new /v1/budgeting/* endpoint group with trilingual AI adviser (EN/FR/Pidgin), savings goals, Njangi integration, and XAF-native spending analytics.
- Added 23 new /v1/budgeting/* endpoints (Budgets, Categories, Goals, Njangi, AI Adviser, Analytics).
- Added 15 new schemas to components/schemas — all referenced by at least one operation (Standing Order 5).
- Added 8 new webhook events: budget.threshold_reached, budget.overspent, budget.period_ended, goal.milestone_reached, goal.completed, njangi.contribution_due, insight.new, budget.unusual_transaction.
- Added new Budgeting tag with externalDocs pointing to /developer/guides/budgeting.
v4.40.0 — 2026-05-17
Type: minor · Breaking: no
Phase 8 bank-grade hardening — scalability KV cache, typed SDK matrix completion (Java + Go auto-generated), and k6 load-test harness with published SLO targets.
- New table public.kv_cache (admin-only RLS) provides a TTL-based, Redis-style key/value store for OIDC discovery, JWKS, and rate-limit counter caching across edge functions.
- New OpenAPI vendor extension x-scalability publishes the KV cache contract, typed SDK matrix (Node/Python/PHP/Go hand-tuned + auto-generated Java/Go/TS/Py), and the k6 load harness location and SLO budgets.
- Load harness scaffolded at e2e/load/ with three scenarios — charge-burst.js, webhook-flood.js, aisp-read-storm.js — bound to the sandbox and tied to p95 latency + error-rate budgets.
- Java SDK skeleton added at packages/sdk-java (Maven, Java 11) to satisfy Docs Standing Order P9 (Multi-Language Rule).
v4.39.0 — 2026-05-17
Type: minor · Breaking: no
Phase 7 bank-grade hardening — shared risk blocklists, per-merchant behavioral baselines, and configurable fail-closed risk policy for high-value transactions.
- New table public.risk_blocklists (admin-only RLS) unifies blocked msisdn/email/iban/device_id/ip across the platform with severity, source, and TTL via expires_at.
- New table public.merchant_risk_baselines stores rolling 30-day per-merchant stats (avg/p95/max amount, decline rate, distinct customers) used to enrich risk-score decisions.
- New system_config rows risk_fail_closed_enabled (default false) and risk_fail_closed_threshold_xaf (default 1,000,000 XAF) convert risk-score to fail-closed for high-value charges when enabled — opt-in to preserve current behaviour.
- New OpenAPI vendor extension x-risk publishes the blocklist identifier types, baseline metric set, and fail-closed contract so SDKs and downstream tools can introspect the policy.
v4.38.0 — 2026-05-17
Type: minor · Breaking: no
Phase 6 bank-grade hardening — declarative data-retention policy registry and consent-ledger reuse.
- New table public.data_retention_policies seeded with 4 COBAC/GDPR baselines: KYC 7y (anonymize 6y), transactions 10y, consent 7y, webhook deliveries 1y (anonymize 6mo).
- Reuses existing public.consent_events (immutable AISP/PISP ledger) and public.compliance_reports (regulatory exports) without schema churn.
- New OpenAPI vendor extension x-data-retention publishes the horizons and legal bases so SDKs and downstream tooling can introspect the policy contract.
- Fully additive — no operationId, path, schema, RLS policy, or column renamed or removed (Standing Orders 1 & 4).
v4.37.0 — 2026-05-17
Type: minor · Breaking: no
Phase 4 bank-grade hardening — feature-flagged payment orchestration layer with 24h idempotency cache and charge dead-letter queue.
- New edge function payment-orchestrator sits in front of payment-router-charge. Flag-gated by system_config.payment_orchestrator_enabled (default OFF) — when OFF, calls are passed through unchanged (zero behavioural risk).
- New table public.charge_dlq (admin-only RLS) captures charges that exhaust provider 5xx retries; supports replay tooling.
- New table public.idempotency_cache_extended extends the existing 60s in-flight reservation to a 24h replay window per merchant + idempotency_key.
- Response header X-Orchestrator (passthrough | active) lets clients observe which path served the charge.
v4.36.0 — 2026-05-17
Type: minor · Breaking: no
Phase 5 bank-grade hardening — end-to-end distributed tracing, structured JSON logger for edge functions, and an admin SLO dashboard.
- Added nullable trace_id column + index to public.webhook_deliveries, gateway_charges, and safeguarding_ledger — a single request can now be followed across HTTP, charge processing, webhook delivery, and ledger posting.
- New shared edge-function helper supabase/functions/_shared/logger.ts — structured single-line JSON logs with mandatory trace_id; accepts inbound X-Trace-Id or W3C traceparent and falls back to UUID v4.
- X-Trace-Id response header documented on every operation (3,020 responses in production spec, 2,575 in sandbox).
- New top-level OpenAPI vendor extension x-observability publishes the SLO targets: charge success ≥ 99.5% / webhook delivery ≥ 99.0% / charge latency p50 200ms, p95 800ms, p99 1500ms.
v4.35.0 — 2026-05-17
Type: minor · Breaking: no
Phase 3 bank-grade hardening — reconciliation Kanban data model, immutable audit-export bucket, canonical payment state machine documentation.
- Extended public.reconciliation_mismatches with assignee, settlement_id, ledger_batch_id, priority, detected_by, updated_at — enables the Kanban (open → investigating → resolved → written_off) without renaming any existing field.
- New private storage bucket audit-exports — write-once, admin-only read, 7-year retention horizon (COBAC).
- New permanent public page /developer/payments/state-machine — canonical charge lifecycle: 13 states, 19 legal transitions, terminal-state guarantees (Order P1, P2, P6).
- OpenAPI x-state-machine extension documents the same states/transitions for SDK and tooling consumers.
v4.34.0 — 2026-05-17
Type: minor · Breaking: no
Phase 2 bank-grade hardening — per-key scope matrix on bearerAuth, webhook circuit-breaker headers, manual-replay headers, public webhook event registry.
- Added x-scopes extension to bearerAuth documenting the 12-scope per-key matrix (charges:*, payouts:*, customers:*, webhooks:*, reports:read, compliance:*, admin:*). Enforcement layer backed by new public.api_key_scopes table (additive).
- Added X-Webhook-Replay, X-Webhook-Replay-Of, X-Circuit-State headers to every documented webhook event in the OpenAPI 3.1 webhooks block (additive parameters, no rename).
- New table public.webhook_endpoint_health with per-endpoint circuit-breaker state (closed | half_open | open), rolling failure window, and cool-down deadline.
- New permanent public page /developer/webhooks/events — canonical registry sourced from the live event-schema SSOT (Order P1, P2, P6).
v4.33.0 — 2026-05-17
Type: minor · Breaking: no
Phase 1 API contract hardening — cursor pagination parity, RFC 7807 error normalization, and X-Request-ID correlation across all 405 operations.
- Added starting_after + ending_before cursor parameters to 41 offset-only list endpoints (offset retained for backward compatibility per Standing Order 1).
- Normalized 17 inline 4xx/5xx responses to shared RFC 7807 ProblemDetails components (BadRequest, NotFound, Conflict, etc.).
- Added optional X-Request-ID header to every operation; echoed back on responses and persisted across edge functions, ledger writes, and outbound webhook deliveries.
- New OpenAPI quality gates: cursor-parity check and Problem coverage check, wired into CI.
v4.32.0 — 2026-05-08
Type: minor · Breaking: no
Virtual Card Issuing v2 release — Kora middleware for Banks and Developers.
- New /v1/issuing/* surface: cardholders, cards, fund/withdraw, freeze/unfreeze/terminate, transactions, reveal.
- PCI-safe reveal endpoint requires step-up MFA; full PAN/CVV is never persisted.
- HMAC-SHA256 webhook receiver (kora-webhook) with idempotent event ledger.
- New Issuing console for Bank staff (/fi-portal/issuing), Developers (/developer-tools/issuing), and Admins (/admin/issuing).
v4.31.0 — 2026-05-06
Type: minor · Breaking: no
Partner-mode QR acceptance — external virtual-card issuers (Visa, Mastercard, fintechs) can now discover KOB merchants and push card-funded payments through the KOB PISP rail. Fully additive — no path, schema, or operationId renames.
- New endpoint GET /v1/merchants/qr-directory paginated public list of verified KOB merchants (country, MCC, cursor).
- New endpoint GET /v1/merchants/qr-directory/{id} returns merchant info plus a freshly built EMVCo MPQR payload (static or dynamic).
- POST /v1/payments/qr-initiate gains a partner-mode auth branch driven by client_credentials access tokens carrying scope payments:qr; partner mode debits a partner_card_token instead of an internal virtual card.
- New header X-Partner-Cardholder-Ref and request fields partner_card_token_id + auth_evidence (PSD2 RTS Art. 18 SCA attestation).
v4.30.0 — 2026-05-06
Type: minor · Breaking: no
Adds Merchant-Presented QR (MPQR) bridge for virtual cards. New POST /v1/payments/qr-initiate decodes EMVCo MPM payloads and forwards through the existing PISP rail. Replay-protected, additive only.
- New endpoint POST /v1/payments/qr-initiate (EMVCo decode + PISP push).
- New error codes QR_001 invalid_qr_payload, QR_002 unsupported_currency_or_country, QR_003 card_unavailable, QR_004 step_up_required, QR_005 upstream_pisp_error, QR_006 idempotency_conflict.
- Dedicated qr_payment_idempotency table provides deterministic 24h replay protection (Idempotency-Key + request hash).
- PISP webhook handler reconciles QR card payments and triggers the in-app merchant success screen via realtime.
v4.29.5 — 2026-05-04
Type: patch · Breaking: no
Documentation closure on the 15-point Open Banking readiness audit. Four new public developer pages expose surface that already existed in the API: Strong Customer Authentication, JWKS, Environments, and the Deprecation Policy. Additive only — no path, schema, or operationId changes.
- New page /developer/security/sca documents POST /v1/security/sca/initiate, challenge types, verification, and the full payment-with-SCA sequence diagram.
- New page /developer/security/jwks documents GET /v1/jwks and the OIDC alias /v1/.well-known/jwks.json with verification snippets and 90-day rotation policy.
- New page /developer/environments consolidates sandbox vs. production base URLs, OAuth/PAR/JWKS endpoints, rate limits, mTLS posture, IP allow-list, and SLA in one matrix.
- New page /developer/api-reference/deprecation-policy formalizes the 12-month sunset window, RFC 8594 Sunset/Deprecation/Link headers, and the migration playbook.
v4.29.4 — 2026-05-04
Type: patch · Breaking: no
Native OpenAPI 3.1 webhooks, lifecycle reference pages, and SDK changelog discoverability. Additive only — no path, schema, or operationId changes.
- Promoted 8 outbound webhook events (payment_intent.succeeded/failed, refund.created, payout.paid, consent.authorized/revoked, account.balance.updated, kyc.verification.completed) from x-webhooks into the native OpenAPI 3.1 webhooks object so SDK generators emit typed handlers.
- New developer-portal lifecycle pages: /developer/api-reference/charge-states, /payout-states, /dispute-lifecycle — each with sequence diagrams and state machines.
- BuildReliablySection on /developer surfaces the new lifecycle pages plus a Standards & compliance entry pointing to /developer/standards.
- apis.json advertises SDK CHANGELOG.md URLs for Node, Python, PHP, and Go and links the FAPI/OBIE/DCR/ISO 20022 standards index.
v4.29.3 — 2026-05-04
Type: patch · Breaking: no
Live OpenAPI remediation for POST /v1/pisp/payment-submission. The request schema now requires payment_id, consent_id, amount, currency, debtor_account, and creditor_account so SDK generators and developer integrations no longer see the stale payment_id-only contract.
- public/openapi.json, public/openapi.yaml, public/openapi-sandbox.json, and public/openapi-sandbox.yaml now advertise the expanded PISP submission request body.
- The public spec-serving function now emits API version 4.29.3 with the same required PISP request fields as the static OpenAPI files.
- The changelog feed head records the PISP schema correction, preserving public developer auditability under ORDER P7.
- Replaced the stale payment_id-only request schema for POST /v1/pisp/payment-submission.
v4.29.2 — 2026-05-04
Type: patch · Breaking: no
Developer portal version alignment across public OpenAPI specs, Postman manifest and collections, getting-started examples, gateway quickstart metadata, and changelog mirrors. This release also preserves the /v1/v1/ prefix cleanup and documents that changelog coverage now spans v4.17.0 through v4.29.x without gaps.
- public/openapi.json, public/openapi.yaml, public/openapi-sandbox.json, and public/openapi-sandbox.yaml now report info.version 4.29.2.
- public/postman/manifest.json and regenerated Postman collection aliases now match the canonical OpenAPI version.
- Developer guide response examples now use the shared KOB_API_VERSION source instead of stale literal API versions.
- public/changelog.json includes entries for every release family from v4.17.0 through v4.29.x, closing the documented five-week gap.
v4.29.1 — 2026-05-03
Type: patch · Breaking: no
Critical live-spec remediation: /v1/pisp/payment-submission now advertises the expanded OBIE 4.0 §5.4 request body, and the 12 past-sunset endpoints now expose only HTTP 410 Gone with RFC 8594 successor metadata.
v4.29.0 — 2026-05-03
Type: minor · Breaking: no
Audit remediation: PISP submission body expanded (OBIE 4.0 §5.4); 12 past-sunset endpoints retired with HTTP 410 + RFC 8594 Sunset/Link; 19 monetary fields coerced number→string per FAPI 1.0 Adv §5.2.2; webhook signature header canonicalized (X-KOB-Signature with X-Webhook-Signature alias); Webhook v1 endpoints deprecated → /v1/webhooks/v2/endpoints (sunset 2026-12-31); 2144 application/problem+json refs corrected to ProblemDetails (RFC 7807); rate-limit window unit declared per_minute; 45 ops gained default 5XX; SDK metadata unified (Java + Go added to x-sdks); currency required on POST /v1/interbank/payments per ISO 20022 pacs.008; AISP list endpoints flagged x-pagination-style=cursor.
v4.28.2 — 2026-05-02
Type: patch · Breaking: no
Documentation-only alignment of webhook signature and replay-protection header names. Adds an explicit 'Webhook Signature & Replay Headers (canonical)' table to info.description in both openapi.yaml and openapi.json. Runtime middleware already accepts all canonical headers and aliases — this release makes the integration contract explicit.
- Canonical X-KOB-Signature with v1=<hex> versioning prefix (Stripe convention).
- Aliases X-Kang-Signature and X-Webhook-Signature accepted for backward compatibility.
- X-Webhook-ID dedup window (24h), X-Webhook-Timestamp replay window (5min) formalised.
- X-Webhook-Event and X-Webhook-Attempt receiver-side telemetry headers documented.
v4.28.1 — 2026-05-02
Type: patch · Breaking: no
Closes audit gap G4 (SDK coverage metadata) by extending info.x-sdk-libraries with Java, Go, and Ruby entries. G5 (real-world examples route) confirmed already implemented in src/pages/developer/RealWorldExamples.tsx and registered in App.tsx + vite-plugin-prerender-docs.ts.
- info.x-sdk-libraries.java — typed client generated by openapi-generator-cli (okhttp-gson), version mirrors spec.
- info.x-sdk-libraries.go — github.com/kangopenbanking/sdk-go v1.5.0 published module.
- info.x-sdk-libraries.ruby — community implementation guide via openapi-generator-cli.
- Each entry includes status, repository, package_manager, and docs URL so Backstage / Stoplight / Redocly auto-surface the SDKs.
v4.28.0 — 2026-05-02
Type: minor · Breaking: no
Spec versioning + diff endpoints, end-to-end provider sandbox simulators (Stripe, Flutterwave, PayPal), Connector Runbook interactive simulator, Institution API Client registration with pre-filled client_credentials snippet, and Admin Webhook Replay history + bulk replay-all-failed action.
- GET /v1/spec/versions and GET /v1/spec/diff?from=&to= — structured OpenAPI version diff (RFC 6902 intent), flags breaking changes per Standing Order 1.
- POST /v1/sandbox/providers/{provider}/simulate — signs realistic Stripe/Flutterwave/PayPal payloads with provider test secrets and forwards through the canonical Kang receiver.
- /developer/spec-diff — public interactive diff UI between any two published spec versions.
- ConnectorSandboxSimulator embedded in /developer/connectors/bank-connector-runbook (file ingestion + reconciliation phases).
v4.27.3 — 2026-05-02
Type: patch · Breaking: no
Audit-driven hardening — restored /v1/webhooks/providers/* canonical paths, declared the missing BankConnectors tag, injected 429 / 401 / 400 responses across ~50 operations, added the reusable XFapiInteractionId response header to all 200/201 responses, and tightened required[] arrays on WebhookReplayRequest, DcrRegistrationRequest, and WebhookEventType.
- Removed legacy duplicate webhook paths (/webhooks/stripe etc.) — single canonical route under /v1/webhooks/providers/{provider}.
- Reusable XFapiInteractionId header component referenced by every 200/201 response (FAPI 1.0 §6.2.1.13).
- Coverage floors enforced via src/test/openapi-v4-27-3-regressions.test.ts (11 tests).
- Provider webhook paths regressed to /webhooks/* in v4.27.2 — restored to /v1/webhooks/providers/{stripe|flutterwave|paypal}.
v4.27.2 — 2026-05-02
Type: patch · Breaking: no
Stripe-grade API documentation richness — added 2,863 response examples across all 391 operations (392 success + 2,473 RFC 7807 error examples), wired x-codeSamples for cURL/Node.js/Python/PHP into every operation, expanded 280 thin operation descriptions, added 13 reusable components.examples, 5 new components.responses (BadRequest, NotFound, UnprocessableEntity, InternalServerError, ServiceUnavailable), and a formal x-webhooks catalogue documenting 8 outbound events with HMAC-SHA256 signature verification and 7-attempt backoff retry policy.
- All 391 operations now ship with response examples, multi-language code samples, and ≥80-char descriptions (390/391).
- scripts/enrich-openapi.mjs — idempotent enrichment pass, safe to re-run after any operation added.
- src/test/openapi-richness.test.ts — richness ratchet preventing regression on examples / x-codeSamples / descriptions.
- x-webhooks: payment_intent.succeeded, payment_intent.failed, refund.created, payout.paid, consent.authorized, consent.revoked, account.balance.updated, kyc.verification.completed.
v4.27.1 — 2026-05-02
Type: patch · Breaking: no
Standards discoverability — closed the auditor 10-second-test gap by surfacing FAPI / OAuth2 / OIDC / DCR / mTLS / OBIE / Berlin Group / FDX / ISO 20022 / PSD2 SCA / COBAC compliance proofs from the /developer landing page. Every standard already implemented in the spec is now reachable from the developer home in one click.
- /developer/authentication/dcr — new public RFC 7591 + RFC 7592 Dynamic Client Registration reference page with cURL / Node / Python snippets, SSA claim table, and FAPI 1.0 Advanced cross-references.
- /developer/open-banking/standards — rewritten as a Standards & Compliance Index covering 11 standards, each linking to its proof page.
- StandardsComplianceRow on /developer home — visible badge strip linking each standard to its proof page (the 10-second auditor test).
- Uptime probes added for /developer/authentication/dcr and /developer/open-banking/standards in the 15-minute GitHub Action.
v4.27.0 — 2026-05-01
Type: minor · Breaking: no
International standards alignment — reaffirmed and documented FAPI 1.0 Advanced security profile (PKCE S256, PAR RFC 9126, JAR RFC 9101, PS256 signing, mTLS-bound tokens via cnf.x5t#S256), OBIE-style permission enums (ReadAccountsDetail, ReadBalances, …), Berlin Group NextGenPSD2 alignment, FDX 6.0 alignment, ISO 20022 message families (pacs / pain / camt), and the OBIE migration guide.
- Standards matrix expanded to 11 standards with explicit conformance citations.
- OAuth authorizationUrl / tokenUrl / refreshUrl normalized to slash-form paths.
- DCR token_endpoint_auth_method enum hardened: 'none' removed (FAPI 1.0 Adv §5.2.2 forbids public clients).
- Audit rebuttal table published at /developer/open-banking/standards documenting where each external audit claim is already implemented.
v4.26.7 — 2026-04-30
Type: patch · Breaking: no
Phase 6 closeout — Final production-readiness run. OpenAPI quality gates G1–G5 pass on 391 operations, all three webhook receivers (Stripe / Flutterwave / PayPal) verified to reject unsigned payloads with 401 invalid_signature on production edge runtime, all five required public docs URLs return 200 on the canonical published origin, and docs/internal/final-report.md captures full evidence including DB migration scope (330 migrations clean), unit test results (431/493 pass; 56 pre-existing mock-chain failures documented), Playwright E2E scaffold readiness, and explicit remaining TODOs.
- docs/internal/final-report.md — Phase 6 production-readiness report with per-gate evidence, webhook live-probe results, public docs URL probes, and standing-order compliance matrix.
- Webhook ingestion: stripe / flutterwave / paypal receivers all return 401 invalid_signature to unsigned payloads, proving HMAC + verif-hash + transmission-sig verification are active in production.
- Public docs URL verification: kangopenbanking.com/openapi.json, /openapi.yaml, /developer/api-explorer, /developer/examples, /developer/examples/real-world all 200 OK.
- Outstanding: user must click Publish to roll the frontend (published origin still on 4.16.4); add SANDBOX_BASE_URL + SANDBOX_API_KEY in GitHub repo secrets to enable live Postman contract job.
v4.26.6 — 2026-04-30
Type: patch · Breaking: no
Phase 5 hardening — Added /developer/status POS Commerce health probe (api-health now returns services.pos by reading pos_products / pos_orders / pos_store_profiles), shipped scripts/generate-typed-sdks.mjs (npm run sdk:generate) producing TypeScript / Python / Go / Java clients via openapi-generator-cli from public/openapi.json, wired .github/workflows/sdk-generate.yml (Java 17 + Node 20) to build them on every PR and upload the kangopenbanking-typed-sdks artifact on main, and surfaced them in the existing /developer/guides/sdks hub alongside the curated SDKs.
- supabase/functions/api-health — added checkPosHealth() probing pos_products + pos_orders + pos_store_profiles; services.pos now reports operational/degraded instead of falling through to down.
- scripts/generate-typed-sdks.mjs — version pinned to spec info.version, ratchet per Standing Order 6; emits sdks/generated/{typescript,python,go,java}/ with GENERATED.md guard files.
- .github/workflows/sdk-generate.yml — runs on every PR touching public/openapi.json or the generator script; uploads kangopenbanking-typed-sdks artifact on main (90-day retention).
- src/pages/developer/SDKsPage.tsx — new 'Generated typed clients' section with install commands per language and link to the CI artifact (positioned below the curated SDKs to preserve recommended DX path).
v4.26.5 — 2026-04-30
Type: patch · Breaking: no
Phase 5 hardening — Added newman + ajv (+ ajv-formats) as devDependencies and wired .github/workflows/api-contract-gates.yml. The workflow runs OpenAPI quality gates G1–G5 (npm run openapi:gates) on every PR/push and, when SANDBOX_API_KEY is configured, executes the Postman collection against sandbox via Newman with Ajv schema validation (npm run postman:contract). Adds a changelog/version alignment guard so info.version in openapi.json must match the changelog head.
- devDependencies: newman@^6, ajv@^8, ajv-formats@^3 — required by scripts/postman-contract-check.mjs.
- .github/workflows/api-contract-gates.yml — two jobs: openapi-gates (always) + postman-contract (skips gracefully without SANDBOX_API_KEY secret).
- CI version-alignment guard prevents merging spec changes whose version does not appear in changelog.json head (Standing Order 6).
- postman-contract job is needs: openapi-gates so a failing gate short-circuits the live run.
v4.26.4 — 2026-04-30
Type: patch · Breaking: no
Phase 5 follow-up — Embedded webhook simulator into /developer/api-explorer (Webhook simulator tab), shipped /developer/merchants/api-keys with create/rotate/revoke + per-permission scoping + audit log, fixed pagination snippets in docs/examples/* to use the documented page+limit / cursor contract (was offset=0), and added scripts/postman-contract-check.mjs (npm run postman:contract) that runs the published Postman collection against sandbox via Newman and validates each response against its OpenAPI schema with Ajv.
- ApiExplorer.tsx — third tab 'Webhook simulator' lazy-loads SandboxWebhookTester (HMAC-SHA256, send to user URL) + WebhookEventSimulator (failure-mode replay).
- MerchantApiKeysManager.tsx — sandbox/production toggle, 8 fine-grained permissions, 24h rotation overlap, secret shown ONCE (cryptographic key governance), audit_logs surfaced in-page.
- docs/examples/02,06,07,08,09: replaced ?limit=N&offset=0 with ?page=1&limit=N to match CursorParam/LimitParam/PageParam in OpenAPI components.
- docs/examples/12: switched bank-aggregator loop to cursor-based pagination.
v4.26.3 — 2026-04-30
Type: patch · Breaking: no
Phase 5 — Developer experience hardening: new Merchants documentation hub at /developer/merchants, public Markdown changelog at /CHANGELOG.md generated from changelog.json, and an OpenAPI quality-gate CI script (scripts/openapi-quality-gates.mjs) enforcing 2xx schema, RFC 7807 errors, idempotency on financial mutations, list-endpoint pagination, and webhook signature/dedupe documentation. Baseline allow-list captured per Standing Order 2 (THE RATCHET). info.version bumped to 4.26.2 across openapi.json/yaml + sandbox specs to match the live changelog.
- Added src/pages/developer/MerchantsDocsHub.tsx — consolidated index of onboarding, KYB, API keys, webhooks (in/out), settlements, refunds, disputes, reconciliation, and funding (ORDER P6 — Complete Content Rule).
- Added scripts/build-changelog-md.mjs and npm run changelog:md — emits public/CHANGELOG.md and CHANGELOG.md from the JSON source of truth (ORDER P7).
- Added scripts/openapi-quality-gates.mjs and npm run openapi:gates — CI ratchet enforcing G1 (2xx schema), G2 (webhook signature + dedupe), G3 (Idempotency-Key on financial mutations), G4 (pagination on list endpoints), G5 (RFC 7807 application/problem+json on 4xx/5xx).
- Captured baseline in scripts/openapi-quality-gates.allow.json — known exceptions only; new violations beyond this set fail CI (Standing Order 2 — THE RATCHET).
v4.26.2 — 2026-04-30
Type: patch · Breaking: no
Phase 4.4 — Closed notification gaps in loan-ops/savings-ops/piggybank/njangi-ops with audit_logs + notifyAdmins calls. Added /admin/loan-review-queue and /admin/savings-anomaly-queue. Scaffolded authenticated Playwright suites (KYB visibility, admin inbox, webhook replay) — skipped until test users are seeded (see e2e/SEEDING.md).
- Added _shared/audit-trail.ts (non-fatal recordAuditEvent helper, service-role).
- loan-ops: audit + notifyAdmins on apply/approve/disburse.
- savings-ops: audit on create/withdraw + notifyAdmins on ≥500k XAF or locked-account withdrawals.
- piggybank: audit on cancel (links the -5 credit penalty to a traceable event).
v4.26.1 — 2026-04-30
Type: patch · Breaking: no
Phase 4 — Dashboard & mobile-app E2E readiness: catalogued 700 routes across 12 dashboards into docs/internal/ui-inventory.json, scaffolded a Playwright smoke harness with one test per dashboard root, and audited Edge Functions for missing notifyAdmins/audit_logs coverage. Documentation-only; no API contract changes.
- Added playwright.config.ts and e2e/smoke/dashboards.spec.ts (12 smoke tests: Admin, FI Portal, Merchant, Personal, Customer PWA, Business PWA, Banking App, Developer, Marketing, API Explorer, Changelog).
- Generated docs/internal/ui-inventory.json (700 routes, 83 admin nav items, 38 merchant nav items).
- Identified 4 confirmed notification gaps in loan-ops / savings-ops / piggybank / njangi-ops (no audit_logs, no notifyAdmins). Targeted fixes pending approval.
- No OpenAPI changes — Standing Order 1 (THE LOCK) and Standing Order 6 (THE VERSION GATE) preserved.
v4.26.0 — 2026-04-30
Type: minor · Breaking: no
Phase 3 — Payment Gateway readiness: spec exposure for merchant API-key lifecycle (rotate/revoke/get), per-webhook lifecycle (get/update/delete/rotate-secret/deliveries/replay), admin KYB lifecycle (queue/approve/reject/suspend/reinstate), report exports (CSV/XLSX), settlement statements, reconciliation run detail, and the public inbound provider webhook URLs (Stripe, Flutterwave, PayPal). All endpoints already deployed; this release advertises them on the public OpenAPI surface.
- Added DELETE/GET /v1/merchants/api-keys/{keyId} and POST /v1/merchants/api-keys/{keyId}/rotate — secret returned ONCE per cryptographic-and-api-key-governance
- Added GET/PATCH/DELETE /v1/merchants/webhooks/{webhookId}, POST /v1/merchants/webhooks/{webhookId}/rotate-secret (24h overlap window), GET /v1/merchants/webhooks/{webhookId}/deliveries, POST .../deliveries/{deliveryId}/replay
- Added GET /v1/admin/merchants, GET /v1/admin/kyb/queue, POST /v1/admin/merchants/{merchantId}/(approve|reject|suspend|reinstate) — admin KYB lifecycle with reason codes
- Added GET /v1/gateway/reports/(transactions|settlements|fees)/export — CSV/XLSX export center
v4.25.0 — 2026-04-30
Type: minor · Breaking: no
Phase 2 — File-based Bank Connector Kit: spec exposure for SFTP/CSV ingestion, batch payment generation (CSV + ISO 20022 pain.001), status-file ingestion and reconciliation. All endpoints already deployed; this release adds them to the public OpenAPI surface so banks without APIs can integrate via documented contracts.
- Added POST /v1/banks/{bankId}/connector/files/upload — manual CSV/XML upload (accounts, balances, transactions, beneficiaries, payment_instructions, payment_status, statement)
- Added POST /v1/banks/{bankId}/connector/sftp/config and POST /v1/banks/{bankId}/connector/sftp/pull — SFTP credentials and pull-now trigger
- Added GET /v1/banks/{bankId}/connector/imports and GET /v1/banks/{bankId}/connector/imports/{importId} — import history with line-level errors
- Added GET/POST /v1/banks/{bankId}/connector/mappings and POST /v1/banks/{bankId}/connector/validate-template — versioned column-mapping templates with transforms
v4.24.0 — 2026-04-30
Type: minor · Breaking: no
Phase 1 — Open Banking readiness: spec aliases for OIDC discovery, consent lifecycle completeness, AISP pagination parity.
- Added GET /v1/consents/{consentId}/status (already deployed as `consent-status` runtime function)
- Added POST /v1/consents/{consentId}/extend (already deployed as `consent-extend` runtime function)
- Added GET /v1/certificates/{certificateId} for individual certificate retrieval (eIDAS / FAPI 1.0 Advanced §5.2.2)
- Added POST /v1/oauth/register — Dynamic Client Registration (RFC 7591), aligning spec with OIDC discovery advertisement
v4.23.0 — 2026-04-30
Type: minor · Breaking: no
Phase 7 — Per-phase changelog backfill, versioning policy reaffirmation, OpenAPI tag alignment.
- Backfilled per-phase changelog entries for Phases 2–6 (webhook reliability, CSV exports, idempotency hardening, runtime + spec hardening, E2E test gate)
- OpenAPI info.version bumped 4.22.0 → 4.23.0; tagged in changelog (STANDING ORDER 6 — Version Gate)
- Versioning policy pages /api/versioning and /developer/api-reference/versioning verified public and SSR-readable (ORDER P1, P4)
- No removals, renames, or schema changes — additive metadata only (STANDING ORDER 1, 4)
v4.22.0 — 2026-04-29
Type: minor · Breaking: no
Phase 6 — End-to-end test CI gate covering provider webhook ingestion, merchant lifecycle, outbound webhooks, contract summary, and dashboard routes.
- Added 5 E2E suites (37/37 passing) plus 6 companion ratchets (13/13 passing) wired into .github/workflows/phase6-e2e.yml
- Provider webhook ingestion: Stripe HMAC, Flutterwave verif-hash, PayPal cert validation; 401 on bad signature; webhook_inbox dedup
- Merchant lifecycle: KYB submit → admin approve → key issuance → 24h grace on rotation
- Outbound merchant webhooks: endpoint create → delivery log → exponential backoff → manual replay
v4.21.0 — 2026-04-28
Type: minor · Breaking: no
Phase 5 — Runtime + spec hardening: idempotency runtime, pagination contract sweep, error catalog completeness, Postman/SDK regen.
- Idempotency helper rewritten with UUID v4 validation, atomic in-flight reservation, replay vs conflict vs in-flight outcomes (X-Idempotent-Replay, Retry-After: 2)
- Pagination: 21 list endpoints linked to LimitParam/CursorParam; PaginatedResponse envelope across all 73 list ops
- Error catalog: 42 ops patched for missing 4xx/5xx; 9 unschemad responses fixed; canonical Error/ProblemDetails/RateLimitError refs
- Postman regenerated to 346 requests via scripts/regen-postman.mjs; Node SDK 1.4.0 with IdempotencyError, WebhookReplayResult, ReportQuery types
v4.20.0 — 2026-04-27
Type: minor · Breaking: no
Phase 4 — Idempotency hardening across all financial mutation endpoints.
- Added Idempotency-Key header parameter (uuid, optional) to 18 financial POST/PUT/PATCH operations across Payment Gateway, Pay by Bank, Overdraft, etc.
- New CI ratchet src/test/openapi-idempotency-coverage.test.ts enforces uuid-format Idempotency-Key on every financial mutation
- Backward compatible: required:false keeps the parameter additive (STANDING ORDER 4)
v4.19.0 — 2026-04-26
Type: minor · Breaking: no
Phase 3 — CSV export endpoints for settlements, transactions, and disputes.
- New edge function gateway-reports exposes CSV-ready report endpoints with text/csv content-type and RFC 4180 quoting
- OpenAPI documents both application/json and text/csv responses; pagination cursors honored
- Audit at docs/audits/phase-3-csv-exports.md
v4.18.0 — 2026-04-25
Type: minor · Breaking: no
Phase 2 — Outbound webhook reliability: endpoint health probe, manual replay, exponential-backoff governance.
- New edge functions: gateway-webhook-endpoint-health and gateway-webhook-replay-delivery
- gateway-webhooks-router emits structured delivery_log rows with attempt count, response_status, next_retry_at
- 7-attempt exponential backoff (1m,5m,30m,2h,8h,24h,48h) documented in info.description
- Audit at docs/audits/phase-2-webhook-reliability.md
v4.17.0 — 2026-04-22
Type: minor · Breaking: no
KOB Integration Layer — Stripe-style facade over the existing /v1/* API. Strictly additive: zero changes to existing endpoints, schemas, or auth flows.
- New edge function POST /functions/v1/integration-layer/{resource}.{action} — unified router across customers, accounts, payments, transfers, payouts, refunds, webhooks, sandbox
- Unified response envelope { id, object, status, amount, currency, created, livemode, metadata, data } and error envelope { error: { type, code, message, param, request_id, upstream } }
- Smart routing engine (method × country × MSISDN) with automatic fallback chain; delegates to existing /v1/* handlers (Surgeon Rule honored)
- Platform-wide Idempotency-Key support via integration_idempotency_keys (24h TTL) and webhook replay via integration_webhook_replays
v4.16.4 — 2026-04-21
Type: patch · Breaking: no
Security Posture Self-Verification Layer -- live /healthz endpoint, hardened /oidc-config caching, public Security & Compliance live page, and downloadable whitepaper
- New public edge function /healthz returns a reviewer-friendly JSON snapshot with live probes for OAuth, OIDC, JWKS, DCR, PAR, plus declared posture for mTLS, JAR, PKCE, and webhooks (FAPI 1.0 Advanced)
- /oidc-config hardened with ETag, conditional GET (304), Cache-Control: public, max-age=3600, stale-while-revalidate=86400, plus op_policy_uri, op_tos_uri, key_rotation_policy_uri, and x-version metadata
- New public page /developer/security with live verification panel, standards matrix, security FAQ, and honest disclosure of known limitations -- verifiable without authentication (ORDER P1)
- New public page /developer/security/whitepaper plus downloadable PDF at /whitepapers/security-compliance.pdf
v4.15.0 — 2026-04-17
Type: minor · Breaking: no
CEMAC Universal Bank Integration -- Wave 4: documentation, OpenAPI version bump, and architecture overview tying Waves 1-3 together
- New public developer page /developer/connectors/cemac-bank-integration documents the full BankConnector architecture, adapter decision matrix, delivery waves, and operating runbook (ORDER P6)
- OpenAPI specification bumped to 4.15.0 (info.version only -- zero changes to operationIds, schemas, parameters, security schemes, or response codes per STANDING ORDER 1)
- Architecture diagram, adapter table, and operating-surface table satisfy ORDER P6 (no nav-only pages)
- Cross-links added between Bank Adapter Framework, Bank Onboarding Flow, and the new overview page
v4.14.0 — 2026-04-17
Type: minor · Breaking: no
CEMAC Universal Bank Integration -- Wave 3: ledger audit fields, six-stage bank onboarding wizard, and public certification flow guide
- Additive ledger columns on transactions (source_connector, sync_status, reconciliation_status, connector_audit_trail) -- all nullable with defaults; existing reads unaffected (STANDING ORDER 1)
- New table bank_onboarding_records tracks the six-stage certification flow per bank with admin-only RLS
- New admin route /admin/bank-onboarding provides a stepper wizard: Assessment -> Adapter -> Credentials -> Sandbox Test -> Certification -> Go Live
- New public developer guide /developer/connectors/bank-onboarding-flow documents the certification path, checklist, and ledger audit fields
v4.13.0 — 2026-04-17
Type: minor · Breaking: no
CEMAC Universal Bank Integration -- Wave 2: scheduled bank polling engine, rule-based reconciliation with auto-flagging, every-5-minute cron sweep across all enabled bank connectors
- New edge function bank-data-poller (cron */5 min) processes bank_sync_jobs, pulls accounts/balances/transactions via configured adapters, applies exponential backoff on failure (60s base, 1h cap)
- New edge function bank-reconcile-engine performs admin-triggered reconciliation against any enabled bank connector and persists outcomes to reconciliation_reports
- New tables bank_sync_jobs (per-config polling schedule with watermarks) and reconciliation_reports (rule-based recon outcomes) with admin-only RLS
- Safety: reconciliation engine flags discrepancies for review only -- never auto-credits or moves funds (financial integrity preserved)
v4.12.0 — 2026-04-17
Type: minor · Breaking: no
CEMAC Universal Bank Integration -- Wave 1: unified BankConnector interface with REST, SQL, File, and SOAP adapters, new bank-data-router with priority-based failover, full attempt audit trail
- New shared module supabase/functions/_shared/bank-connectors with a single contract: getAccountDetails, getBalance, getTransactions, initiateTransfer, reconcile, healthCheck
- Four pluggable adapters: REST (modern APIs), SQL (read-only via parameterized gateway), File (CSV/pain.001/MT940 from Storage), SOAP (legacy cores)
- New edge function bank-data-router resolves enabled adapters by priority and fails over automatically; admin-only via JWT + role check
- New tables bank_connector_configs (per-bank adapter setup) and bank_connector_attempts (full audit trail) with admin RLS
v4.11.0 — 2026-04-17
Type: minor · Breaking: no
BYO Phase 2 — server-side polling for direct mobile-money rails, SOAP Bank adapter for legacy core-banking systems, and multi-rail cross-bank failover with full attempt audit trail
- New cron edge function byo-charge-poller reconciles pending MTN/Orange/SOAP charges and fires synthetic webhooks via existing dispatcher
- New connector soap_bank with WS-Security UsernameToken authentication for T24, Flexcube, OBDX-class cores
- payment-router-charge now performs multi-rail failover across ALL enabled tenant connectors before Flutterwave fallback
- New tables byo_charge_polls and byo_routing_attempts with RLS scoped to owner + admin read-all
v4.10.0 — 2026-04-17
Type: minor · Breaking: no
BYO Mobile Money Connectors -- institutions, merchants, and developers can register their own MTN MoMo or Orange Money credentials and route charges through them while Flutterwave (KOB-managed) remains the default rail and automatic fallback
- New edge functions: tenant-connectors-manage, tenant-connectors-list, tenant-connectors-test, payment-router-charge
- New table tenant_payment_connectors with AES-GCM credential encryption (PAYMENT_CONNECTOR_KEY) and RLS
- Connector framework with unified PaymentConnector interface (initiateCharge, getStatus, refund, healthCheck)
- Direct connectors: MTN MoMo Collection API, Orange Money Web Payment, Flutterwave (default + fallback)
v4.9.7 — 2026-04-14
Type: patch · Breaking: no
Direct Backend Infrastructure Correction -- all runtime API references standardized to direct Supabase Edge Functions URL; legacy custom API domains removed from active spec, SDKs, and docs
- OpenAPI servers[] corrected to single direct backend entry
- OAuth/OIDC endpoint references corrected to direct backend paths
- All 8 payment channels verified returning JSON via direct backend
- SDK packages (Node, PHP, Python) DEFAULT_BASE_URL corrected
v4.9.6 — 2026-04-12
Type: patch · Breaking: no
Documentation depth upgrade -- 63-error catalogue, failure/retry/reversal guides, end-to-end use-case tutorials, auth decision table, observability checklist
- Error Codes Reference expanded from 18 to 63 codes across 14 domains (AUTH, AISP, PISP, PAY, MM, FLW, KYC, CERT, LOAN, SAV, ADM, WH, LED, BANK) with per-error recovery actions
- Retry/backoff code examples (Node.js + Python) added to Error Codes page for 429 and 5xx handling
- Common Mistakes section added to Error Codes Reference with 5 frequent integration pitfalls
- Failure handling, edge cases, and reversal flows added to Accept Payments, Refunds, and Payouts guides
v4.9.5 — 2026-04-11
Type: patch · Breaking: no
Webhook event expansion, sandbox x-test-data metadata, event filtering documentation, split payment examples
- 8 new webhook event types added: onboarding_application.approved/rejected, merchant_kyb.verified/failed, credit_score.updated, loan_application.approved/rejected/pending_documents
- Sandbox spec (openapi-sandbox.json) enhanced with x-sandbox: true, x-test-data test phone numbers and card numbers, x-scenario annotations
- Webhook event filtering documentation -- topic-based subscription model with events[] array on POST /v1/webhooks
- Split payment documentation expanded with marketplace worked examples, settlement timing, and percentage vs fixed_amount comparisons
v4.9.4 — 2026-04-08
Type: patch · Breaking: no
Rate limit documentation hardening, 429 response schema, X-RateLimit headers, and changelog version sync
- Added 429 Too Many Requests response with RFC 7807 ProblemDetails to all rate-limited endpoints
- Added X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After response headers to OpenAPI specification
- Rate limit documentation page (/developer/api/rate-limits) verified with per-endpoint and per-tier limits
- Changelog apiVersion synchronized with spec version (previously 4.9.3 while spec was 4.9.2)
v4.9.3 — 2026-04-05
Type: patch · Breaking: no
Self-service Sandbox Console with API key issuance, test data seeding, webhook testing, and bank connector validation
- Sandbox Console page (/developer/sandbox/console) -- unified self-service sandbox registration, API key generation, test data seeding, webhook testing, and bank connector validation
- Self-service API key issuance eliminates manual key provisioning -- developers get sbx_ keys instantly
- Bank connector validation suite tests all 4 modes (API, DB, File, MQ) plus Banking API Router with latency profiling
- Webhook testing sends real HTTP requests with HMAC-SHA256 signatures and reports status code and response time
v4.9.2 — 2026-04-05
Type: patch · Breaking: no
DCR schema completion -- full request/response schemas for POST /v1/dcr/register
- DcrRegistrationRequest component schema added with 12 properties including software_statement (SSA JWT), jwks_uri, jwks, and FAPI signing algorithm fields
- DcrRegistrationResponse component schema added with 13 properties covering all fields returned by the DCR edge function
- POST /v1/dcr/register endpoint now uses $ref component schemas instead of inline definitions
- Request and response examples added to the DCR endpoint for developer onboarding
v4.9.1 — 2026-04-05
Type: patch · Breaking: no
POS modules GA, live endpoint testing, SLA transparency, FAPI certification tracker
- POS Commerce modules (catalog, inventory, orders, refunds, WooCommerce sync) promoted to active status
- Live endpoint testing with real-time latency profiling (p50/p95/p99) on Test Report page
- SLA commitment table with 99.95% uptime target, RTO/RPO guarantees, and P1-P4 incident response times
- FAPI 1.0 Advanced certification tracker with 12-point checklist and OpenID Foundation verification link
v4.7.0 — 2026-04-03
Type: minor · Breaking: no
HTTP Caching, Token Lifecycle, Webhook Retry Policy, and Spec Hardening
- Cache-Control, ETag, and Last-Modified headers added to all 122 GET endpoints (RFC 7234)
- 304 Not Modified response component added for conditional request support
- Token lifetime documented: 15m access, 30d rotating refresh, 60s auth code
- Webhook delivery policy documented: 7 attempts, exponential backoff, 30-day dead-letter
v4.6.0 — 2026-03-29
Type: minor · Breaking: no
FAPI 1.0 Advanced Certification + Schema Hardening
- FAPI 1.0 Advanced certification ready — code_challenge and code_challenge_method now required on /v1/oauth/authorize
- Schema validation hardened — required[] arrays added to all 49 API schemas
- Idempotency-Key header added to 15 payment-related POST endpoints
- StandardResponse envelope applied to all 19 single-resource GET endpoints
v4.5.0 — 2026-03-29
Type: minor · Breaking: no
ISO 20022 Tag Alignment + OIDC Discovery
- ISO 20022 tag alignment across all 339 operations
- nonce parameter set to required on /v1/oauth/authorize per FAPI 1.0 Advanced Section 5.2.2-14
- OIDC discovery document extended with pushed_authorization_request_endpoint
v4.4.0 — 2026-03-28
Type: minor · Breaking: no
Multi-Language Code Examples + Response Validation
- Auto-generated code examples in 9 languages on all 60+ API reference pages
- Official SDK examples for Node.js, Python, and PHP added to API reference
- Postman Collection v2.1 auto-export from OpenAPI spec
- Response validation test suite — 8 automated tests for OpenAPI contract integrity
v4.3.0 — 2026-03-27
Type: minor · Breaking: no
Standards Remediation Release
- Fixed PISP required fields
- Added fapi-interaction-id headers
- Corrected server URL versioning
- Added 4 missing tag declarations
v4.2.0 — 2026-03-21
Type: minor · Breaking: no
Pay by Bank — Redirect-Based SCA
- Pay by Bank with Strong Customer Authentication
- New pay_by_bank_intents table
- Hosted authorization page with consumer approval screen
- 4 webhook event types: authorized, submitted, completed, failed
v4.1.0 — 2026-03-08
Type: minor · Breaking: no
POS Commerce Suite
- POS Commerce data model with 19 tables
- Catalog, Inventory, Orders, and Payments APIs
- WooCommerce connector with import and webhooks
- Inventory sync jobs with conflict handling
v4.0.0 — 2026-03-14
Type: major · Breaking: no
Identity Modernization — unified registration, login, MFA, onboarding lifecycle
- Unified /v1/identity/register endpoint supporting personal, merchant, institution, and developer account types
- MFA system — TOTP, SMS OTP, email OTP with step-up challenges
- Session management — device tracking, rotating tokens, session revocation
- Onboarding lifecycle — unified onboarding_applications table
v3.9.0 — 2026-03-14
Type: minor · Breaking: no
Admin Rewards & Referral Management, 5 new banking fee types
- Admin Rewards Management — full referral tracking, reward history, manual credit
- Dynamic reward settings — referral bonus, cashback rate configurable via system_config
- 5 new fee types: overdraft_fee, loan_processing_fee, atm_withdrawal, standing_order, dormancy_fee
v3.8.0 — 2026-03-13
Type: minor · Breaking: no
Overdraft Eligibility Engine + Credit Report Purchase
- Overdraft Eligibility Engine — 7-factor scoring with risk bands (A-F)
- Full overdraft lifecycle: recalculate, request, approve, suspend, revoke
- Credit Report Purchase — wallet-based payment with 30-day access
v3.7.0 — 2026-03-08
Type: minor · Breaking: no
POS Consumer Marketplace + QR Payments
- POS Consumer Marketplace — merchants publish storefronts
- QR Code Payments — static/dynamic merchant QR generation
- Wallet payment method added to pos-pay-order
v3.5.0 — 2026-03-01
Type: minor · Breaking: no
Cameroon Banking Identifiers — RIB, IBAN, BIC/SWIFT
- Full RIB (23-digit) and IBAN (27-char) validation with MOD-97 checksum
- DOMESTIC_RIB added to account_scheme enum
- Transfer rail auto-selection
v3.0.0 — 2026-02-26
Type: major · Breaking: no
30+ institutional pages, regulatory compliance, fraud engine
- BEAC/COBAC regulatory framework
- Fraud Engine — 5-layer defence model
- Double-Entry Ledger and Reconciliation Framework
v2.0.0 — 2026-02-16
Type: major · Breaking: yes
v1 API path standardization, RFC 7807, OAuth 2.0/DCR/mTLS, Payment Facilitation, Virtual Cards
- v1 API path standardization across all endpoints
- RFC 7807 error model with domain-prefixed codes
- OAuth 2.0 + Dynamic Client Registration + mTLS
- Payment Facilitation API
v1.0.0 — 2024-11-01
Type: major · Breaking: no
Initial public release — AISP, PISP, Mobile Money, Credit Scoring, OAuth 2.0
- Account Information Service (AISP)
- Payment Initiation Service (PISP)
- Mobile Money integration (MTN, Orange)
- Credit scoring engine
Machine-readable feeds
Developer Portal Home | OpenAPI Spec (JSON) | Contact