joellewis/integration-patterns

Integration Patterns

Core Concepts

1. API Design for Financial Systems

Financial APIs serve position data, transaction history, account information, reference data, and order submission. Design conventions differ from general-purpose APIs due to the sensitivity, auditability, and volume of financial data.

REST conventions: Resource-oriented design with nouns for financial entities -- /accounts/{id}/positions, /transactions, /orders/{id}/executions. Use HTTP methods semantically: GET for reads (positions, balances), POST for actions (order submission, transfer initiation), PUT/PATCH for updates (account preferences, model assignments). Return standard HTTP status codes with domain-specific error bodies including error codes, human-readable messages, and correlation IDs for traceability. Financial APIs must distinguish between synchronous operations (position lookup returns immediately) and asynchronous operations (transfer initiation returns a 202 Accepted with a status polling URL or webhook callback). Long-running operations such as bulk rebalancing or batch trade submission should use the async pattern to avoid client-side timeouts.

WebSocket and streaming: For real-time use cases (position updates, order status, market data), WebSocket connections provide server-push capability without polling overhead. Financial WebSocket APIs require heartbeat/ping-pong to detect stale connections, automatic reconnection with state recovery (the client must receive missed updates on reconnect), and back-pressure handling when the consumer cannot keep pace with the producer.

Versioning: URL-based versioning (/v2/positions) is the dominant pattern in financial APIs due to its visibility and cacheability. Breaking changes (field removal, type change, semantic change) require a new version; additive changes (new optional fields) do not. Maintain at least two concurrent versions with a published deprecation timeline (typically 12-18 months in financial services).

Pagination for large datasets: Position and transaction endpoints routinely return thousands of records. Cursor-based pagination (opaque next-page token) is preferred over offset-based for consistency during concurrent writes. Include total count estimates, page size limits, and sorting parameters. For bulk data extraction, offer a separate export/download endpoint returning files rather than paginated API calls.

Rate limiting and throttling: Protect systems from burst traffic during market events (open, close, volatility spikes). Use token bucket or sliding window algorithms. Return 429 Too Many Requests with Retry-After headers. Distinguish rate limits per client, per endpoint, and per operation type (reads vs writes).

Authentication and authorization: OAuth 2.0 client credentials flow for service-to-service. API keys with HMAC request signing for simpler integrations. Mutual TLS (mTLS) for high-security custodian and clearing connections. Role-based access control scoped to accounts, operations (read-only vs read-write), and data sensitivity levels. Token expiration and rotation policies must be automated -- expired credentials are a leading cause of integration outages.

Integration testing: Financial API integrations require dedicated testing environments (UAT/sandbox) that mirror production behavior including realistic data volumes, error scenarios, and latency characteristics. Contract testing (verifying both producer and consumer conform to the API specification) prevents integration regressions during independent deployments. Custodians and data vendors typically provide certification environments; completing certification is a prerequisite for production connectivity. Maintain a suite of integration tests that exercise the happy path, each documented error code, timeout behavior, pagination boundaries, and rate limit responses.

2. FIX Protocol

The Financial Information eXchange (FIX) protocol is the dominant messaging standard for electronic trading, connecting buy-side firms, sell-side firms, exchanges, ECNs, and alternative trading systems.

Protocol structure: FIX messages are sequences of tag=value pairs delimited by SOH (ASCII 0x01). Each message has a header (BeginString, BodyLength, MsgType, SenderCompID, TargetCompID, MsgSeqNum, SendingTime), a body (message-type-specific fields), and a trailer (CheckSum). Tags are numeric (e.g., Tag 35 = MsgType, Tag 55 = Symbol, Tag 44 = Price, Tag 38 = OrderQty).

Session layer: Manages connectivity, sequencing, and recovery. Logon (MsgType=A) establishes the session with sequence number synchronization. Heartbeat (MsgType=0) and TestRequest (MsgType=1) monitor connection health. ResendRequest (MsgType=2) and SequenceReset (MsgType=4) handle gap recovery after disconnection. Logout (MsgType=5) terminates the session. Sequence numbers are strictly monotonic per session per direction; gaps trigger automatic recovery.

