How Does API Versioning and Change Management Work?

Payment interfaces change. Banks revise their file specification documents, providers release new API versions, and industry changes such as new DebiCheck rules or ISO 20022 migrations ripple through every integration built on them. Versioning is how those changes are introduced without breaking systems that move money every day.

For integrators, change management is not optional maintenance: a missed migration deadline can mean rejected files or failed API calls on a production collection run.

How are payment APIs and file specs versioned?

• API versioning typically appears in the URL path or a header. Providers run multiple versions in parallel, introduce changes in a new version and give consumers a window to migrate before retiring old ones.
• File specification versioning works through numbered specification documents. The bank publishes a new version of the layout, communicates an effective date and migration window, and may require re-certification through UAT before you submit files in the new format. See sandbox, UAT and production for how certification fits in.

Providers also distinguish between the interface version and the underlying scheme rules: an industry rule change (for example to DebiCheck processing) can force a change even when the API surface looks the same.

What counts as a breaking change?

Breaking changes require you to modify your integration:

• Removing or renaming fields, or changing a field's type, length or format
• Making an optional field mandatory
• Changing the meaning of a status or reason code
• Changing authentication requirements, such as new signature algorithms or certificate standards
• Changing file layouts, record structures or delimiters

Non-breaking changes should be absorbed without a release:

• New optional fields in responses or webhook payloads
• New enum values, statuses or reason codes
• New endpoints or message types you do not use

How do you build a tolerant integration?

The single most valuable defence is a tolerant parser:

• Ignore unknown fields rather than failing when a new one appears. Strict schema validation that rejects unrecognised fields turns every additive change into an outage.
• Handle unknown enum values gracefully: route an unrecognised status or reason code to a review queue with a safe default rather than crashing.
• Do not depend on field order in JSON, or on undocumented behaviour anywhere.
• Pin the version explicitly in requests and file headers, so behaviour changes only when you choose to migrate.

How should you manage a migration?

1. Track announcements: subscribe to the provider's and bank's technical bulletins, and assign ownership so notices are actioned, not just received.
2. Assess impact: diff the new specification against the current one and identify affected fields, flows and mappings.
3. Update and test in sandbox, then complete any required UAT or re-certification in the bank's test environment.
4. Deploy ahead of the deadline, leaving buffer for issues; never plan to migrate on the retirement date itself.
5. Migrate progressively where possible: run the new version on a subset of traffic first, watching error rates and webhook payloads before switching fully.
6. Keep a rollback path during the migration window while both versions are supported.

What should you have in place permanently?

• An inventory of every provider and bank interface you consume, with its current version and announced end-of-life dates
• Contract tests that validate your integration against the specification, run in CI
• A configuration-driven mapping for statuses and reason codes, so additive changes are data updates
• A change log of your own migrations, useful in incident reviews and audits, alongside the records described in logging, masking and audit trails

Version upgrades handled this way become routine engineering work instead of emergencies.

Back to the Payment Operations hub.