Integration Architecture

ID.Banking connects to the outside world through a disciplined facade/adapter pattern. Every external dependency — payments, fraud, sanctions, card processing, notifications — is accessed via a platform-defined interface. This means the platform owns its integration contracts and can swap underlying providers without impacting business logic.

Platform Integration Landscape

The diagram below shows all major integration points between the ID.Banking platform and external systems. Platform-owned components appear in blue/cyan; external dependencies appear in gray/orange.

flowchart TB
  subgraph platform["ID.Banking Platform (owned)"]
    direction TB
    style platform fill:#e0f7fa,stroke:#0097a7,stroke-width:2px

    Ledger["CILedger
Balance Authority"]
    PaymentService["Payment Service
Rail Orchestration"]
    FraudEngine["Fraud Engine
Risk Scoring"]
    SanctionsService["Sanctions Screening
Compliance"]
    CardService["Card Issuing Service
Lifecycle & Auth"]
    NotificationService["Notification Service
Multi-channel Alerts"]
    ProvisioningService["Push Provisioning
Wallet Tokenisation"]
  end

  subgraph adapters["Facade / Adapter Layer (owned)"]
    direction TB
    style adapters fill:#e3f2fd,stroke:#1565c0,stroke-width:2px

    PaymentAdapter["IPartnerBank Adapter"]
    FraudAdapter["IFraudScoring Adapter"]
    SanctionsAdapter["ISanctionsScreening Adapter"]
    CardAdapter["ICardProcessor Adapter"]
    NotifyAdapter["INotification Adapter"]
  end

  subgraph external["External Dependencies"]
    direction TB
    style external fill:#fff3e0,stroke:#e65100,stroke-width:2px

    PayRails["Payment Rails
PayShap · RTC · PAPSS
M-Pesa · MoMo · Airtel"]
    FraudProvider["Fraud Provider
TransUnion · Internal ML"]
    SanctionsProvider["Sanctions Lists
UN · OFAC · EU · SARB"]
    CardProcessor["Card Processor
Marqeta · Lithic · Tutuka"]
    NotifyChannels["Notification Channels
SMS · Email · Push · WhatsApp"]
    CardNetworks["Card Networks
Visa · Mastercard"]
    TSPs["Token Service Providers
Apple TSP · Google TSP"]
    MobileWallets["Mobile Wallets
Apple Pay · Google Pay"]
  end

  PaymentService --> PaymentAdapter --> PayRails
  FraudEngine --> FraudAdapter --> FraudProvider
  SanctionsService --> SanctionsAdapter --> SanctionsProvider
  CardService --> CardAdapter --> CardProcessor
  NotificationService --> NotifyAdapter --> NotifyChannels
  CardProcessor --> CardNetworks
  ProvisioningService --> CardAdapter
  CardAdapter --> TSPs
  TSPs --> MobileWallets

Design Principles

• Interface-first contracts — Each adapter implements a platform-defined interface (ICardProcessor, IPartnerBank, ISanctionsScreening, etc.), ensuring the platform never depends on provider-specific APIs directly.
• Mock adapters for development — Every integration has a mock implementation enabling full end-to-end testing without live provider connections.
• Hot-swappable providers — Switching from one card processor to another (e.g., Marqeta to Lithic) requires only a new adapter implementation — no service-layer changes.
• Fail-closed posture — If an external dependency is unreachable, the platform declines the operation rather than proceeding without validation.

Card Issuing Integration Flow

The card issuing flow is the most complex integration path in the platform, spanning from the internal Card Issuing Service all the way through to a customer’s mobile wallet. Each hop is shown below with the responsible party at every stage.

flowchart LR
  subgraph owned["Platform-Owned"]
    direction LR
    style owned fill:#e0f7fa,stroke:#0097a7,stroke-width:2px

    CIS["Card Issuing
Service"]
    CPA["Card Processor
Adapter"]
    AE["Authorization
Engine"]
    PPS["Push Provisioning
Service"]
  end

  subgraph external_card["External Systems"]
    direction LR
    style external_card fill:#fff3e0,stroke:#e65100,stroke-width:2px

    Processor["Card Processor
(Marqeta / Lithic / Tutuka)"]
    Networks["Card Networks
(Visa / Mastercard)"]
    TSP["Token Service Provider
(Apple TSP / Google TSP)"]
    Wallet["Mobile Wallet
(Apple Pay / Google Pay)"]
  end

  CIS -->|"Issue / Freeze / Cancel"| CPA
  CPA -->|"API calls"| Processor
  Processor -->|"Webhook auth requests"| AE
  Processor -->|"Network routing"| Networks
  PPS -->|"Provisioning payload"| CPA
  CPA -->|"Token request"| TSP
  TSP -->|"DPAN tokenisation"| Wallet

Flow Stages

1. Card Issuance — The Card Issuing Service validates the request (account status, customer identity) and delegates card creation to the Card Processor Adapter. The adapter translates the request into the processor’s native API format.

2. Card Processor — The external processor (Marqeta, Lithic, or Tutuka) provisions the card on the network, stores full PAN and sensitive card data (PCI DSS scope stays with the processor), and returns a masked PAN and processor card ID to the platform.

3. Real-Time Authorization — When the card is used at a merchant, the transaction flows through the card network to the processor, which sends a webhook to the platform’s Authorization Engine. The engine checks spend controls and CILedger balance, then responds approve/decline within 2 seconds.

4. Push Provisioning — The Push Provisioning Service requests an encrypted provisioning payload from the processor via the adapter. This payload is passed to the mobile device’s native SDK (Apple PassKit or Google TapAndPay), which communicates with the Token Service Provider to create a Device PAN (DPAN) for NFC tap-to-pay.

5. Mobile Wallet — The TSP completes EMV tokenisation, linking the DPAN to the physical card network. The customer can now tap-to-pay using Apple Pay or Google Pay, with every transaction flowing back through the authorization webhook.

Responsibility Boundaries

Authorization Webhook Flow

Real-time transaction authorization is the most latency-sensitive integration. The platform guarantees a response within 2 seconds of receiving the webhook from the card processor.

sequenceDiagram
  participant Merchant as Merchant POS
  participant Network as Card Network
  participant Processor as Card Processor
  participant Platform as ID.Banking Webhook
  participant Engine as Authorization Engine
  participant Ledger as CILedger

  Merchant->>Network: Tap-to-pay (NFC)
  Network->>Processor: Authorization request
  Processor->>Platform: POST /webhooks/authorization
  Platform->>Platform: Validate HMAC signature
  Platform->>Engine: Process authorization
  Engine->>Engine: Evaluate spend controls
  Engine->>Ledger: Check available balance
  Ledger-->>Engine: Balance response
  Engine-->>Platform: Decision (approve/decline)
  Platform-->>Processor: HTTP 200 response (< 2s)
  Processor-->>Network: Auth result
  Network-->>Merchant: Approved / Declined

Latency Budget

Integration Summary