Skip to main content

API Versioning

The API is versioned by date.

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")

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​

How deprecation is signalled​

A request that uses a superseded field shape is processed normally and answered with its usual success status plus RFC 8594 deprecation headers, so you can find the legacy usage in production. The one surface that emits them is POST /v1/sessions when a request passes the stringified metadata.mirror value instead of the top-level mirror field — it still succeeds with 201 Created, the string is never parsed so no order is mirrored, and the response carries:

Deprecation: true
Sunset: Wed, 27 Aug 2026 00:00:00 GMT
Link: <https://docs.vonpay.com/connected-platforms/shopify#legacy>; 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 — the earliest HTTP-date at which the legacy shape may stop being accepted. The metadata.mirror date has passed and the shape is still accepted.
  • Link — a documentation URL describing the replacement, with rel="deprecation".

A deprecated shape is not met with 410 Gone, and no blanket Deprecation header appears on other endpoints. A breaking change ships in a new dated version and is signalled the same way, on the affected request shape, before the prior version is retired — pin apiVersion so a future default does not change your integration's behaviour until you bump it.