Skip to main content

API Versioning

Von Payments uses date-based API versioning to ensure backward compatibility while allowing the API to evolve.

Version Header​

Set the Von-Pay-Version request header to pin your integration to a specific API version:

Von-Pay-Version: 2026-04-14

The current (and only) supported version is 2026-04-14. The API validates the header against an allowlist of supported versions, so an unrecognized value is treated the same as no header at all (see below).

Default Behavior​

If the Von-Pay-Version header is omitted — or set to a value that isn't a supported version — the API falls back to the current version, 2026-04-14. This is a single, global default, not a per-account or per-key setting; there is no account-specific "version current when your account was created."

Every response echoes two headers so you can confirm what was applied:

  • Von-Pay-Version — the version the request was processed against. This is the value you sent only if it's a supported version; otherwise it's the current version.
  • Von-Pay-Latest-Version — always the latest available version, so you can detect when a newer version exists.

SDK Pinning​

The server SDKs that talk to the REST API — Node.js and Python — accept an apiVersion option that sets the Von-Pay-Version header automatically on every request.

Node.js:

const vonpay = new VonPayCheckout({
  apiKey: "vp_sk_live_xxx",
  apiVersion: "2026-04-14",
});

Python:

client = VonPayCheckout("vp_sk_test_...", api_version="2026-04-14")

Pin your SDK to a specific version to avoid unexpected behavior when new versions are released.

The browser SDK (vora.js) and the hosted SDK (vora-hosted.js) do not send a version header — browser-side behavior tracks the current version automatically — and the CLI and MCP server inherit whatever the underlying Node SDK is configured with. Version pinning is therefore a server-side concern: set it where you make API calls.

Compatibility Policy​

Non-breaking changes do not require a version bump. These include:

  • Adding new optional request parameters
  • Adding new fields to response objects
  • Adding new event types
  • Adding new error codes

Breaking changes result in a new dated version. These include:

  • Removing or renaming fields
  • Changing field types
  • Changing default behavior
  • Removing endpoints

Deprecation Policy​

Von Payments aims for a predictable deprecation window so integrations have time to migrate before anything breaks.

How deprecation is signalled​

When a request uses a legacy field shape that has been superseded, the API still processes the request normally and returns its usual success status, but attaches RFC 8594 deprecation headers to the response so you can detect the legacy usage in production.

Today the only surface that emits these headers is POST /v1/sessions, on the legacy Embedded Fields field path — requests that pass the older stringified metadata.mirror value instead of the current top-level mirror field. Such a request still succeeds with 201 Created and carries:

Deprecation: true
Sunset: Wed, 27 Aug 2026 00:00:00 GMT
Link: <https://docs.vonpay.com/api/sessions#mirror>; rel="deprecation"; type="text/html"
  • Deprecation — the literal value true (an RFC 8594 boolean signal that the request used a deprecated shape). It is not an HTTP-date.
  • Sunset — an HTTP-date marking when the legacy shape may stop being accepted. For the legacy Embedded Fields field, that date is Wed, 27 Aug 2026 00:00:00 GMT.
  • Link — a documentation URL describing the replacement, with rel="deprecation".

There is no blanket Deprecation header on "every affected endpoint," and a deprecated field is not met with 410 Gone — the legacy request continues to work until its sunset date. Watch for a Deprecation header on your responses in production so you find out about deprecated usage before its sunset arrives.

Notice commitments​

  • No silent removals. A breaking change ships in a dated version and is signalled in-band through RFC 8594 Deprecation / Sunset / Link response headers on the affected request shape, plus release notes in the changelog.
  • Authentication changes (key prefix, signing algorithm, header format) carry the longest notice window given their blast radius. (Forward-looking policy intent; the only mechanism exercised in the API today is the RFC 8594 header signal above.)

Dated version support​

Currently there is exactly one supported API version, 2026-04-14, and the server keeps a single-version allowlist. There is no previous-version cohort or "N-2 and older" tier to deprecate yet, because only one dated version has ever been issued. When additional dated versions are introduced, each breaking change will be announced through the channels above before the prior version is retired.

Pin your SDK to a specific apiVersion (see SDK Pinning) so a future default version doesn't change behavior for your integration until you explicitly bump.

Changelog​

The full version changelog is maintained at openapi/CHANGELOG.md in the repository.