Skip to content

Versioning & Release Policy

This page describes how PayAlo evolves the Merchant Gateway API and what changes you can rely on between releases.

Draft

The specifics below are the current intent; some figures (deprecation window, breaking-change cadence) are pending product confirmation. If a number on this page conflicts with what your account manager tells you, trust the account manager and report the doc.

Versioning Model

The major API version is part of the URL path:

POST https://api.payalo.com/gateway/mmo/v2/...

Within a major version, we follow these rules:

Change type Treated as
Adding a new endpoint Non-breaking
Adding a new optional request field Non-breaking
Adding a new field to a response or callback body Non-breaking — clients must ignore unknown fields
Adding a new value to an open enum (status, completionSource, errorCode, flow) Non-breaking — clients must treat unknown values as informational
Adding a new HTTP error response code Non-breaking
Renaming or removing a field Breaking — only in a new major version
Changing a field's type or shape Breaking — only in a new major version
Tightening validation (rejecting input previously accepted) Breaking — only in a new major version
Loosening validation (accepting input previously rejected) Non-breaking
Changing the canonical wire value of an enum Breaking — only in a new major version

Forward compatibility is your responsibility on the receive side. Your callback handler and status response parser must:

  • Ignore fields they don't recognise.
  • Treat unknown enum values as informational rather than throwing.
  • Tolerate null on any field documented as nullable.

If you build to those rules, additive changes will not break you.

Current Status

Version Status Notes
V2 Generally available All new integrations must use V2.
V1 Sunset V1 documentation has been removed. Existing V1 integrations remain operational during the sunset window — contact your account manager for the timeline that applies to your brand.

Breaking Changes and New Major Versions

When we need to make a breaking change, we publish a new major version (e.g. v3) at a new URL path. The previous major remains operational during a deprecation window.

What we commit to

  • Advance notice before a major version is announced as deprecated. The window is set per-release; expect at least several months for any externally-visible API.
  • Co-existence — the deprecated version keeps serving traffic until the announced sunset date.
  • A migration guide that maps every changed field, endpoint, and behaviour from the old version to the new.

What we do not commit to

  • No timeline for security fixes. A breaking change required to close a security issue may ship faster than the standard window. We will notify affected merchants directly when this happens.
  • No support for indefinite use of deprecated versions. After sunset, deprecated endpoints return 410 Gone.

How Changes Are Communicated

Channel What you'll see there
Account manager Pre-announcement of significant changes for brands they manage.
Release notes (this site) The authoritative changelog per release. Coming soon.
OpenAPI spec The current contract — diffing two snapshots is the most precise way to see what's changed. See OpenAPI Spec.

OpenAPI Spec

Contact your account manager to obtain a snapshot of the V2 OpenAPI document for use with codegen tools like openapi-generator or kiota.

If you generate clients in CI, pin to a specific snapshot of the spec rather than fetching the latest at build time — that way an additive server-side change won't show up as a non-deterministic diff in your generated code.

  • Pin to V2 explicitly in your code paths. Don't write logic that conditionally targets "the latest version".
  • Snapshot test your callback handler against a recorded payload. Snapshot tests catch unintended deserialisation changes when we add new fields.
  • Subscribe an internal alias (e.g. [email protected]) with your account manager so deprecation notices reach more than one engineer.