-
Notifications
You must be signed in to change notification settings - Fork 0
Scope
This page is for pre-sales engineers, FSI architects, and demo presenters who need to answer the question:
"This looks like a payment gateway, but what does it actually do? And what would a production system add on top?"
The short answer: this demo is a PCI DSS-aligned fraud investigation platform with a payment simulation layer. It is not a full payment processing engine. That distinction matters when speaking to technical FSI prospects.
- What This Demo Is
- Quick Capability Map
- Domain-by-Domain Analysis
- What a Real Payment Gateway Adds
- BIAN Service Domain Coverage
- Talking Points for Demo Conversations
This demo is positioned as a PCI DSS-aligned reference architecture, not a payment processor. It answers one specific question that FSI CISOs ask:
"How can we keep cardholder data fully encrypted and still run fraud investigations at operational speed?"
The answer is MongoDB Queryable Encryption (QE) with AWS KMS. Every other feature (the checkout UI, card tokenization, merchant metadata, and RBAC roles) exists to make that core story credible and explainable in a live demo.
A standard card payment chain looks like this:
Merchant backend → Payment Gateway → Processor → Acquirer → Card Network → Issuer
This demo simulates the Payment Gateway position: the component that receives payment intents, stores cardholder data securely, routes authorization decisions, and feeds the fraud investigation workflow. It does not simulate the Processor, Acquirer, Card Network, or Issuer.
| Mode | Who uses it | Auth required |
|---|---|---|
| Simulator Mode | AE/SE running a live demo | No login (presenter-controlled) |
| Application Mode | Technical evaluators, POC walkthroughs | JWT login, role-based routing |
Both modes share the same MongoDB Atlas data, the same QE encryption, and the same API. The difference is the UX layer.
This table maps every major payment gateway capability category against the demo's current implementation and roadmap iteration.
| # | Capability | Status | Demo Roadmap |
|---|---|---|---|
| 1 | 💳 Card payments (single transaction) | ✅ Implemented | v1 |
| 2 | 🏦 Bank transfers (ACH / SEPA / SWIFT) | ✅ Implemented (rail engine, PISP provider, async settlement) | v2 |
| 3 | 📱 eWallets (Apple Pay / Google Pay) | ❌ Out of scope | Not planned |
| 4 | 🔐 Authentication: OAuth 2.0 / OIDC, JWT, data-driven ACL | ✅ Implemented | v1 / v2 |
| 5 | 🛡️ Passwordless / strong auth (CIBA, WebAuthn) | ✅ Implemented (CIBA backchannel + FIDO2-style enrolled keys, NIST AAL1) | v2 |
| 6 | 💰 Fund verification (balance / funds-availability gate) | ✅ Implemented (atomic hold via AIS + FX) | v2 |
| 7 | 🔁 Recurring payments / mandates | ✅ Implemented (ACH Direct Debit / SEPA SDD + scheduler) | v2 |
| 8 | 💸 Refunds | later | |
| 9 | ❌ Cancellations / voids | later | |
| 10 | 🌍 Multi-currency / FX conversion | ✅ Implemented (currency-exchange provider) | v2 |
| 11 | ⏸️ Pre-authorizations (hold + capture) | later | |
| 12 | 🔑 Card tokenization (PAN → token) | ✅ Implemented (surrogate token) | v1 |
| 13 | 🏪 Token vault (deterministic card token) | ✅ Implemented (cardEtokenProcedure, SD-57) |
v4 |
| 14 | 🚨 Fraud detection (rule-based trigger) | ✅ Implemented (amount + MCC rules; fds provider) |
v1 |
| 15 | 🔍 Fraud investigation: L1 search (QE equality) | ✅ Implemented | v1 |
| 16 | ⬆️ Fraud escalation: L2 sensitive field reveal | ✅ Implemented | v2 |
| 17 | 📋 Audit trail (per-case + event-driven timeseries) | ✅ Implemented (fraudDiagnosisCaseEvents + businessProcessEvent/complianceProcessEvent) |
v2 |
| 18 | ✅ Implemented | v2 | |
| 19 | 🤖 AI-assisted fraud pre-review | ✅ Implemented (agentDraftDiagnosis, Accept / Override) |
v5 |
| 20 | 🏬 Merchant management (onboarding, KYB, SSO app) | ✅ Implemented (external merchant app, merchant_officer review) |
v2 |
| 21 | 📦 Payment order lifecycle (intent → settled) | ✅ Implemented (paymentOrderProcedure, SD-64) |
v4 |
| 22 | 🔀 Split payments (marketplace distribution) | ❌ Out of scope | Not planned |
| 23 | 💡 Tips / gratuity | ❌ Out of scope | Not planned |
| 24 | 🔗 Payment links / hosted checkout | ✅ Implemented (paymentLinkRecord, checkoutSessionLog) |
v4 |
| 25 | 📊 Revenue analytics / BI reporting | ❌ Out of scope | Not planned |
| 26 | 🖥️ POS physical terminal integration | pos, contactless) |
Not planned |
| 27 | 🌐 Open Banking (AIS / PIS providers) | ✅ Implemented (AISP account validation, PISP payment initiation, SD-193 hub) | v2 |
| 28 | 🔄 Webhook delivery (signed callbacks) | ✅ Implemented (HMAC-signed, merchantWebhookDeliveryLog, CIBA ping/push) |
v2 |
| 29 | 🔑 AWS KMS key management | ✅ Implemented | v1 |
| 30 | 🔒 QE range queries (amount band search) | 🔵 Model ready | later |
| 31 | 🏷️ Statement descriptor / transaction description | ✅ Implemented (cardTransactionDescription + cardTransactionNarrative) |
v1 |
Legend:
- ✅ Fully implemented and demonstrated in the current build
⚠️ Partially present (field or status exists, no business logic or dedicated endpoint)- 🔵 Designed and modeled (TypeScript interfaces + BIAN SD defined), implementation scheduled
- ❌ Out of scope (not in any planned iteration)
| Capability | Status | Notes |
|---|---|---|
| 3-step card checkout UI | ✅ | Simulator + Application mode. Masks PAN on input; token generated client-side |
| Card number field: PAN never transmitted | ✅ |
paymentCardReference is a tok_<uuid> surrogate. Full PAN is PROHIBITED by design |
| CVV / PIN storage | ✅ Never stored | SAD (Sensitive Authentication Data) is never captured. PCI DSS Req 3.2 compliance |
POST /api/v1/transactions: creates transaction record |
✅ | Writes to cardTransactionLog (SD-254) with QE:equality on account reference |
| Statement descriptor / transaction description | ✅ |
cardTransactionDescription (max 22 chars, cardholder-visible) + cardTransactionNarrative (extended investigation context). BIAN SD-254 fields. Plaintext; not CHD |
| Transaction type classification | ✅ |
cardTransactionType enum: purchase, cash_advance, balance_transfer, refund, fee, adjustment
|
| Auto-creates fraud case on threshold breach | ✅ | Amount > FRAUD_AMOUNT_THRESHOLD or high-risk MCC triggers fraudDiagnosisCase creation |
| Bank transfer initiation (ACH / SEPA / SWIFT) | ✅ | v17.1. /system/transfer/bank + POST /gateway/transfers/*. Rail auto-derived + validated (ISO 13616 / ISO 9362 / NACHA), executed via the payment_initiation provider, async settlement, pre-initiation fraud gate, recurring Direct Debit mandates. See Bank Transfers
|
| eWallet initiation | ❌ | Not in scope |
This is the core demo capability. Everything here maps directly to a MongoDB feature.
| Capability | Status | MongoDB Feature | PCI DSS Req |
|---|---|---|---|
| Encrypted email (searchable) | ✅ | QE:equality on partyEmailAddress
|
Req 3 |
| Encrypted phone (searchable) | ✅ | QE:equality on partyMobilePhoneNumber
|
Req 3 |
| Encrypted account reference (searchable) | ✅ | QE:equality on cardTransactionAccountReference
|
Req 3 |
| Encrypted card expiry date (non-searchable) | ✅ | QE:none on paymentCardExpirationDate
|
Req 3 |
| Encrypted residential address (L2 only) | ✅ | QE:none inline, DEK-sensitive tier | Req 7 |
| Encrypted government ID (L2 only) | ✅ | QE:none inline, DEK-sensitive tier | Req 7 |
| Encrypted raw gateway payload (L2 only) | ✅ | QE:none inline on rawGatewayPayload
|
Req 7 |
| Customer-controlled keys (AWS KMS CMK) | ✅ | AWS KMS integration | Req 3.6 |
| Full PAN stored | ✅ NEVER | PROHIBITED by design. Masked display only | Req 3.5 |
| QE range queries on transaction amount | 🔵 | QE:range on cardTransactionAmount.amount
|
N/A |
| Wire encryption | ✅ | TLS 1.3 on all Atlas connections | Req 4 |
| Capability | Status | Notes |
|---|---|---|
| JWT authentication (local, HS256) | ✅ |
customerAuthenticationAssessment (SD-91). QE:equality on email |
| OAuth 2.0 / OIDC authorization server | ✅ | Confidential-client SSO (merchant app), discovery, id_token, userinfo, token revocation/introspection, JWKS |
| 6 roles: customer, L1, L2, auditor, merchant_officer, manager | ✅ | Data-driven ACL (ADR-030): resource/action permissions in the role collection, resolved via GET /api/v1/acl/effective; role in the JWT, permissions are not |
| Dual-auth (merchant = OAuth client) | ✅ |
dualAuth middleware accepts a first-party session JWT or a merchant OAuth Bearer on shared modules (v23) |
| Role-based field projection (L1 vs L2) | ✅ |
getDbForRole() selects L1 or L2 QE client pool |
| Escalation token for sensitive field reveal | ✅ | Short-lived token; X-Escalation-Token header binds L2 sensitive access |
| Passwordless / CIBA + WebAuthn | ✅ | CIBA backchannel login + browser-enrolled non-extractable keys (RS256/ES256); NIST AAL1 (v24/v25) |
| MS Entra ID / external OIDC federation | 🔵 |
authenticationDomain collection supports it; local OAuth/OIDC server is the implemented path |
| Fund authorization (balance / funds gate) | ✅ | v17 funds-availability gate: atomic hold via the AIS provider + FX |
A real payment gateway manages a full lifecycle: initiated → confirmed → authorized → captured → settled → refunded/voided. The demo currently models status values but implements only the write path.
| Lifecycle Stage |
cardTransactionStatus Value |
Endpoint | Status |
|---|---|---|---|
| Initiated | pending |
POST /transactions |
✅ Creates record |
| Authorized | authorized |
POST /transactions response |
✅ Simulated |
| Settled | settled |
(none) | |
| Disputed | disputed |
(none) | |
| Declined | declined |
POST /transactions response |
✅ Simulated |
| Captured (pre-auth → capture) | (none) | (none) | ❌ Not modeled. SD-64 Payment Order lifecycle covers this in v4 |
| Refunded | (none) | (none) | ❌ No refund endpoint. v4 scope |
| Voided | (none) | (none) | ❌ No void endpoint. v4 scope |
The full lifecycle (initiated → confirmed → authorized → captured → settled/refunded/voided) is the responsibility of SD-64 Payment Order and SD-65 Payment Execution, both planned for v4.
This is the second core capability of the demo, and it is fully implemented in v1+v2.
| Capability | Status | Notes |
|---|---|---|
| Auto-open fraud case on suspicious transaction | ✅ |
fraudDiagnosisCase (SD-83) created automatically |
| L1 search by encrypted email / phone / account ref | ✅ | QE equality query; server never sees plaintext |
| L1 search by card token (standard index) | ✅ |
paymentCardReference plaintext index |
L1 escalation (POST /fraud/:id/escalate) |
✅ | Status → escalated; audit event written |
L2 escalation approval + token (POST /fraud/:id/escalate/approve) |
✅ | Issues escalationToken (UUID, 4h TTL) |
| L2 sensitive field reveal (QE:none decrypt) | ✅ | L2 QE client auto-decrypts when escalation token valid |
| HRPC risk check (PEP, SIP, HNWI, fraud history) | ✅ |
GET /fraud/hrpc/check?accountRef=<ref>; queries customerCreditRatingState (SD-60) |
| Per-case audit event log | ✅ |
fraudDiagnosisCaseEvents: append-only, separate collection |
| Global audit log (Security Auditor) | ✅ |
GET /fraud/audit-events: all events, all cases |
| Case resolution (cleared / confirmed fraud) | ✅ |
resolutionOutcome field on case |
| AI-assisted draft diagnosis | 🔵 |
agentDraftDiagnosis field defined in model; v5 scope |
| QE range queries on amount (analyst filter) | 🔵 | v2 scope |
| Capability | Status | Notes |
|---|---|---|
paymentCardMandateStatus field |
✅ | active / cancelled / expired |
paymentCardConsentDateTime field |
✅ | PCI DSS Req 3.1 + 3.7 |
paymentCardMandateExpiryDate field |
✅ | Auto-purge trigger |
| Recurring mandate creation (ACH SDD / SEPA SDD) | ✅ |
recurringMandateProcedure (SD-66) + scheduler; POST /gateway/transfers/mandates, run-due (v17.1) |
| Merchant-initiated transaction (MIT) |
cardTransactionInitiationType: 'merchantInitiated' enum exists; commission attribution via SD-65 (v18) |
|
| Token vault (deterministic card token) | ✅ |
cardEtokenProcedure (SD-57) |
Merchants are a first-class actor (v18): a standalone external merchant SSO app (Espresso Works) authenticates as an OAuth confidential client and operates on the shared capability modules (v23 dual-auth). Onboarding runs through a KYB review by a merchant_officer.
| Capability | Status | Notes |
|---|---|---|
| Merchant name / MCC on transactions | ✅ | Plaintext fields on cardTransactionLog
|
| Merchant selector in Simulator checkout | ✅ |
GET /transactions/merchants returns unique name+MCC pairs |
| Merchant entity (agreement, OAuth client, KYB) | ✅ |
merchantAgreementProcedure (SD-89) with merchantAgreementKybCheck BQ:Step |
| External merchant SSO app | ✅ | OAuth 2.0 / OIDC confidential client, CIBA passwordless (v18 / v25) |
| Merchant onboarding / approval (KYB review) | ✅ |
merchant_officer reviews and approves/rejects applications |
| Commission / fee attribution | ✅ | SD-65 fee on merchant-attributed transactions (v18) |
| Merchant webhook delivery | ✅ | HMAC-signed, merchantWebhookDeliveryLog
|
| Capability | Status | Notes |
|---|---|---|
cardTransactionAmount.currency field (ISO 4217) |
✅ | Field present on all transaction records |
| Multi-currency display | ✅ | UI formats amount + currency code |
| FX conversion engine | ✅ |
currency-exchange provider; used by the funds-availability gate (v17) |
| Cross-border rails (SWIFT) | ✅ | SWIFT rail with correspondent surcharge (v17.1) |
| Capability | Status | Notes |
|---|---|---|
| Transaction list with filters (status, merchant, card token, email) | ✅ |
/demo/transactions view (analyst-facing) |
| Transaction history (customer-facing) | ✅ | /demo/payment/history |
| Fraud case dashboard (status, severity filters) | ✅ | /demo/investigation |
| Global audit log viewer (Security Auditor) | ✅ | /demo/audit |
| Revenue analytics / income reporting | ❌ | Out of scope |
| Merchant settlement reports | ❌ | Out of scope |
| MongoDB Charts integration | ❌ | Not planned in current iterations |
A production payment gateway such as Stripe, Adyen, or Braintree covers a broader surface than any single demo can address. The table below maps the standard capabilities of a real gateway against the demo's scope, to help presenters frame the boundaries correctly.
| Domain | Real Gateway Capability | This Demo | Gap |
|---|---|---|---|
| Payment rails | Card, ACH, SEPA, SWIFT, open banking, eWallet, BNPL | Card + ACH / SEPA / SWIFT + open banking (AIS/PIS) | eWallet / BNPL not covered |
| Authorization | Real-time approval from acquirer / card network | Provider-based (internal Module or external card-issuer provider via the hub) | No real network integration |
| 3DS / SCA | 3D Secure 2.x, Strong Customer Authentication (PSD2) | Partial: CIBA passwordless + WebAuthn (NIST AAL1); dynamic linking deferred | No 3DS protocol; SCA authorization link pending |
| Tokenization | Network tokens (Visa Token Service, Mastercard MDES) | Surrogate tok_<uuid> only |
No network token protocol |
| Settlement | Daily batch settlement to merchant bank account | Status field only | No settlement engine |
| Refunds / disputes | Full refund API, chargeback workflow, issuer communication | Status field only | No refund endpoint |
| Fraud scoring | Real-time ML scoring, velocity rules, device fingerprint | Amount + MCC rule trigger | No ML model, no device signals |
| Compliance programs | PCI DSS audit support, GDPR, CCPA, PSD2 | PCI DSS architecture reference | Regulatory reference only |
| Merchant onboarding | KYC, underwriting, MCC assignment, settlement schedule | KYB review + approval workflow (merchant_officer), external SSO app |
No underwriting / settlement scheduling |
| Reporting | Revenue dashboards, reconciliation reports, tax exports | Fraud + audit dashboards only | No financial reporting |
| Scalability | Multi-region, active-active, 99.99% SLA | Single-region demo cluster | Not a performance benchmark |
This is the key message for FSI technical audiences:
| Real gateway requirement | MongoDB capability | Demo moment |
|---|---|---|
| Search encrypted PII (email, phone) for fraud investigation | Queryable Encryption equality | L1 analyst finds the transaction by encrypted email; server never decrypts |
| Protect raw gateway payload and processor metadata from insider access | QE:none (non-searchable encryption) | Raw Gateway Payload visible only after L2 escalation approval |
| Customer controls their own encryption keys | AWS KMS CMK integration | Open AWS console; MongoDB has zero key access |
| Role-based field visibility for fraud teams | DEK-per-access-tier + RBAC | L1 sees masked fields; L2 sees full record; same document in Atlas |
| Immutable audit trail for every sensitive field access | Separate fraudDiagnosisCaseEvents collection |
Security Auditor reviews full access history |
| Flexible BIAN-aligned data model for core banking integration | MongoDB document model | BIAN field names throughout, credible to FSI architects |
BIAN (Banking Industry Architecture Network) provides the standard vocabulary for banking capabilities. The table below shows which BIAN Service Domains are in scope for each iteration.
| BIAN Service Domain | SD Ref | Collection | Status | Version |
|---|---|---|---|---|
| Party Data Management | SD-13 | party |
✅ Implemented | v1 |
| Customer Authentication | SD-91 | customerAuthenticationAssessment |
✅ Implemented | v1 |
| Party Authentication | SD-16 |
partyAuthenticationAssessment, authenticationDomain
|
✅ Implemented | v1 |
| Customer Agreement | SD-53 | customerAgreementProcedure |
✅ Implemented | v1 |
| Payment Card | SD-88 | paymentCardManagement |
✅ Implemented | v1 |
| Card Transaction | SD-254 | cardTransactionLog |
✅ Implemented | v1 |
| Fraud Diagnosis | SD-83 |
fraudDiagnosisCase, fraudDiagnosisCaseEvents
|
✅ Implemented | v1+v2 |
| Customer Credit Rating | SD-60 | customerCreditRatingState |
✅ Implemented (HRPC) | v2 |
| Merchant Relations | SD-89 | merchantAgreementProcedure |
✅ Implemented (KYB, OAuth client, SSO app) | v2 |
| Payment Order | SD-64 |
paymentOrderProcedure, checkoutSessionLog, paymentLinkRecord
|
✅ Implemented | v4 |
| Card Authorization | SD-15 | cardAuthorizationRecord |
✅ Implemented | v4 |
| Card Etoken (token vault) | SD-57 | cardEtokenProcedure |
✅ Implemented | v4 |
| Account Information (AIS) | SD-36 |
payoutAccountArrangement, balanceCreditLog
|
✅ Implemented (funds gate, AISP) | v2 |
| Payment Execution | SD-65 | paymentExecutionProcedure |
✅ Implemented (bank transfers, commission) | v2 |
| Payment Initiation | SD-66 |
payoutAccountArrangement, counterpartyArrangement, recurringMandateProcedure
|
✅ Implemented (PISP, mandates) | v2 |
| Fraud Evaluation | SD-63 | (provider: fds) |
✅ Implemented (real-time scoring) | v2 |
| Suspicious Activity Analysis | SD-99 | (provider: aml) |
✅ Implemented (AML monitoring) | v2 |
| Party Authentication (passwordless) | SD-91 / SD-16 |
partyEnrolledCredential, partyBackchannelAuthentication
|
✅ Implemented (CIBA / WebAuthn) | v2 |
| External Provider Arrangements | SD-193 |
externalProviderArrangement, capabilityModuleConfiguration
|
✅ Implemented (Integration Hub) | v2 |
| Consent Agreement (Open Banking TPP) | SD-36 |
consentAgreement, consentAccessLog
|
🔵 Stub (OAuth consent uses partyAuthConsent) |
later |
Out of scope BIAN SDs (not planned in any iteration): Current Account (SD-12), Savings Account (SD-39), Credit Facility (SD-47), Mortgage Loan (SD-47), Insurance (SD-74), Trade Finance (SD-58), and others. This demo is scoped to the card payment, bank transfer, and fraud investigation chain.
"No, and intentionally so. This demo shows the data security and fraud investigation layer of a payment gateway: the part that determines whether a bank can be PCI DSS compliant while still running fraud investigations at speed. The payment simulation is realistic enough to tell that story, but we're not emulating a card network or processor. What we're showing is how MongoDB handles the most sensitive part of that chain: storing, protecting, and querying cardholder data."
"A production system adds real authorization against a card network, multi-currency conversion, full refund and chargeback workflows, 3D Secure authentication, and a settlement engine. Those are solvable with standard integration patterns. What MongoDB uniquely solves (and what this demo shows) is the part that every payment system struggles with: how do you keep CHD fully encrypted and still let fraud analysts search it in real time? That's the MongoDB story."
"The data model is already there:
paymentCardMandateStatus,paymentCardConsentDateTime, and thetokenVaultcollection for network tokens are all defined and modeled in BIAN. The business logic is roadmap v4. For a POC you could wire up the mandate flow in a sprint using the existing schema."
"The demo runs on an M10 cluster for cost efficiency. The architecture (QE auto-encryption with
crypt_shared, separate DEK pools per access tier, application-side joins to avoid$lookupacross QE collections) is designed for production scale. MongoDB Atlas M30+ with horizontal sharding handles the write throughput of a mid-size card issuer. We have performance benchmarks from existing FSI customers if you want specifics."
"You do. The AWS Customer Master Key (CMK) lives in your AWS account. MongoDB never has access to it. Even MongoDB support cannot read your cardholder data. That's the architectural guarantee this demo shows live; we open the AWS KMS console and prove it."
This document is written for demo presenters and pre-sales engineers. It does not constitute a PCI DSS compliance assessment or a product specification. For implementation contracts, see technical-spec.md and roadmap.md.
- KYC/KYB built-in module administration: review workbench + configuration for the KYC and KYB engines; beneficial owners (FATF UBO); events-only onboarding fan-out; manual/automated/assisted decision mode.