API Versioning in Payment Systems
What Is API Versioning?
API versioning is the practice of maintaining multiple stable versions of an API simultaneously, allowing existing integrations to continue functioning unchanged as the underlying API evolves. Each version represents a documented, stable contract: the request schema, response structure, authentication method, and error codes will not change within that version's supported lifetime. Clients integrate against a specific version and are unaffected by changes to other versions.
In payment systems, API versioning carries exceptional commercial weight. A payment integration is a critical path system that, if disrupted, directly stops revenue. Unversioned or poorly versioned payment APIs impose invisible engineering costs: every provider update risks breaking a live integration, requiring emergency patches with all the associated testing, compliance, and operational risk.
Versioning Strategies
URI Versioning
The most common approach embeds the version identifier in the URL path: /v1/payments, /v2/authorisations. Each version is a distinct endpoint maintained independently. Deprecated versions carry explicit sunset dates—typically 12–24 months after a successor version is released—giving integrators adequate time to migrate without being forced into emergency updates.
Breaking vs. Non-Breaking Changes
Non-breaking changes include adding optional request fields, adding new response fields, introducing new endpoints, and adding new enum values. Breaking changes include removing required or optional fields, changing data types, altering authentication requirements, or modifying response schema structure. A mature versioning policy defines this boundary explicitly—ambiguity here is a support cost multiplier and a trust-eroding experience for API consumers.
The Hidden Cost of PSP API Churn
Payment service providers update their APIs frequently—adding required fields for regulatory compliance, deprecating legacy authentication schemes, updating webhook formats. For merchants integrated directly with multiple PSPs, each update is an engineering task: schema change analysis, integration update, test suite revision, and deployment. At three PSPs this is manageable; at seven it becomes a persistent drain on engineering capacity that consumes bandwidth that could be spent on product development.
How Hellgate Link Eliminates PSP API Churn
Link, Hellgate's PSP abstraction layer, is built on the principle that PSP API churn should never create merchant engineering work. Merchants integrate against Link's versioned API and are insulated from all underlying PSP API changes. When an acquirer updates a required field or changes its webhook format, Link's abstraction layer absorbs the change without any merchant-side update required.
Hub's API is independently versioned from Link's, enabling each component to evolve without forcing coordinated merchant-side upgrades. The Hellgate Developer Portal documents all API versions with explicit deprecation timelines, migration guides, and changelog entries—providing the predictability that engineering teams need to plan integration work as an optional optimisation rather than a forced emergency response.