PayBridge

Overview

PayBridge is a systems architecture concept exploring how POS and SaaS platforms could connect to payment processors and certified payment devices through a normalized, interoperable middleware layer.

The central question PayBridge is designed to answer: what would a well-designed payment orchestration infrastructure look like if it were built specifically to address the integration complexity that POS developers face today?

This is technical exploration, not a product. The architecture is intended to surface design decisions, tradeoffs, and engineering requirements — not to ship software.

The Problem

Building a reliable POS payment integration today requires solving the same set of structural problems that every other POS developer has already solved independently:

• Processor API fragmentation. Every major payment processor exposes a different API surface, a different data model, and a different error vocabulary. Supporting multiple processors requires rebuilding normalization logic for each one.

• Device protocol diversity. Certified payment terminals — Ingenico, Verifone, PAX, and others — expose different command sets and communication protocols. Integrating a new device family often requires a new integration project from scratch.

• Offline handling complexity. Real POS environments experience network degradation. Store-and-forward transaction queuing, idempotency management, and reconnection reconciliation are well-defined problems with well-known solutions, but they must be re-implemented by each POS team.

• Transaction state ambiguity. Network timeouts during payment authorization leave the system in an ambiguous state. Handling this correctly requires careful state machine design and idempotent retry logic that is frequently absent from simpler implementations.

• Certification constraints. EMV and PCI PTS certification requirements constrain how device-side logic can be structured, creating architectural tension between certification compliance and engineering flexibility.

The result is that payment integration work does not compound across the industry. Each POS company builds its own version of the same infrastructure layer. The engineering cost is significant, and the reliability outcomes are variable.

Proposed Architecture

PayBridge proposes a three-layer architecture that separates concerns between the POS application, the orchestration layer, and the processor/device adapters.

Layer 1: Canonical Payment API

The top layer exposes a normalized, processor-agnostic API to the POS application. The application developer writes against a small set of operations:

• payment.authorize(request) — submit a payment for authorization
• payment.capture(id, amount) — capture an authorized payment
• payment.void(id) — void an authorized payment
• payment.refund(id, amount) — refund a settled payment
• payment.status(id) — retrieve the current canonical status

The canonical API surface is deliberately narrow. It covers the operations that every POS platform needs, without encoding the specific features of any processor.

Layer 2: Orchestration Core

The orchestration core is responsible for:

Processor routing. Given a payment request, the router selects the appropriate processor adapter. Routing decisions can be based on merchant configuration, card type, geographic constraints, or processor health status.

Canonical state machine. The state machine tracks every payment through its lifecycle — from CREATED through AUTHORIZED, CAPTURED, SETTLED, and terminal states. State transitions are persisted atomically before being communicated to the processor, creating a durable record.

Idempotency management. Every outbound request carries a stable idempotency key. The orchestration core handles key generation, retry logic, and timeout resolution, so individual processor adapters do not need to implement these behaviors independently.

Offline queue management. When a processor or device is unreachable, transactions are queued in a durable, ordered local store. Queue draining is controlled and idempotent — the draining process can restart without risk of duplicate submission.

Layer 3: Processor and Device Adapters

Each payment processor and payment device family is represented as an adapter — a module that translates between the canonical API and the specific integration requirements of that processor or device.

The adapter interface is narrow, defined by the canonical API:

interface ProcessorAdapter {
  processorId: string
  authorize(request: CanonicalPaymentRequest): Promise<CanonicalPaymentResult>
  capture(id: string, amount: number): Promise<CanonicalPaymentResult>
  void(id: string): Promise<CanonicalPaymentResult>
  refund(id: string, amount: number): Promise<CanonicalPaymentResult>
  getStatus(id: string): Promise<CanonicalPaymentResult>
}

The adapter is responsible for:

• Translating canonical request fields to the processor's expected format
• Translating processor response fields to the canonical response model
• Mapping processor-specific error codes to canonical error codes
• Handling processor-specific authentication and request signing