Key application messages: NewOrderSingle (MsgType=D) submits an order. ExecutionReport (MsgType=8) reports fills, partial fills, cancellations, and rejects. OrderCancelRequest (MsgType=F) and OrderCancelReplaceRequest (MsgType=G) modify or cancel orders. MarketDataRequest (MsgType=V) subscribes to market data. MarketDataSnapshotFullRefresh (MsgType=W) and MarketDataIncrementalRefresh (MsgType=X) deliver market data.

FIX versions: FIX 4.2 remains widely deployed for equity order routing. FIX 4.4 added improved support for multi-leg instruments, allocations, and position management. FIX 5.0 (with FIXT 1.1 transport) decoupled the session and application layers, enabling transport independence and versioned application messages. Most new implementations target FIX 4.4 or FIX 5.0/FIXT 1.1 depending on counterparty requirements.

FIX engines and libraries: QuickFIX (open-source, C++/Java/.NET/Python), QuickFIX/J (Java), Chronicle FIX (low-latency Java), Cameron FIX (commercial), Onix FIX (commercial, high performance). The engine handles session management, message parsing, sequencing, and persistence. Application logic connects via callbacks (onMessage handlers per message type).

FIX connectivity management: Each counterparty requires a separate FIX session with agreed-upon CompIDs, message versions, custom tags, and testing in UAT before production. Managing 20-50 FIX sessions across brokers, exchanges, and custodians is a material operational burden. Use a FIX hub or order management system to centralize session management.

Custom tags and extensions: Counterparties frequently require custom FIX tags (tag numbers above 5000) for proprietary fields -- internal order IDs, strategy codes, clearing instructions, or regulatory identifiers. Document all custom tags per counterparty in the FIX specification agreement. Validate inbound custom tags against the agreed specification to detect schema drift.

Drop copy sessions: A drop copy (FIX session type) provides a real-time copy of all execution reports to a secondary consumer (risk system, compliance, middle office) without affecting the primary trading session. Drop copies are essential for firms that need real-time trade surveillance or independent position tracking alongside the OMS.

FIX performance considerations: For high-frequency trading, FIX message parsing and serialization latency matters. Binary FIX encodings (SBE -- Simple Binary Encoding, used with FIX 5.0 FIXT) reduce parsing overhead by orders of magnitude compared to text-based FIX. For typical buy-side order routing (hundreds to thousands of orders per day), text-based FIX 4.4 is more than adequate and far simpler to debug -- log files are human-readable.

Allocation and post-trade via FIX: FIX supports post-trade workflows beyond order execution. Allocation messages (MsgType=J, AllocationInstruction) communicate how a block trade should be split across accounts. AllocationReport (MsgType=AS) confirms allocation processing. Confirmation (MsgType=AK) provides trade-level detail per allocation. These post-trade messages are increasingly important under T+1, where allocations must be communicated within hours of execution rather than the following morning.

3. ISO 20022 Messaging

ISO 20022 is the XML-based financial messaging standard replacing legacy formats across payments, securities, trade finance, and foreign exchange. SWIFT's migration from MT (Message Type) to ISO 20022 MX messages for cross-border payments completed in November 2025.

Message structure: ISO 20022 messages use XML schemas organized into business domains. Each message has a Business Application Header (BAH) containing sender, receiver, message type, and creation date, followed by the business document. Messages are identified by four-character codes within domain categories.

Domain categories: pain (payments initiation), pacs (payments clearing and settlement), camt (cash management), semt (securities management -- statements, balances), setr (securities trade -- order, confirmation), sese (securities settlement -- instruction, confirmation, status), secl (securities clearing), colr (collateral management), reda (reference data).

Key message types:

| Message ID | Name | Use Case | |---|---|---| | semt.002 | Custody statement of holdings | End-of-day position reporting from custodian | | semt.017 | Securities statement of transactions | Transaction history from custodian | | setr.004 | Redemption order | Mutual fund redemption instruction | | setr.010 | Subscription order | Mutual fund subscription instruction | | sese.023 | Securities settlement transaction instruction | Delivery/receipt instruction to depository | | sese.024 | Securities settlement status advice | Settlement status updates (matched, settled, failed) | | pacs.008 | FI to FI customer credit transfer | Cross-border payment instruction | | pacs.009 | FI to FI financial institution credit transfer | Interbank transfer | | camt.053 | Bank-to-customer statement | Cash account statement |

