Gateway Patterns for Payment Integrations

Six months after our initial payment gateway integration, our provider changed their pricing. Significantly. We had to migrate to a new gateway under time pressure. The only reason this was survivable was the adapter pattern we'd implemented from the start.

The adapter pattern

Instead of calling the payment gateway directly from our application code, we built a thin abstraction layer. Our application talks to a PaymentService interface. The interface has methods like authorize, capture, refund, and void. Behind the interface, a gateway-specific adapter translates these calls to the provider's API.

When we switched gateways, we wrote a new adapter. The application code didn't change at all. Zero changes to business logic, zero changes to the frontend, zero changes to the database schema.

Why most teams skip this

It feels like over-engineering on day one. When you're integrating your first gateway under deadline pressure, building an abstraction layer seems like premature optimization. I get it. But the cost of the abstraction is maybe 2-3 days upfront. The cost of not having it when you need to switch is 2-3 months.

"We'll never switch providers." I've heard this on every payments project I've managed. Every single team has eventually switched or added a second provider. Build the adapter.

Implementation details that matter

Normalize error responses. Different gateways return errors differently. Your adapter should translate gateway-specific errors into your standard error taxonomy. This prevents gateway-specific error handling from leaking into your application.

Idempotency at the adapter level. Each adapter should handle idempotency keys according to the specific gateway's requirements. Your application shouldn't need to know how each gateway implements idempotency.

Logging and audit trails. Log every gateway interaction at the adapter level. Raw request, raw response, timestamp, duration. When disputes happen — and they will — this audit trail is invaluable.

Build the abstraction. Future you will be grateful.