The processor adapter is the only part of the system that knows about a specific processor. All other components work exclusively with canonical types.

Key Innovation Areas

1. Payment Orchestration Architecture

The orchestration layer introduces a routing and normalization mechanism that allows POS platforms to support multiple processors without duplicating integration logic. The key design decision is the canonical model — a data model that is expressive enough to represent the operations needed by any POS application, without encoding the specifics of any single processor.

This is analogous to the database adapter pattern in application frameworks: the application writes against a normalized interface, and adapters handle the specifics of each underlying system.

2. Normalized Payment State Machine

Payment transactions have a well-defined lifecycle. The PayBridge state machine makes that lifecycle explicit and enforces it programmatically. Every transition is defined. Invalid transitions are rejected. The state of every payment is always unambiguous.

The state machine also handles the difficult edge cases — timeouts, duplicate requests, partial failures — in a centralized place, so these problems do not need to be solved independently by each adapter.

CREATED ──► AUTHORIZED ──► CAPTURED ──► SETTLED
   │             │               │
   ▼             ▼               ▼
 FAILED        VOIDED         REFUNDED

3. Hybrid Device-Cloud Payment Execution

Card-present payments require coordination between a certified payment terminal and a backend service. This coordination is non-trivial: the terminal performs card reading, PIN collection, and cryptographic processing; the backend handles authorization requests, state persistence, and settlement.

PayBridge proposes a device coordination layer that abstracts over device-specific communication protocols — presenting a uniform interface for terminal operations regardless of the underlying device family. The coordination layer manages the stateful dialogue between the terminal and the backend, handling interruptions and resumption cleanly.

4. Offline-Capable Transaction Handling

The offline queue is a first-class component of the PayBridge architecture. Key properties:

• Durable storage: Transactions are written to stable storage and fsync'd before acceptance
• Idempotency keys at origination: Keys are generated when the transaction is created, not when it is submitted
• Ordered draining: Queue entries are submitted in the order they were received
• Safe restart: The draining process is idempotent and can restart at any point without risk of duplicate submission
• Status resolution: TIMEOUT-state transactions are resolved via idempotent retry or explicit status query before the queue advances

Why It Matters

The cumulative engineering cost of fragmented payment infrastructure is significant and largely invisible. It shows up as:

• Repeated integration projects, each building the same foundational layer
• Maintenance burden as processor APIs change
• Reliability gaps in edge-case handling (timeouts, offline scenarios, duplicate detection)
• Difficulty onboarding new processors as a platform scales

If this infrastructure were shared — a well-designed, maintained, open layer that POS companies could build on — the engineering effort currently spent on foundational integration work could be redirected toward differentiated features.

PayBridge is an attempt to design that layer carefully: to specify the canonical model, the adapter interface, the state machine, and the operational requirements in enough detail that the result would be something trustworthy, not just plausible.

Future Exploration

The architecture described here raises several questions that warrant deeper investigation:

Governance of the canonical model. Who decides when the canonical model needs to evolve? How are breaking changes managed? A shared infrastructure layer requires governance that proprietary implementations do not.

Certification boundaries. EMV and PCI PTS certification requirements constrain how device-side logic can be structured. A device coordination layer that abstracts over device families must do so within certification constraints — an architectural requirement that is not well-documented in the public literature.

Settlement reconciliation. The canonical state machine tracks authorization and capture, but settlement happens asynchronously through the card networks. A complete payment orchestration architecture must include reconciliation tooling that matches canonical state records against processor settlement reports.

Multi-party payment flows. Platforms that involve multiple merchants (marketplaces, SaaS platforms with sub-merchants) require payment flows that a POS-centric canonical model does not naturally address. Extending the architecture to cover split payments and sub-merchant flows is a meaningful research direction.

PayBridge is a technical architecture concept. It is a systems design exercise, not a commercial product or operating service.