Skip to content

Home

Jump to bottom
Antonio Membrides Espinosa edited this page Jul 22, 2026 · 27 revisions

A Payment Service Provider (PSP) solution: a PCI DSS-aligned platform used by digital banks or card issuers to authorize card payments, detect fraud, and investigate cases. It runs the full payment lifecycle on MongoDB Atlas, from checkout and authorization, through automated transaction scoring, to multi-tier analyst investigation and resolution.

Core message: 🔐 Encrypt everything. 🔍 Query anything. 🔑 Keys are yours.

🎯 What This Demo Shows

A synthetic digital bank uses MongoDB Queryable Encryption (QE) with AWS KMS to protect cardholder data. The server stores only ciphertext. Fraud analysts still search encrypted fields by email, phone, and account reference: without server-side decryption. Access is controlled by role. Every action is audited.

This answers the most common FSI prospect question:

"How can we keep payment data fully encrypted and still run fraud investigations at speed?"

🗺️ Roadmap

Version Theme Status Key Features
🟢 v1 Security Foundation Complete Payment simulation, JWT auth, dual-mode UI, QE encryption visible, fraud investigation
🟢 v2 Investigation, Control & Platform In Development RBAC / data-driven ACL, escalation workflow, audit trail, HRPC check, profile management, plus all the platform capabilities below
🟢 v3 Integration-ready API Surface Planned Recurring payments, webhook events, stable OpenAPI contracts, performance visualization
🟢 v4 Payment Gateway + Integration Refinement Planned Modular backend (BIAN SD modules), gateway API, merchant as first-class actor, full payment order lifecycle
🟢 v5 Agentic Integration Planned AI agent (ThreatSight360) for automated fraud pre-review; draft diagnosis with Accept / Override