SWIFT migration status (as of June 2026): SWIFT ran MT/MX coexistence for cross-border payments from March 2023 and completed the migration on November 22, 2025. ISO 20022 (CBPR+) is now the exclusive standard for cross-border payment instructions between financial institutions; the network rejects legacy MT payment instruction messages (e.g., MT103, MT202). Securities messaging migration follows on a separate, later timeline, so MT securities messages (MT535, MT548) remain in use. Firms with internal MT-based processing must translate at the boundary; note that translating from the richer ISO 20022 format back to constrained MT fields can lose information.

Comparison with legacy formats: MT messages use fixed-field structures with limited field lengths (MT103 for customer transfers, MT202 for bank transfers, MT535 for custody statements, MT548 for settlement status). ISO 20022 provides richer, structured data -- longer reference fields, structured addresses, LEI support, purpose codes, and remittance information. ISO 15022 (the predecessor for securities) used a tagged format similar to SWIFT MT; ISO 20022 replaces both.

Implementation considerations: ISO 20022 messages are verbose (10-50x larger than equivalent MT messages). XML parsing overhead is non-trivial at high volumes. Schema validation is essential to catch malformed messages before processing. Many firms implement a canonical internal format and translate to/from ISO 20022 at integration boundaries rather than processing ISO 20022 natively throughout.

Testing and certification: SWIFT requires participants to complete a readiness assessment and certification testing before migrating to ISO 20022. Testing covers message format compliance, field population rules, character set handling (ISO 20022 supports extended UTF-8 characters that MT formats did not), and end-to-end transaction flow validation. With payments coexistence ended (November 2025), parallel MT/MX processing is now only required for message categories still on legacy formats, such as securities messaging.

4. Event-Driven Architecture

Event-driven architecture (EDA) decouples financial system components by communicating through events rather than direct API calls, enabling real-time propagation of trade executions, settlement status changes, corporate actions, and reference data updates.

