Executive Summary

This section describes a generic integration pattern for master–master wallet mirroring between a Fintech platform and a Regulated Financial Institution (RFI) operating a Banking‑as‑a‑Service (BaaS) platform.

The pattern enables a 1:1 wallet mapping between systems where:

• The Fintech wallet platform remains the system of record (SoR) for customer wallet state and all customer‑initiated transactions.
• The RFI BaaS platform executes regulated banking operations, enforcing limits, compliance, and fraud controls.
• Transactions follow a single canonical flow initiated by the Fintech platform, ensuring operational consistency and reconciliation integrity.
• Bank‑originated events are converted into canonical flows by notifying the Fintech platform to initiate the transaction.

This architecture ensures:

• Regulatory compliance
• Transaction idempotency
• Operational resilience
• Consistent reconciliation between the two ledgers

Background and Objectives

Many fintech wallet platforms require integration with regulated banking infrastructure to perform actions such as:

• Deposits
• Withdrawals
• Transfers
• Compliance checks
• Fraud evaluation

However, fintech platforms often maintain their own wallet ledgers and customer workflows.

This pattern enables a master–master synchronization model where:

Objectives

• Enable 1:1 wallet mirroring
• Maintain Fintech‑initiated canonical transaction flows
• Ensure idempotency and ordering
• Support fraud and compliance checks
• Provide reconciliation and auditability

Stakeholders and Roles

---

High Level Architecture

The integration uses bidirectional APIs with strict control over transaction initiation.

Key principle:

All transactional flows originate from the Fintech platform.

Components

• Fintech Wallet Platform

  • Customer wallet ledger
  • Transaction orchestration

• BaaS API Gateway

  • mTLS termination
  • JWT validation
  • Request signature validation
  • Rate limiting
  • Idempotency protection

• Transaction Orchestrator

  • Executes financial transactions
  • Applies policy and limits
  • Invokes fraud checks

• Event Notification Service

  • Sends notifications to the Fintech platform when bank events occur

• Reconciliation Engine

  • Performs ledger matching and dispute analysis

Wallet Creation and Master–Master Synchronisation

A 1:1 mapping exists between:

• Fintech wallet IDs
• BaaS wallet IDs

The mapping is maintained by both systems.

Identity Requirements

Each wallet must include:

• External Wallet ID (Fintech identifier)
• Internal Wallet ID (BaaS identifier)
• Wallet status
• Customer KYC attributes

Wallet lifecycle events include:

• Create
• Suspend
• Block
• Close

Wallet status changes must be synchronized between both systems.

Ledger Model

The system uses double‑entry accounting.

Every transaction results in:

• One debit
• One credit

Example:

Customer pays a fee:

Debit: Customer Wallet
Credit: Fee Wallet

Additional wallet types may include:

• Customer wallets
• Fintech operational wallets
• Settlement wallets
• System wallets

System wallets represent money entering or leaving the regulated banking environment.

Canonical Transaction Pattern

All wallet transactions follow this pattern:

Fintech → BaaS → Banking System → Response → Fintech

This ensures:

• One orchestration path
• Consistent auditing
• Simpler reconciliation

Transaction Flows

Fintech Initiated Transaction

1. Fintech wallet receives a transaction request from its channels
2. Fintech wallet does all internal processing but does not commit its transaction
3. Eclipse is asked to also do the transaction.
4. Eclipse does Fraud, screening etc and limit checks and updates its ledger and responds
5. Fintech commits its ledger transaction

Eclipse/Bank Initiated Transaction

A. Eclipse wallet receives a transaction request from its bank integrations

B. Eclipse delegates the transaction to the Fintech

C. Fintech wallet does all internal processing but does not commit its transaction

D. Eclipse is asked to also do the transaction.

E. Eclipse does Fraud, screening etc and limit checks and updates its ledger and responds

F. Fintech commits its ledger transaction

Peer‑to‑Peer Transfers

Internal wallet transfers follow the same canonical model.

Idempotency and Ordering

Each transaction includes a globally unique idempotency key.

Properties:

• Prevents duplicate execution
• Supports safe retries
• Enables distributed consistency

The BaaS platform must:

• Reject duplicate keys
• Return previous result for replays

Limits, Risk and Fraud

Transactions are evaluated by:

• Bank policy rules
• Transaction limits
• Fraud detection engines

Possible decisions:

• Approve
• Decline
• Review

Declines must include clear reason codes so the Fintech platform can reverse provisional wallet operations.

Error Handling and Reversals

Errors fall into several categories:

• Validation errors
• Policy violations
• Fraud declines
• Processing errors
• Transient failures

If a transaction fails after a provisional wallet change, the Fintech platform must reverse the transaction locally.

Atomic batch transfers should support full reversal by session ID.

Security and Compliance

Security controls include:

• Mutual TLS authentication
• JWT authentication
• Request signature validation
• Replay protection
• Full audit logging

Recommended standards:

• TLS 1.2+
• HMAC request signatures
• Rotating API credentials

Reconciliation

Reconciliation is performed daily between both systems.

Typical reports include:

Balance Report

Total balance grouped by wallet type.

Transaction Report

Includes:

• Source wallet ID
• Destination wallet ID
• Idempotency key
• Amount
• Timestamp

Customer Report

Includes:

• Customer identifier
• Wallet IDs
• Status
• Creation timestamp

These reports ensure ledger integrity across platforms.

Monitoring and Observability

Operational visibility should include:

• Transaction latency metrics
• Fraud decision telemetry
• Error rate monitoring
• API call tracing
• Idempotency conflict monitoring

Distributed tracing is recommended for debugging cross‑platform transactions.

Key Design Principles

1. Fintech initiates all flows
2. Bank events trigger canonical flows
3. Wallets are mirrored but independent
4. Strict idempotency guarantees
5. Double entry accounting
6. Reconciliation is mandatory
7. Security by default

Benefits of the Pattern

This architecture provides:

• Regulatory separation
• Operational clarity
• Simplified reconciliation
• Safe distributed transactions
• Fraud and compliance enforcement
• Scalable wallet infrastructure