FinFactory Primitives
Reusable financial infrastructure services with bounded domains, owned data, stable APIs, and domain events.
Overview
FinFactory primitives are reusable financial infrastructure services that can be composed into fintech products.
A primitive is not just a module or library. It is a bounded service with its own domain model, API contract, data ownership, events, operational workflows, and compliance responsibilities.
Primitive design rules
Each primitive should:
- Own its domain
- Own its database
- Expose stable APIs
- Publish domain events
- Support idempotent commands
- Maintain audit logs
- Enforce authorization
- Support tenant-level configuration where needed
- Avoid direct database access from other services
- Avoid leaking provider-specific details into product APIs
Initial primitive list
Identity and KYC
Verifies individuals and businesses.
Responsibilities:
- Customer identity
- Business identity
- KYC status
- KYB status
- Document verification
- Liveness verification
- Sanctions screening
- PEP screening
- Risk flags
- Verification provider integration
Typical events:
- customer.created
- kyc.started
- kyc.verified
- kyc.rejected
- kyc.expired
- risk.flagged
EMI Wallet Issuing
Manages wallet programs and wallet lifecycle.
Responsibilities:
- Wallet program configuration
- Wallet holder enrollment
- Wallet creation
- Wallet activation
- Wallet suspension
- Wallet closure
- Wallet tiers
- Wallet limits
- Allowed transaction types
- Compliance state
Typical events:
- wallet.created
- wallet.activated
- wallet.suspended
- wallet.closed
- wallet.limit.updated
Ledger
The source of truth for balances and financial postings.
Responsibilities:
- Accounts
- Balances
- Journal entries
- Double-entry postings
- Holds
- Reversals
- Adjustments
- Transaction references
- Available balance
- Current balance
The ledger should be deterministic, strict, and domain-neutral. It should not know about QRPh, cards, KYC, fraud, or product-specific business logic.
Typical events:
- journal.posted
- balance.updated
- hold.created
- hold.released
- transaction.reversed
QRPh Payments
Handles QRPh payment flows and QR-based money movement.
Responsibilities:
- QR generation
- QR parsing
- QR payment requests
- QR payment confirmation
- QRPh network integration
- InstaPay integration where applicable
- Merchant QR acceptance
- Payment status mapping
Typical events:
- qr.generated
- qr.payment.received
- qr.payment.confirmed
- qr.payment.failed
Credit Card Payments
Handles card acquiring flows.
Responsibilities:
- Authorization
- Capture
- Void
- Refund
- Card transaction lifecycle
- Acquirer integration
- Processor integration
- Scheme response mapping
- Merchant acquiring configuration
Typical events:
- card.payment.authorized
- card.payment.captured
- card.payment.failed
- card.payment.refunded
Card Issuing
Handles cardholder and card program lifecycle.
Responsibilities:
- Cardholder enrollment
- Card product configuration
- Virtual card issuance
- Physical card lifecycle
- Spend controls
- Card status
- Authorization rules
- Issuer processor integration
Typical events:
- card.issued
- card.activated
- card.suspended
- card.closed
- card.authorization.approved
- card.authorization.declined
3D Secure
Handles cardholder authentication for online card transactions.
Responsibilities:
- 3DS session creation
- Frictionless authentication
- Challenge authentication
- Authentication result
- ECI
- CAVV/AAV
- Directory server integration
- ACS interaction where applicable
Typical events:
- threedsecure.started
- threedsecure.challenge_required
- threedsecure.authenticated
- threedsecure.failed
Fraud Detection
Evaluates transaction and account risk.
Responsibilities:
- Risk rules
- Velocity checks
- Device fingerprinting
- Blacklists
- Whitelists
- Behavioral patterns
- Transaction scoring
- Manual review queue
Typical events:
- risk.approved
- risk.declined
- risk.review_required
- risk.rule_triggered
Tokenization
Protects sensitive payment credentials.
Responsibilities:
- Card tokenization
- Network token references
- Merchant token references
- Device token references
- Token lifecycle
- Secure token vault mapping
The tokenization service should prevent raw sensitive credentials from spreading across the platform.
Typical events:
- token.created
- token.updated
- token.suspended
- token.deleted
POS and SoftPOS
Manages physical and software payment acceptance endpoints.
Responsibilities:
- Terminal registration
- Terminal assignment
- POS app configuration
- Terminal management
- Device health
- SoftPOS activation
- Merchant-terminal mapping
- Terminal transaction synchronization
Typical events:
- terminal.registered
- terminal.assigned
- terminal.activated
- terminal.disabled
- terminal.heartbeat.received
AI Financial Agent
Provides controlled AI assistance across the financial platform.
Responsibilities:
- Transaction explanation
- Merchant support assistance
- Reconciliation summaries
- Risk investigation support
- Product setup guidance
- Back-office workflow assistance
- Anomaly detection support
The AI financial agent should be read-only by default. Any action that mutates financial state must require policy controls, role-based authorization, and audit logging.
Typical events:
- ai.agent.query.received
- ai.agent.action.proposed
- ai.agent.action.approved
- ai.agent.action.executed
- ai.agent.action.rejected