Versioning

The gateway is path-versioned. The current version is v1, mounted at /api/v1/. The OpenAPI spec at /openapi.yaml declares info.version: 1.0.0 and openapi: 3.1.0.

What’s stable

Within v1, the following are guaranteed not to break:

Endpoint paths (/api/v1/payments/collect, etc.).
HTTP methods for documented endpoints.
error_code values — once published, a code’s meaning never changes. New codes may be added, never repurposed.
Response field types — a field that is string will not silently become int.
Required field semantics — a required field will not become optional in a way that changes existing callers’ behaviour.
Response status codes for documented success and failure cases.

What may change without a major version bump

New optional request fields. Old clients that don’t send them are unaffected.
New optional response fields. Old clients that don’t read them are unaffected.
New endpoints, tags, and error_code values in unused ranges.
message strings — these are localised and may be reworded for clarity. Branch on error_code, never on message.
Internal behaviour that’s not part of the documented contract (timing, log formats, header order).

What requires a major version bump (`v2`)

Removing or renaming any endpoint, request field, or response field in a way that breaks existing clients.
Changing a field’s type or semantics.
Repurposing or removing an error_code.
Auth model changes that affect the request shape.

When v2 ships, it’ll be at /api/v2/. v1 will continue serving in parallel for a published deprecation window before being retired.

Telegraphed renames

Some v1 endpoint paths will be renamed in v2. They’re documented here so you can track them:

`v1` path	`v2` rename	Reason
`/api/v1/internal/sessions/create`	`/api/v1/merchant/sessions/create`	The `/internal/` prefix is misleading — this is the merchant-facing S2S endpoint.
`/api/v1/payments/b2c`	(removed)	Deprecated alias of `/payments/send`.

Both will continue to work in v1. The renames take effect at v2 boundary, and both old and new paths will be live for the deprecation window.

SDK versioning

The SDKs follow semver independently of the API:

pdirect_pay (Flutter) is on 3.0.0. Major versions track breaking auth model changes (v3.x = Auth-v3 session tokens).
@mms/pdirect-pay (Angular) is on 1.2.x. The Auth-v3 migration is v2.0.0.

A new minor SDK version may add request fields or response fields without an API version bump — both ends were forward-compatible by design.

Pinning

For HTTP integrations, pin the path version (v1) — that’s the contract.

For SDK integrations, pin the major version of the SDK and let minors and patches roll forward:

dependencies:
  pdirect_pay: ^3.0.0

"dependencies": {
  "@mms/pdirect-pay": "^1.2.0"
}

Track new releases on the SDK changelog pages (Flutter, Angular).