Core patterns: Publish-subscribe (producers emit events to topics; consumers subscribe independently), event streaming (ordered, durable log of events that consumers read at their own pace), event sourcing (the system's state is derived from a sequential log of events rather than stored as mutable records).

Financial event types: Trade events (order submitted, order acknowledged, partial fill, full fill, cancel, reject), settlement events (instruction sent, matched, settled, failed), corporate action events (announcement, election deadline, ex-date, pay-date), reference data events (new security created, identifier changed, price updated), account events (opened, restricted, closed), compliance events (alert triggered, alert resolved).

Message brokers in finance:

| Broker | Strengths | Common Use Case | |---|---|---| | Apache Kafka | High throughput, ordered log, replay, partitioning | Trade event streaming, audit trails, position updates | | Solace | Financial-grade messaging, multi-protocol (JMS, AMQP, MQTT, REST) | Market data distribution, cross-region messaging | | RabbitMQ | Flexible routing, AMQP 0-9-1, simple operations | Task queuing, request-reply, exception processing | | TIBCO EMS/FTL | Enterprise middleware, legacy integration | Capital markets, mainframe connectivity | | IBM MQ | Transactional, exactly-once, banking-grade reliability | Banking payments, high-value transaction messaging |

Selection depends on throughput requirements, ordering guarantees, existing infrastructure, and operational expertise. Kafka dominates new builds in capital markets and asset management; IBM MQ and TIBCO remain entrenched in banking and clearing.

Event sourcing for audit trails: Financial regulations require complete, immutable audit trails. Event sourcing naturally produces these -- every state change is an appended event with timestamp, actor, and payload. Reconstructing the state of an account, position, or order at any point in time requires replaying events up to that timestamp. This aligns with books-and-records requirements (SEC Rule 17a-4, FINRA Rule 4511).

CQRS for financial systems: Command Query Responsibility Segregation separates write operations (trade booking, settlement instruction) from read operations (position queries, reporting). Financial systems are heavily read-biased -- hundreds of report consumers per trade writer. CQRS allows optimizing read models independently (materialized views, denormalized for specific query patterns) while maintaining a strict, auditable write path.

Event schema design and evolution: Financial events require careful schema design. Include metadata (event ID, timestamp, source system, correlation ID, schema version) and business payload (trade details, settlement status, account attributes). Schema evolution must be backward-compatible -- new consumers must handle old events, and old consumers must tolerate new fields. Use a schema registry (Confluent Schema Registry, AWS Glue) to enforce compatibility checks at publish time. Breaking schema changes require a new topic or versioned event types with parallel consumption during migration.

Ordering guarantees: Financial event ordering is critical. A fill event processed before its corresponding order-acknowledged event corrupts state. Kafka provides ordering within a partition -- partition by the key whose ordering matters most (account ID for position updates, order ID for order lifecycle). Cross-partition ordering requires application-level sequencing (timestamps, sequence numbers) and handling out-of-order delivery.

Consumer failure and recovery: When a Kafka consumer fails and restarts, it resumes from its last committed offset. If the consumer had processed a message but crashed before committing the offset, it will reprocess that message on restart -- requiring idempotent processing. For financial consumers, the standard pattern is: (1) process the message, (2) write the result and the message offset to the database in a single transaction, (3) commit the Kafka offset. If step 3 fails, the message is reprocessed but the database transaction detects the duplicate via the stored offset and skips reprocessing.

5. Batch Processing Patterns

Despite the trend toward real-time processing, batch file exchange remains the dominant integration pattern between advisory firms and custodians, fund administrators, transfer agents, and data vendors.

Common batch file types: Position files (end-of-day holdings per account), transaction files (trades, income, fees, corporate actions), cash balance files, performance return files, billing files, reconciliation files, reference data files (security master updates, pricing), tax lot files.

| File Type | Typical Frequency | Typical Delivery Window | Critical Deadline | |---|---|---|---| | Position file | Daily | 1:00-4:00 AM ET | Before morning portfolio review | | Transaction file | Daily | 1:00-4:00 AM ET | Before reconciliation run | | Cash balance file | Daily | 2:00-5:00 AM ET | Before cash management | | Pricing file | Daily | 6:00-8:00 PM ET (prior evening) | Before overnight valuation | | Tax lot file | Daily or weekly | 2:00-6:00 AM ET | Before tax reporting | | Reconciliation file | Daily | 3:00-6:00 AM ET | Before operations review | | Corporate action file | Event-driven + daily | Varies | Before ex-date processing |

File formats: CSV (most common for custodian feeds; column order varies per custodian), fixed-width (legacy format still used by some custodians and clearing firms; column positions defined by specifications), XML (increasingly used for richer data; ISO 20022-aligned for securities), JSON (emerging for modern API-based file delivery), proprietary (vendor-specific formats requiring dedicated parsers).

File delivery mechanisms: SFTP (dominant; scheduled push or pull), S3/cloud storage (growing adoption for custodian feeds), API-based file download (polling for new files via REST), MQ/message-based (file notification triggers pickup), email with encrypted attachments (legacy, declining). All file transfers should use encryption in transit (SFTP inherently provides this; S3 requires HTTPS; FTP without TLS is never acceptable for financial data). PGP/GPG encryption of file contents provides an additional layer, ensuring confidentiality even if the transport is compromised or the file is stored in an intermediate staging area.

Processing pipeline stages: (1) File monitoring -- detect file arrival, verify expected files received by deadline; (2) File validation -- checksum verification, record count validation against trailer, schema validation, character encoding check; (3) Parsing -- extract records into structured format, handle format variations per source; (4) Business validation -- referential integrity (accounts exist, securities exist), value range checks, cross-field consistency; (5) Transformation -- map to canonical format, translate identifiers, enrich from reference data; (6) Loading -- insert/update target system, handle duplicates; (7) Reconciliation -- compare loaded data against source counts and control totals.

Sequence numbers and idempotent loading: Custodian files include sequence numbers or file dates. Track the last processed sequence per source to detect gaps (missing files) and duplicates (reprocessed files). Design loading to be idempotent -- reprocessing the same file produces the same result without double-counting.

Batch vs real-time trade-offs: Batch provides simplicity, natural checkpoints, and alignment with EOD reconciliation cycles. Real-time provides immediacy but adds complexity (state management, error recovery, ordering guarantees). Most firms use a hybrid: real-time for order flow and trade execution, batch for EOD positions, reconciliation, and reporting.

Late file and missing file handling: Define SLAs for file arrival per source with escalation procedures. Track file arrival history to establish normal delivery windows and detect anomalies. When a file is late, the pipeline must decide: wait (delaying all downstream processing), proceed without (risk incomplete data), or use the prior day's data with a stale-data flag. The choice depends on the file's criticality -- a missing position file blocks portfolio reporting; a missing billing file can be processed the next day.

File redelivery and corrections: Custodians and counterparties occasionally redeliver corrected files. The pipeline must support reprocessing: detect the redelivered file (same date, updated sequence or timestamp), back out the original load, and apply the corrected data. This requires the original load to be reversible -- either through soft deletes with version tracking or through full replacement keyed on file date and source.

6. Idempotency and Exactly-Once Semantics

Financial transactions demand exactly-once processing. A duplicated order submission, a repeated settlement instruction, or a double-posted dividend creates real monetary errors that are expensive to detect and correct.

Why idempotency matters: Networks are unreliable -- TCP connections drop, HTTP requests time out, message brokers redeliver. The caller often cannot distinguish "the request failed" from "the request succeeded but the response was lost." Without idempotency, retrying a timed-out order submission may create a duplicate order.

Idempotency key design: The client generates a unique key per logical operation (UUID, or a deterministic composite key such as account + security + side + quantity + timestamp). The server stores the key with the result. On receiving a duplicate key, the server returns the stored result without re-executing. Keys must have a defined TTL (hours to days) to bound storage. For financial operations, composite keys incorporating business attributes (order ID, trade reference, settlement instruction ID) are preferred over random UUIDs because they enable deduplication even across retries from different client instances.

Duplicate detection patterns:

1. Server-side idempotency table (key, result, expiry) checked before processing -- the most common pattern for REST APIs.
2. Database unique constraints on business keys preventing duplicate inserts -- simple and reliable for database-backed operations.
3. Message broker deduplication (Kafka exactly-once semantics via idempotent producers and transactional consumers) -- handles the broker-to-consumer path.
4. Distributed locks for operations that span multiple systems -- heavyweight but necessary when a single operation writes to multiple datastores.
5. Content-based deduplication (hash of the message payload) -- useful as a secondary check when idempotency keys are not available from the source.

At-least-once delivery with idempotent processing: The practical pattern for financial systems. Message brokers guarantee at-least-once delivery (messages may be delivered more than once on failure/retry). Consumers are designed to be idempotent -- processing the same message twice has no additional effect. This provides effectively exactly-once semantics without the complexity and performance cost of true distributed exactly-once protocols.

Replay safety: Idempotent systems support safe replay of event streams for recovery, migration, or reconciliation. An operations team can reprocess a day's transactions to reconcile without fear of double-booking. This is essential for financial audit and exception resolution.

Idempotency across system boundaries: When an integration spans multiple systems (e.g., submitting a trade to a broker and booking it internally), the idempotency key must be consistent across both systems. If the broker acknowledges the trade but the internal booking times out, a retry must use the same key for both the broker re-query ("did my order already execute?") and the internal booking attempt. Design the idempotency key at the business operation level, not the individual API call level.

7. Error Handling and Resilience

Financial integrations must handle failures gracefully because downstream consequences are severe -- a missed settlement instruction causes a fail, a dropped trade confirmation creates a reconciliation break, a lost corporate action notification causes incorrect processing.

Retry strategies: Immediate retry for transient errors (network timeout, HTTP 503). Exponential backoff with jitter for sustained unavailability (base delay * 2^attempt + random jitter). Cap retry count and total duration. Classify errors as retryable (timeout, 429, 503, connection reset) vs non-retryable (400, 401, 403, 422). Never retry non-idempotent operations without idempotency keys.

Circuit breaker pattern: Prevent cascading failures when an upstream system is down. Three states govern behavior:

• Closed (normal): requests pass through to the upstream system. Failures are counted.
• Open (tripped): all requests fail immediately without contacting the upstream system. This protects both the caller (no wasted timeout waits) and the upstream (no additional load during recovery).
• Half-open (testing): after a configurable timeout, a limited number of requests are allowed through to test whether the upstream has recovered.

Transition thresholds: open after N consecutive failures or error rate exceeding X% within a window; half-open after a configurable cooldown period; closed after N consecutive successes in half-open state. In financial systems, circuit breakers protect trading platforms from failing custodian connections and prevent settlement systems from overwhelming a degraded clearing interface. When a circuit breaker trips, the integration must have a defined fallback behavior -- queue messages for later delivery, serve cached data, or alert operations for manual intervention.

Dead letter queues (DLQ): Messages that fail processing after all retries are routed to a DLQ rather than discarded. The DLQ preserves the message with failure metadata (error reason, attempt count, timestamps). Operations staff review, diagnose, and reprocess or manually resolve DLQ items. DLQs are critical in financial operations -- a discarded settlement instruction is far worse than a delayed one. Monitor DLQ depth as a key operational metric.

Compensating transactions: When a multi-step process partially completes and a later step fails, compensating transactions undo the earlier steps. Example: an order routed to a broker and acknowledged, but the internal booking fails -- the compensating transaction cancels the broker order. Design compensating actions for every step in a multi-system workflow. Unlike database rollbacks, compensating transactions are new forward actions (a cancel, a reversal, a credit) and may themselves fail, requiring monitoring and manual resolution.

Timeout management: Set timeouts at every integration boundary. Connect timeout (seconds), read timeout (seconds to minutes depending on operation), and end-to-end timeout for multi-step workflows. In financial systems, timeout values must account for market-hours load, end-of-day processing peaks, and custodian batch windows.

Partial failure handling: Multi-record operations (batch order submission, bulk position update) must handle partial success. If 95 of 100 records succeed and 5 fail, the system must report which records succeeded, which failed and why, and whether the 5 failures can be retried independently. Never silently drop failures in a batch -- return a detailed result manifest per record. In financial operations, a missing record in a batch response is indistinguishable from a lost transaction without explicit per-record acknowledgment.

Monitoring and alerting: Track integration health metrics: message throughput (messages per second per channel), error rate (percentage of failed messages), latency (end-to-end from source event to target system update), queue depth (backlog size per consumer), and DLQ depth (unresolved failures). Set alerts with severity tiers: warning (elevated error rate), critical (integration down or DLQ threshold exceeded), and emergency (data loss risk). Dashboard visibility into integration health is as important as the integration itself.

8. Data Transformation and Mapping

Financial system integration invariably requires transforming data between different schemas, identifier systems, code sets, and conventions.

Field mapping: Source-to-target mapping documents define how each field in the source system maps to the target. Financial field mappings are frequently non-trivial: a single source field may map to multiple target fields (a combined name field split into first/last), multiple source fields may combine into one target field, and some fields require lookup or derivation. Maintain mapping specifications as versioned artifacts -- they are the integration contract.

Identifier translation: The same security may be identified by CUSIP in one system, ISIN in another, and a proprietary ID in a third. Integration layers maintain cross-reference tables (sourced from the security master) to translate identifiers. Always translate through the canonical internal ID rather than directly between external identifiers to avoid N-to-N mapping complexity.

Currency and code normalization: Standardize currency codes to ISO 4217 (USD, EUR, GBP). Country codes to ISO 3166 (US, GB, DE). Transaction type codes vary wildly between systems -- map to a canonical code set and maintain per-source translation tables. Date formats (YYYYMMDD, MM/DD/YYYY, ISO 8601) must be normalized early in the pipeline.

Enrichment from reference data: Inbound data frequently lacks fields required by the target system. Enrich during transformation by looking up the security master (asset class, sector, issuer), client master (household, advisor), or account master (registration type, tax status). Enrichment creates a runtime dependency on reference data availability -- design for graceful degradation if reference data is temporarily unavailable (queue the record for retry rather than failing the entire batch).

Handling unmapped values: Integration pipelines inevitably encounter source values that have no mapping in the translation table -- a new custodian transaction code, an unrecognized security type, a country code variant. The pipeline must not silently discard or default these values. Route unmapped records to an exception queue, log the unmapped value for steward review, and add the new mapping to the translation table once resolved. Track the frequency of unmapped values per source as a data quality metric -- a spike indicates a source system change that requires mapping table updates.

Canonical data model: Define a firm-wide canonical representation of key entities (trade, position, account, security, client). All integrations translate source data into the canonical model at the boundary, and translate out to target-specific formats at the other boundary. This reduces integration complexity from N-to-N to N-to-1-to-N, dramatically simplifying the addition of new systems and data sources.

Data type conversions: Financial data types require careful conversion. Decimal precision matters -- monetary amounts should use fixed-point decimal (not floating-point) to avoid rounding errors. Quantity fields may be fractional for mutual funds and whole for equities. Date/time fields must carry timezone context (a trade timestamp without timezone is ambiguous across international operations). Boolean fields vary in representation (Y/N, true/false, 1/0, T/F) and must be normalized at the boundary.

9. Security and Compliance for Integrations

Financial integration infrastructure handles sensitive data (PII, account numbers, positions, transactions) and is subject to regulatory requirements for data protection, auditability, and access control.

Transport security: TLS 1.2 or 1.3 for all data in transit. Mutual TLS (mTLS) for custodian, clearing, and counterparty connections -- both parties present certificates, providing strong bilateral authentication. Certificate management (issuance, rotation, revocation, expiry monitoring) is a critical operational function; expired certificates are a top cause of integration outages.

Data encryption at rest: Encrypt all persisted integration data (message stores, file staging areas, DLQs, audit logs) using AES-256 or equivalent. Key management via HSM or cloud KMS. Encryption applies to both production and non-production environments -- test data derived from production contains real PII and account data unless explicitly anonymized.

PII handling: Integration payloads frequently contain SSN/TIN, dates of birth, account numbers, and financial details. Minimize PII in transit -- transmit only what the receiving system requires. Mask or tokenize sensitive fields in logs and monitoring dashboards. Apply data classification labels to integration channels (public, internal, confidential, restricted) and enforce controls accordingly.

Audit logging: Log every integration event: message sent, message received, transformation applied, validation passed/failed, error encountered, retry attempted, manual intervention. Include timestamp, source system, target system, message identifier, correlation ID, and outcome. Retain logs per the firm's books-and-records policy (typically 6-7 years for broker-dealers under SEC Rule 17a-4, 5 years for investment advisers under SEC Rule 204-2). Audit logs must be immutable -- write-once storage or append-only systems.

Correlation IDs and distributed tracing: A single business operation (e.g., processing a client trade from order entry through settlement) may traverse 5-10 systems. A correlation ID generated at the origin and propagated through every system enables end-to-end tracing of the transaction's path, timing, and outcome. Without correlation IDs, troubleshooting a failed settlement requires manually correlating timestamps across independent system logs -- a process that can take hours instead of minutes. Implement correlation ID propagation as a mandatory standard across all integration channels (HTTP headers, FIX custom tags, message metadata, file record fields).

SOC 2 controls: Integration infrastructure falls within the scope of SOC 2 Type II audits. Relevant controls include access management (who can configure integrations, deploy changes, access production data), change management (integration changes follow the firm's SDLC with testing and approval), availability (monitoring, alerting, failover), and confidentiality (encryption, access logging, data classification). Third-party integration vendors (iPaaS, middleware) must provide their own SOC 2 reports.

Non-production environment security: Integration testing environments frequently use production-derived data for realistic testing. This data contains real PII and financial information. Non-production environments must either use fully anonymized/synthetic data or implement the same access controls and encryption as production. Regulators and auditors specifically examine non-production data handling during examinations.

Worked Examples

Three end-to-end design scenarios (multi-custodian RIA integration architecture, event-driven trade notification with Kafka, resilient EOD settlement batch pipeline) are in references/examples.md. Load that file when designing a concrete integration or when the user asks for a worked architecture example.

Common Pitfalls

• No idempotency on financial transaction APIs. Retrying a timed-out order submission or settlement instruction without an idempotency key creates duplicates that cause real monetary errors.
• Treating batch file processing as simple file loading. Skipping checksum validation, record count verification, and sequence number tracking allows corrupted, truncated, or duplicate files to silently corrupt the book of record.
• Point-to-point integrations between every system pair. N systems with direct connections create N*(N-1)/2 integrations. A canonical data model with a central integration layer reduces this to N connections.
• Ignoring FIX sequence number management. FIX session recovery depends on correct sequence number persistence. Resetting sequence numbers without coordination with the counterparty causes message loss or duplicate processing.
• Polling instead of event-driven for time-sensitive data. Polling introduces latency equal to half the polling interval on average, wastes resources on empty polls, and misses events during polling gaps.
• No dead letter queue for failed messages. Discarding messages that fail processing (rather than routing to a DLQ) creates silent data loss. In financial operations, a missing settlement instruction is far worse than a delayed one.
• Hardcoding identifier types in integration logic. Assuming all securities have CUSIPs, or that CUSIPs never change, causes breakage for international securities and during corporate actions. Always translate through the security master.
• Insufficient timeout configuration. Default HTTP timeouts (30 seconds, 60 seconds) are often inappropriate for financial operations -- bulk position queries may legitimately take minutes, while order submissions should fail fast.
• Neglecting certificate expiry monitoring for mTLS connections. Expired certificates cause immediate, total integration failure. Automated monitoring with 30/14/7-day advance alerts is essential.
• Processing ISO 20022 messages without schema validation. Malformed XML that passes basic parsing but violates the ISO 20022 schema can cause subtle data corruption downstream.
• No compensating transaction design for multi-step workflows. When step 3 of a 5-step process fails, the system must undo steps 1 and 2. Without pre-designed compensating transactions, manual intervention is the only recovery path.
• Logging PII in integration debug logs. SSNs, account numbers, and financial data appearing in application logs violate data protection requirements and create regulatory exposure during examinations.

Cross-References

• reference-data (Layer 13, data-integration) -- Reference data is the foundation that integrations distribute; security master, client master, and account master provide the identifiers and attributes that integration payloads carry.
• market-data (Layer 13, data-integration) -- Market data feeds are a primary integration domain; real-time and delayed data distribution uses many of the same patterns (pub-sub, fan-out, conflation) described here.
• data-quality (Layer 13, data-integration) -- Integration failures are a leading source of data quality issues; validation, monitoring, and exception handling at integration boundaries are the first line of defense.
• settlement-clearing (Layer 11, trading-operations) -- Settlement relies on inter-system messaging between clearing firms, custodians, and depositories; settlement instruction delivery uses FIX, ISO 20022, and batch file patterns.
• exchange-connectivity (Layer 11, trading-operations) -- Exchange connectivity uses FIX protocol for order routing and market data; this skill covers FIX at the protocol level while exchange-connectivity covers the operational and regulatory context.
• order-lifecycle (Layer 11, trading-operations) -- Order flow across systems (OMS to broker to exchange) requires reliable integration with sequencing, acknowledgment, and error handling.
• stp-automation (Layer 12, client-operations) -- STP depends on well-designed integrations; STP rate is directly constrained by the reliability and data quality of upstream integration feeds.
• portfolio-management-systems (Layer 10, advisory-practice) -- PMS is a hub consuming data from many integrations (custodian positions, market data, reference data, trade confirmations) and is the primary beneficiary of robust integration architecture.
• books-and-records (Layer 9, compliance) -- Integration audit trails (message logs, file processing records, transformation history) are regulatory records subject to retention and examination requirements.