Skip to content
Lango Docs

Versioning & compatibility

Your integration should keep working while Lango keeps shipping. This page is the contract that makes that safe.

One stable version

Every endpoint lives under /v1. That version is stable: we add to it, we don’t break it. A genuinely breaking change would ship as a new version (/v2) alongside /v1, and /v1 would keep working for its announced lifetime — you would move when it suits you, not when we deploy.

Every response carries the version it was served by:

X-Lango-Api-Version: v1

What can change without notice

These are additive and ship freely — so write your code to tolerate them:

  • new fields on existing responses and events,
  • new endpoints, new event types,
  • new optional request parameters,
  • new enum values (e.g. a new method or a new payment status).

Two rules keep you safe: ignore fields you don’t recognise, and don’t hard-code the full set of a list — fetch payment methods from the API, and treat an unknown status as “not yet terminal” rather than an error.

What counts as breaking

Removing or renaming a field, removing an endpoint, changing a field’s type or meaning, making an optional parameter required, or tightening validation. These never happen silently.

How a deprecation works

When something is scheduled for removal, its responses carry the standard RFC 8594 headers:

Deprecation: true
Sunset: Wed, 30 Jun 2027 00:00:00 GMT
Link: <https://docs.lango.co.zw/reference/versioning>; rel="sunset"

Alongside the headers you always get:

  • a dated entry in the changelog,
  • direct email to affected merchants,
  • a migration window of at least 90 days before the Sunset date.

Log the Deprecation header in your client and you’ll hear about a change long before it can affect you.

Zero-downtime on our side

Updates don’t interrupt live payments. Deploys are rolling (old and new instances serve side by side for a moment), database migrations are forward-only and backward-compatible (expand first, contract later — never a change that the currently-running version can’t read), and every release is gated by the full test suite before it ships. A payment in flight during a deploy is unaffected: its state is in the database, not in any one instance’s memory.