Within v2, the platform grew through a series of internal development-plan increments (the v6 / v17 / v18 / v24 numbers below are the engineering plan's own iteration ids in docs/roadmap.md, not product versions beyond v5):

Increment (dev-plan id) Delivered within v2
Integration Hub (v6) SD-193 external-provider registry, internal-first dispatch, system_admin role, HMAC webhooks
Event architecture (v7 / v8) Timeseries businessProcessEvent / complianceProcessEvent audit; Provider / Capability / Module taxonomy; BIAN-pure collection renames
Funds gate + Bank transfers (v17 / v17.1) Funds-availability gate + FX; ACH / SEPA / SWIFT transfers, recurring Direct Debit mandates, PISP / AIS providers
Merchant app (v18) External merchant SSO app (OAuth 2.0 / OIDC confidential client), commission model, merchant_officer review
Merchant unification (v23) Dual-auth (merchant = OAuth client on shared modules)
Passwordless (v24 / v25) CIBA login + WebAuthn-style credential enrollment (PSP portal and merchant app)

See Scope for a detailed breakdown of what each iteration implements, what is out of scope, and how this compares to a real payment gateway. For the complete FR, NFR, and acceptance criteria per iteration, see docs/roadmap.md.

⚡ Key MongoDB Capabilities Demonstrated

Capability What the Demo Shows
🔐 Queryable Encryption (equality) Search encrypted email, phone, and account reference (PII fields) without server-side decryption
🔒 Queryable Encryption (none mode) Protect address and government ID; revealed only after L2 escalation approval
🔑 AWS KMS integration Customer-controlled master key (CMK); MongoDB has zero access
👤 RBAC (data-driven ACL) Six roles (Customer, L1 Analyst, L2 Investigator, Security Auditor, Merchant Officer, Manager) with resource/action permissions resolved server-side (not in the JWT)
📢 Escalation workflow L1 escalates a case; L2 approves and receives a short-lived escalation token to reveal QE:none fields
🔍 Audit trail Append-only fraudDiagnosisCaseEvents plus event-driven timeseries businessProcessEvent / complianceProcessEvent streams
⚠️ HRPC risk check Lookup of High-Risk Person and Counterparty categories (PEP, SIP, HNWI, fraud history, etc.) against customerCreditRatingState (BIAN SD-60)
🔌 Integration Hub (SD-193) External-provider registry with internal-first dispatch for FDS, AML, sanctions, KYC/KYB, AIS/PIS, card issuer/authorization
🏦 Bank transfers ACH / SEPA / SWIFT rails via PISP, recurring Direct Debit mandates, account validation via AIS; the PSP holds no balances
🪪 Passwordless (CIBA + WebAuthn) OAuth 2.0 / OIDC authorization server with CIBA backchannel login and browser-generated, non-extractable enrolled keys
🌐 TLS 1.3 All Atlas connections encrypted in transit by default

🏛️ Regulatory Alignment

  • PCI DSS v4.0: MongoDB Atlas is a Level 1 validated Service Provider
  • BIAN (Banking Industry Architecture Network): data model follows BIAN Service Domain naming conventions
  • PSD2: open banking roles implemented as providers (AISP account information, PISP payment initiation); SCA aligned at the authentication layer (dynamic linking deferred)
  • GDPR: Art. 5 minimization / masking and Art. 32 encryption at rest for PII and bank data (IBAN/BIC), outside PCI scope
  • OAuth 2.0 / OpenID Connect + CIBA and FIDO2 / WebAuthn for identity, SSO and passwordless auth; NIST SP 800-63B AAL1
  • ISO 20022 payment messaging (pacs.002, remittance info, mandate ids) over ACH / SEPA / SWIFT rails

See the Architecture Proposal tab in the in-app help (/system/help/mongodb) for the full standards-and-regulations breakdown and the per-provider-group mapping.

🎬 Demo Flow

💳  Customer pays with credit card
         ↓
🔒  PAN tokenized in the browser: never transmitted or stored
         ↓
🔐  PII fields encrypted client-side before reaching MongoDB Atlas
     (customerEmailAddress, customerMobilePhoneNumber, cardTransactionAccountReference, ...)
         ↓
🚨  Suspicious transaction triggers a Fraud Diagnosis Case
         ↓
🕵️  Level 1 Analyst searches by encrypted email: finds the record
     MongoDB server never decrypted the field
         ↓
⬆️  Analyst escalates → Level 2 Investigator reveals sensitive fields (v2)
         ↓
📋  Complete audit trail: who accessed what, when, under which role (v2)

🚀 Quick Start

To begin the process of testing, installation, and execution, please follow the instructions in the installation guide.

Once running, verify the stack:

# 1. Install dependencies
npm run setup

# 2. Set up database (QE collections, DEKs, indexes)
npm run setup:db

# 3. Seed demo data
npm run setup:seed

# 4. Start dev servers (hot reload): backend, PSP frontend, and merchant app
npm run dev

# Health check (no auth required) — backend on port 8081
curl http://localhost:8081/api/v1/system/health

# Swagger UI
open http://localhost:8081/doc

# PSP frontend: http://localhost:8080   ·   Merchant app: http://localhost:8082

🗄️ Data Architecture

The data model follows BIAN Service Domain naming conventions. Core collections (see architecture.md for the full ~35-collection catalogue):

Collection BIAN Service Domain QE Protection Module
party Party Data Management (SD-13) equality: email, phone; none: postal address, date of birth customer
customerAuthenticationAssessment Customer Authentication (SD-91) equality: login email identity
partyEnrolledCredential / partyBackchannelAuthentication Party Authentication (SD-91/16) plaintext: passwordless public keys + CIBA requests identity
customerAgreementProcedure Customer Agreement (SD-53) equality: account reference; none (inline): address, government ID, risk notes customer
paymentCardManagement Payment Card (SD-88) none: expiry date; card token is plaintext customer
cardTransactionLog Card Transaction (SD-254) equality: account reference; none (inline): gateway payload, processor metadata transactions
fraudDiagnosisCase / fraudDiagnosisCaseEvents Fraud Diagnosis (SD-83) plaintext: cases + append-only audit log fraud
customerCreditRatingState Customer Credit Rating (SD-60) plaintext: HRPC risk classification flags fraud
merchantAgreementProcedure Merchant Relations (SD-89) plaintext: merchant agreement + OAuth client config gateway
paymentOrderProcedure / cardEtokenProcedure Payment Order (SD-64) / Card Etoken (SD-57) plaintext order + token vault gateway
payoutAccountArrangement / paymentExecutionProcedure Payment Initiation / Execution (SD-66/65) none: IBAN, routing, destination IBAN (GDPR/PSD2) gateway
externalProviderArrangement External Provider Arrangements (SD-193) plaintext: integration-hub registry provider
businessProcessEvent / complianceProcessEvent audit (timeseries) plaintext: event streams (TTL) provider

Multi-DEK key set (16 DEKs, two tiers):

  • Lookup tier (5 DEKs): QE:equality fields (searchable encrypted PII) accessible to all authenticated analyst roles.
  • Sensitive tier (11 DEKs): QE:none fields (address, DOB, government ID, raw gateway payload, card expiry, and GDPR/PSD2 bank data: payout IBAN/routing, destination IBAN) accessible only to L2 Investigator with a valid escalation token and Security Auditor.

Full schema definitions, field-level QE modes, index strategy, and collection relationships are in docs/technical-spec.md and architecture.md.

🛡️ PCI DSS Alignment

This demo demonstrates a PCI DSS-aligned reference architecture. MongoDB Atlas holds PCI DSS 4.0 certification. The customer remains responsible for their own PCI compliance program.

Key PCI DSS v4.0 requirements addressed:

  • ✅ Req 3: Cardholder data encrypted before storage; SAD (CVV, PIN) never stored
  • ✅ Req 3.6: Customer-controlled key management via AWS KMS
  • ✅ Req 4: TLS 1.3 on all Atlas connections
  • ✅ Req 7: Role-based field visibility (v2)
  • ✅ Req 10: Audit log for all field access events (v2)

📁 Repository Structure

sec-fsi-pci-dss/
├── 💻 frontend/        # PSP portal: Next.js App Router + TypeScript (port 8080)
├── 🛍️ merchant/        # External merchant SSO app (Espresso Works), DB-less, OAuth/OIDC + CIBA (port 8082)
├── ⚙️ backend/         # Fastify + TypeScript + NPM Tools (setup + seed), OAuth/OIDC server (port 8081)
└── 📚 docs/            # Engineering documentation

🏗️ Technology Stack

Layer Technology
💻 Frontend Next.js 14 App Router + TypeScript
⚙️ Backend API Fastify 4 + TypeScript
🗄️ Database MongoDB Atlas (M10+) with Queryable Encryption
🔑 Key Management AWS KMS (local KMS fallback for offline demos)
📦 Project setup npm workspaces + concurrently
🎨 UI Design LeafyGreen Design System

🖥️ Application Modes

The demo runs in two modes accessible from the home screen:

Application Mode (requires login): Role-based UX with JWT authentication.

  • Customer: Makes payments, views transaction history and status, manages profile (edit with QE:equality re-encryption)
  • L1 Analyst (Sarah Chen): Dashboard of investigation cases, search customers via QE, manage transactions, HRPC risk check, escalate cases, add notes
  • L2 Investigator (Michael Obi): Sees escalated cases first; approves escalations (issues DEK-sensitive token); reveals QE:none fields (address, government ID)
  • Security Auditor (Diego Sans): Read-only view of all cases, transactions, users, and the global audit log

Simulator Mode: Story-driven walkthrough (no login required). Shows all perspectives in one session.

📚 Documentation

Document Description
📖 Project Wiki Installation guide, API reference, Q&A, and resources for non-engineering readers
🔌 API Reference Complete REST API: all modules, endpoints, request/response shapes, PCI constraints
📋 PRD What and why: audience, storyline, BIAN data model, QE design overview
🗺️ Roadmap FR and NFR per iteration (v1–v5) with acceptance criteria and Definition of Done
🛠️ Technical Specification BIAN TypeScript interfaces, QE encryptedFieldsMaps, API contracts, index strategy
🏗️ Engineering Proposal Architecture decisions (BIAN module map §3.8), implementation phases P1–P26, ADRs
🗂️ Architecture Overview Data model, PII fields, encryption design, collection relationships, and role model
🔐 Encryption Queryable Encryption field config, DEKs, master key (CMK) management, CHD envelope, key lifecycle
🎯 Payment Gateway Scope What this demo implements vs. a real payment gateway, mapped to roadmap iterations
❓ Q&A: PCI DSS Common FSI client questions about MongoDB and PCI DSS compliance
🧪 Test Dataset Default test users, card numbers and bank accounts (ACH/SEPA/SWIFT) with approve/block scenarios
🏦 Bank Transfers End-user guide: ACH/SEPA/SWIFT transfers, recurring Direct Debit, approvals/blocks/errors
🐛 Issues Bug reports, feature requests, and task tracking

⚠️ Disclaimer

This demo uses synthetic data only. No real cardholder data, personal information, or production credentials are included. The demo is a reference architecture illustration and does not constitute a PCI DSS compliance certification or legal compliance advice.

Clone this wiki locally