Skip to main content

API Versioning

The PayConnect API uses dated version ids of the form YYYY-MM-DD.N — the version's release date, a dot, then its version number (e.g. 2026-07-05.1). You select a version with the Payconnect-Version request header:

POST https://my.payconnect.us/api/trx
Authorization: Api-Key YOUR_API_KEY
Payconnect-Version: 2026-07-05.1
Content-Type: application/json

Send the full dated id — a bare number (1) is rejected. We mint a new version only for a breaking change, and we expect that to happen rarely — at most a few times a year.

The default: your integration never breaks​

Your account is pinned to a version — the one that was current when you onboarded. If you omit the Payconnect-Version header, every request uses your pinned version, and we never change how that version behaves. When we release a new version, it does not touch you: you keep getting your pinned version until you explicitly opt in by sending the header.

Existing integrations that predate versioning are pinned to 2026-07-05.1 (v1).

You only need to send Payconnect-Version when you want to move to a newer version. When you do, pin it explicitly so your integration is stable and reproducible. A per-request header always wins over your account default — handy for testing a new version on a few calls before you commit.

What's a breaking change?​

We mint a new version only for breaking changes — removing or renaming a field, changing a field's type/format/units, tightening validation, changing default behavior, changing an error status code, or changing the response envelope.

Non-breaking, additive changes ship within your version at any time, so your integration must tolerate them:

  • New fields on responses — ignore any you don't recognize.
  • New optional request fields.
  • New values in an existing enum — handle unknown values gracefully.
  • New endpoints.

Bug fixes and security patches that make a version behave as documented are not breaking changes — they ship into your version without a bump.

Every response tells you its version​

Responses echo the version they were served with, and caches are keyed on it:

Payconnect-Version: 2026-07-05.1
Vary: Payconnect-Version

A malformed value (including a bare number) returns 400 api_version_invalid; a well-formed id that isn't a real version (unknown number, or a date that doesn't match that version's release date) returns 400 api_version_unknown:

{ "statusCode": 400, "error": "api_version_unknown",
  "message": "Unknown API version \"2026-07-05.9\". Supported versions: 2026-07-05.1." }

Deprecation & sunset​

When a version is deprecated, its responses carry standard headers so you're warned in-band:

Deprecation: @1798761600
Sunset: Mon, 05 Jul 2027 00:00:00 GMT
Link: <https://docs.liveacid.com/docs/versioning>; rel="sunset"
  • Minimum 12 months between deprecation and sunset.
  • A final reminder goes out 90 days before sunset.
  • After the sunset date the version returns 410 Gone — migrate to the successor version before then.

(The Deprecation value is an RFC 9745 Structured-Field Date — @ followed by Unix seconds.)

See the Changelog for the list of versions and what changed in each.