Designing a Payment Orchestration Layer

The Need for Payment Orchestration

As a system integrates with multiple payment service providers (PSPs) or payment methods, the codebase often becomes riddled with conditional logic (e.g., `if provider == "X"`) to handle provider-specific nuances. This complexity extends to refunds, webhooks, reconciliation, and fraud checks, making new integrations cumbersome and error-prone. Payment orchestration addresses this by introducing an abstraction layer.

Core Components of a Payment Orchestration System

• Normalized Payment Model: Defines a single, consistent API for `Charge`, `Refund`, `Payout` actions, standardizing currency representation, status vocabularies, and error taxonomies across all providers. This prevents provider-specific quirks from leaking into business logic.
• Routing Layer: Intelligently directs transactions to the appropriate provider based on rules like least cost, best authorization rate, or geographical presence. It also handles retries, cascades on soft declines, and implements circuit breakers.
• Retry & Cascade Engine: Manages idempotency keys across providers, handles bounded re-attempts for transient failures, and understands decline codes to prevent inappropriate retries (e.g., retrying a stolen card).
• Webhook Fan-in: Aggregates and normalizes asynchronous callbacks from multiple providers into a single, de-duplicated, ordered event stream, ensuring reliable event processing.
• Reconciliation Spine: Links payment attempts, authorizations, captures, and settlement files to the internal ledger, identifying mismatches and enabling accurate financial reporting and dispute resolution.

Architecting the Provider-Agnostic Boundary

A crucial architectural decision is designing a simple, money-shaped interface that all provider adapters must implement. This ensures a consistent interaction model regardless of the underlying payment gateway. Key design rules include using minor units (integers/bigints) for all monetary values to avoid floating-point issues, and maintaining an internal, unified decline-code taxonomy that provider-specific codes are mapped to.

type Money = { amountMinor: bigint; currency: string };
interface PaymentProvider {
  readonly id: string;
  authorize(req: AuthorizeRequest): Promise<AuthorizeResult>;
  capture(authId: string, amount: Money, idemKey: string): Promise<CaptureResult>;
  refund(captureId: string, amount: Money, idemKey: string): Promise<RefundResult>;
  parseWebhook(raw: HttpRequest): NormalizedEvent | null;
}