Building a connector abstraction layer

Every payment platform ends up with a connector abstraction layer — a set of interfaces that hide the differences between acquirers, schemes, and payment method providers behind a uniform internal API. Every second-generation payment platform ends up rewriting the first version of that layer, because the first version made assumptions that didn't survive.

Written August 2026 from platform architecture reviews.

What the layer is for

• Uniform request/response shape across otherwise-different providers.
• Contract-specific behavior encapsulated behind a stable interface.
• Explicit capability advertisement — some connectors support reversal, some don't; some support idempotency keys, some don't.
• Consistent error taxonomy — every connector's errors mapped to a shared set.

The design choices that matter

• Capability contracts, not feature flags. Each connector declares what it supports as a set of capabilities. Business logic checks capabilities; it never checks connector names.
• Explicit "unknown" in the error taxonomy. The shared error set must include an "outcome unknown" case, not just success and failure.
• Idempotency-key format owned by the abstraction. Not passed through from callers. The layer generates and manages keys.
• Replay of connector-level responses. Every raw connector response is preserved as an event, so a caller reviewing an anomaly six months later can see exactly what the connector said.

The mistakes that produce a rewrite

• Assuming every connector supports the same set of operations.
• Overloading the abstraction with merchant-specific business rules.
• Treating "reversal" as universal when it's contract-specific.
• Building the abstraction around a single connector's message model.

The connector layer is boring, foundational work. Doing it right is the difference between a platform that adds connectors in weeks and one that adds them in quarters.