# Versioning & deprecation

## Version in the path

The gateway API is versioned in the URL path. The current version is **`v1`**:

```
https://api.paymee.online/api/v1/gateway/...
```

A given version's request and response contracts are stable. We will not make
breaking changes to `v1`.

## What counts as breaking vs. non-breaking

We may add the following to `v1` **without** a new version — your integration
should tolerate them:

- New endpoints.
- New **optional** request fields.
- New fields in responses and webhook payloads.
- New `enum` values (e.g. a new session status or webhook event).
- New error `type`s.

Write your integration defensively: ignore unknown fields, and have a default
branch for unrecognized `status`, `event`, and error `type` values.

**Breaking changes** — removing or renaming a field, changing a type, or
changing required fields — are introduced only under a **new path version**
(e.g. a future `v2`).

## Deprecation policy

When a version or field is deprecated, we will:

- Announce it in the [changelog](/guides/changelog/) with a migration path.
- Continue to support the deprecated surface during a published sunset window.
- Keep both versions running in parallel so you can migrate on your schedule.

:::note
Pin to `v1` explicitly in your base URL. Don't build URLs that assume a "latest"
alias.
:::

Source: https://docs.paymee.online/guides/versioning/