Intégration bancaire — architecture

Comment une banque branche magot sur son écosystème existant (émetteur carte, core banking, identité e-banking, app mobile, SI de supervision).

1. Principes

magot ne détient pas de fonds. La banque (ou son BaaS) détient la licence, les comptes et les cartes. magot est une couche d'expérience et de règles parentales au-dessus.
La banque garde ses systèmes. magot se branche par des ports standardisés ; on n'écrit pas de code sur mesure dans le cœur magot. Un port = une interface + une suite de tests de contrat que tout adaptateur doit passer (comme test/issuer-contract.test.ts aujourd'hui).
Multi-établissements, isolés. Chaque banque est un tenant, isolé par Row Level Security Postgres ; en production, une instance dédiée par banque si elle l'exige (hébergement suisse ou datacenter de la banque).
Aucune donnée carte sensible. Pas de PAN chez magot (PCI DSS hors périmètre, SAQ-A visé) ; 3-D Secure reste chez l'émetteur.

2. Vue d'ensemble

flowchart TB
  subgraph Banque
    APP[App mobile banque<br/>+ SDK magot]
    IDP[IdP e-banking<br/>OIDC]
    CORE[Core banking]
    ISS[Processeur / émetteur carte]
    SI[SI banque<br/>CRM, fraude, reporting]
    BO[Back-office conseillers]
  end
  subgraph magot
    API[API app /v1]
    AUTHZ[Service d'autorisation<br/>temps réel]
    J[(Journal d'événements<br/>append-only)]
    OUT[Événements sortants]
  end
  APP -- token banque échangé --> API
  IDP -. fédération .-> API
  ISS -- autorisation carte < 500 ms --> AUTHZ
  API -- gel, limites --> ISS
  API -- recharges --> CORE
  CORE -- mouvements, soldes --> API
  API --> J --> OUT -- webhooks signés --> SI
  BO -- API back-office --> API
  APP -. app marque blanche .-> API

3. Ports d'intégration

3.1 Émetteur carte — autorisation temps réel (entrant)

Le processeur appelle magot à chaque autorisation ; magot répond approuvé/refusé selon les règles parentales (gel, plafond journalier et par transaction, catégories bloquées, solde).

POST /webhooks/issuer/authorization, service dédié, décision en mémoire sans I/O (objectif p99 < 500 ms de bout en bout, mesuré < 10 ms côté magot).
Corps : idempotency_key, card_ref (référence de la carte chez l'émetteur), amount_cents, mcc, merchant. Réponse : approved, reason parmi card_frozen, daily_limit_exceeded, txn_limit_exceeded, category_blocked, insufficient_funds, unknown_card.
Sécurité : mTLS + signature HMAC du corps avec horodatage (anti-rejeu), établissement déduit du credential, jamais du corps. Contrat complet : issuer-webhook.md.
Repli (magot indisponible ou timeout) : politique décidée avec la banque — stand-in de l'émetteur avec les limites miroir posées sur la carte.

3.2 Émetteur carte — pilotage (sortant)

IssuerAdapter : création de compte et de carte, gel/dégel, lecture du solde, relevé des transactions par curseur (réconciliation). Les plafonds sont répliqués sur la carte chez l'émetteur pour que le repli reste sûr.

3.3 Financement / core banking

Les recharges (argent de poche, demande acceptée, mission validée) déplacent de l'argent du compte du parent vers celui de l'enfant.

Port FundingAdapter : transfer(from, to, amount, idempotency_key), statut asynchrone (en cours, exécuté, rejeté), relevé des mouvements.
Source de vérité : les soldes font foi chez la banque. magot tient un miroir pour l'expérience et l'autorisation temps réel, réconcilié chaque jour avec l'émetteur et le core banking ; tout écart produit un événement et une alerte.
Options par banque : virement interne, recharge programmée, TWINT (à confirmer avec la banque).

3.4 Identité

Qui	Cible
Parent	Identité de la banque : l'app de la banque échange son jeton contre un jeton magot (OAuth 2.0 Token Exchange, RFC 8693) ou le parent se connecte via l'IdP e-banking (OIDC). Les passkeys magot restent l'option de l'app marque blanche.
Appareil enfant	Appairage par QR à usage unique ou code à 6 chiffres (montre) → jeton d'appareil limité à cet enfant, révocable par le parent.
Conseiller banque	SSO sur l'IdP de la banque (OIDC/SAML), rôles lecture seule / support, accès nominatif journalisé.

Aucun mot de passe magot. Les jetons sont opaques, stockés hachés, révocables.

3.5 Événements sortants

Chaque fait métier est écrit dans un journal append-only (paiement, recharge, gel de carte, demande, mission, règle modifiée, décision d'autorisation).

Diffusion vers le SI de la banque par webhooks signés (HMAC, réessais avec backoff, file de rejeu) au format CloudEvents, schéma JSON versionné par type d'événement.
Alternative pour les banques qui l'exigent : relevé par curseur (GET /v1/events?cursor=N, le même protocole que les apps) ou connecteur vers leur bus (Kafka).

3.6 Back-office et configuration

API back-office pour le support banque : recherche d'un foyer, historique, gel d'urgence, export d'audit.
Configuration par établissement, versionnée : marque, devise, langues, plafonds par défaut, catégories, adaptateurs actifs.

4. Intégration mobile

Trois modes, cumulables :

App marque blanche : l'app magot aux couleurs de la banque, publiée sur le compte développeur de la banque. Aucun développement mobile côté banque.
SDK dans l'app de la banque : un Swift Package (MagotCore : client API, modèles, synchronisation, auth branchable par token provider ; MagotUI : écrans SwiftUI thémables). La banque garde son app, son login et sa charte. Android : même contrat d'API ; SDK Kotlin selon la demande.
API seule : la banque construit ses propres écrans sur l'API documentée (OpenAPI).

Les apps enfant (iPhone, Apple Watch) restent des apps magot marque blanche : un enfant de 7 ans n'a pas accès à l'app e-banking de ses parents.

5. Sécurité et conformité

Transport : TLS 1.2+ partout, mTLS sur les flux serveur-à-serveur.
Données : hébergement en Suisse, chiffrement au repos, colonnes sensibles chiffrées, secrets hors code (SOPS/age aujourd'hui, coffre de la banque en production).
Journal d'événements et décisions d'autorisation immuables (trigger Postgres qui refuse UPDATE/DELETE, y compris pour l'administrateur).
Consentements parentaux tracés, accès aux données de mineurs nominatifs et journalisés, export d'audit, politique de conservation et de purge (nLPD).
Sauvegardes continues (PITR, RPO ≈ 2-3 min) avec exercice de restauration documenté. Test d'intrusion externe avant pilote.

6. Hébergement et exploitation

Livraison en image conteneur (Docker) + chart Helm ou docker-compose, déployable chez un hébergeur suisse ou dans le datacenter de la banque.
Postgres 16+ standard (pas de dépendance propriétaire).
Observabilité OpenTelemetry (traces, métriques de latence d'autorisation), page de statut, runbooks.
Engagements : SLA 99,9 % (API) / 99,95 % (autorisation), plan de réversibilité, séquestre du code.

7. Sandbox

Un établissement de démonstration sur api-staging.magot.ch, remis sous forme de kit : fournisseur d'identité de test, credential de webhook, virements réglés par la banque elle-même via le webhook signé, événements poussés vers une URL de test. Toute l'intégration se rejoue pas à pas avant d'écrire la moindre ligne (sandbox.md).