Versioning and changes

The API has two levels of versioning.

• Major version in the path: /v1. It changes only for a rewrite of the API.
• Dated versions within v1, sent in the ZyloPay-Version header. The current and only version is 2026-09-28.

How your version is chosenCopy Anchor Link

1. Each API key is pinned to the latest version when it is created.
2. Send ZyloPay-Version: <date> to choose a version for one request. An unknown version answers 400 api_version_invalid.
3. Every response echoes the version it was rendered with in the ZyloPay-Version header.
4. Each webhook endpoint is pinned to a version too (api_version, set at creation). Events delivered to it use that version's shape.

curl https://zylopay-api.fly.dev/api/v1/payments \
  -H "Authorization: Bearer $ZYLOPAY_SECRET_KEY" \
  -H "ZyloPay-Version: 2026-09-28"

The Node SDK sends the version its types describe (ZyloPay.API_VERSION) with every request, so responses always match its types. Upgrading the SDK is how you move to a new version; new ZyloPay(key, { apiVersion }) pins another one.

What is not a breaking changeCopy Anchor Link

ZyloPay adds to v1 without a new dated version. Build your integration to tolerate:

• new endpoints;
• new optional request parameters;
• new fields in response objects and event payloads;
• new event types (you receive them only if your endpoint subscribes with * or a matching family such as payment_intent.*);
• new error codes, decline codes and reason_code values;
• new values in enums such as status or cancellation_reason, where the documentation says the list may grow;
• changes to message texts and to the format of IDs after their prefix.

In practice: ignore fields you do not know, handle unknown codes by their type, and never parse messages or IDs.

What is a breaking changeCopy Anchor Link

Removing or renaming a field, changing its type or meaning, changing an endpoint's behaviour for the same request, or removing an event type. These ship only in a new dated version. Your keys and endpoints stay on their version until you move them.

UpgradingCopy Anchor Link

When a new dated version ships, its changes are listed in the changelog.

1. Read the changes for every version between yours and the new one.
2. Test with ZyloPay-Version: <new date> on a test key.
3. Create a new webhook endpoint on the new version and move your handlers, or update your code to accept both shapes.
4. Create or rotate your live keys to pin them to the new version.

Changelog policyCopy Anchor Link

• Every change to the public API is recorded in the changelog, additive or not.
• Breaking changes are announced before release, with the version date that carries them.
• Deprecated fields and endpoints keep working on the versions that have them.