SDK Versioning and Support Policy

This policy covers @paymentlabs/paymentlabs-js, the Payin SDK, whether you install it from npm or load it from our CDN. It tells you what each release can change, how long a version is supported, and how much notice you get before something you use goes away.

In short

• We follow Semantic Versioning: MAJOR.MINOR.PATCH.
• Minor and patch releases never break your integration. You can take any 1.x release without changing your code.
• Breaking changes only ship in a new major version, and moving to it is always your choice.
• We announce a deprecation at least 6 months before we remove anything, and tell you what to use instead.
• When a new major version ships, the previous one keeps getting security and critical fixes for 12 months.

How versions are numbered

What the policy covers

The policy protects the SDK's public API, which is everything documented in the Payin SDK guide:

• PaymentLabs.create(config) and its configuration options.
• sdk.createElement(...), sdk.updateTheme(...), and the element methods (submitPayment, on, getCheckoutData, getSubscriptionOfferData, destroy).
• Event names, the fields of their payloads, and sdk-error codes.
• The exported TypeScript types.
• The PaymentLabs global that the CDN script defines.

It does not cover anything the guide doesn't document, such as the element's internal markup and CSS classes, the exact wording of messages shown to buyers, or the requests the SDK makes to our API. We improve these in minor and patch releases.

What counts as a breaking change

A change is breaking if code written against the documented API can stop working or behave differently. For example:

• Removing or renaming a method, option, event, type, or sdk-error code.
• Changing the type or the meaning of an existing field.
• Making an optional option required.
• No longer emitting an event in a situation where it was emitted before.
• Removing a payment method or a field that the element used to collect.

These are not breaking changes, and can ship in any minor or patch release:

• Adding optional options, new events, new payload fields, or new sdk-error codes.
• Fixing behavior so it matches the documentation.
• Improving the element's layout, labels, accessibility, or buyer-facing wording.

💡

Write code that tolerates additions

Ignore event payload fields you don't recognize, and treat an unknown sdk-error code by its category and severity rather than failing. New values arrive in minor releases.

⚠️

Security and compliance exceptions

Very rarely, a fix required for security, a card network rule, or PCI DSS can't wait for a major version. When that happens we ship it in a minor or patch release and contact you directly before it goes out.

Version lifecycle

Each major version moves through three statuses:

A major version is Active until the next major version ships. It then stays in Maintenance for 12 months, and we publish its end-of-support date on this page on the day it enters Maintenance.

While a version is supported, the API endpoints it calls keep working. If an endpoint has to change, that is a breaking change for the versions that call it, and we announce it with the same notice as a deprecation.

Fixes always ship as a new release on the newest version of a line. We don't patch older minor versions, so stay on the latest 1.x release to receive them.

Supported versions

To move from 0.x to 1.x, see Upgrading from 0.x to 1.x. For every release and what it changed, see the Payin SDK Changelog.

Deprecations

When we plan to remove part of the public API, we deprecate it first:

1. We list it in the table below, with its replacement and the version that will remove it.
2. We mark it @deprecated in the TypeScript types, so your editor flags it.
3. The SDK logs a warning to the browser console, once per page load, when your code uses it.
4. We email the contacts on your Payment Labs account.

A deprecated feature keeps working for at least 6 months after the announcement, and it is only removed in a major version.

Choosing and pinning a version

npm

Install a specific version and let your lockfile hold it:

npm install @paymentlabs/[email protected]

The default range that npm writes (^1.16.0) picks up new 1.x releases when you update your dependencies, which is safe under this policy, and never moves you to 2.0.0. To stay on one exact version until you choose to change it, add --save-exact.

CDN

<script src="https://sdk.paymentlabs.io/payin/latest/paymentlabs.js"></script>

This URL serves the newest 1.x release and picks up minor and patch releases automatically. A new major version never reaches your checkout through a CDN URL you already use. If you need a version that never changes, install the SDK from npm.

Upgrading between major versions

Every major version comes with a migration guide on this page.

Upgrading from 0.x to 1.x

1.x renamed the public API from "Widget" to "Element" terminology. The old names were removed, not kept as aliases.

Event listeners, the order of method calls, option objects, and callback signatures didn't change.

How we tell you about changes

Patch and minor releases don't need any action from you. For everything else:

Questions about this policy or about upgrading? Reach out to the Payment Labs support team.