Skip to main content

​
Summary

​
How the version works

The path carries the version. The /v1 path versions the shared API mechanics and the Receivables core. A profile versions the industry rules on top: your grant fixes credit_union.v1 or property_management.v1, and you cannot select a profile in a request. Every response carries PayPathIQ-Api-Version: v1, including problem responses and the OpenAPI document. Read it to confirm which contract answered you. Sending that header in a request does nothing, because the server does not read it. A future version is chosen by path only, such as /v2. PayPathIQ-Api-Version stays a response label: it will never take a dated value, and you will never send it to pin a version. Breaking core changes require /v2. Breaking profile changes require a new profile version such as credit_union.v2. An existing grant is never switched to a new profile version implicitly.

​
What counts as breaking

These changes are additive and ship in /v1 without a new version:
  • New optional response fields.
  • New optional request fields.
  • New endpoints.
  • New scopes. They are never granted to existing grants automatically.
  • New problem types. Every problem has a stable type URL and an HTTP status.
  • New change types in the change feed and webhooks.
  • New values in response enums, such as statuses, holdReason, outcome, change types and problem types. Accepted request values are never removed within /v1.
These changes are breaking and need a new version:
  • Removing or renaming a field, endpoint, scope or problem type.
  • Making an optional request field required.
  • Narrowing accepted values.
  • Changing the meaning of money, balances, allocations or identities.
  • Changing a default.
Because of the additive rules, write your client to tolerate:
  • Response fields it does not know. Ignore them.
  • A change or webhook type or resource.type it does not know. Skip the event, but still store the cursor.
  • An enum value it does not know in a response, such as a new holdReason, outcome or status. Treat the record as needing review: do not count it as settled, paid or clear.
  • A problem type it does not know. Use the HTTP status and Retry-After to decide whether to retry, as in Errors and retries.
Retained records and their identities keep their meaning across versions. Every change is paired with a regenerated OpenAPI document and a dated changelog entry. A breaking change also has a migration guide and the support period below.

​
The launched baseline

The /v1 contract in the generated OpenAPI document is the baseline for launch. It replaced the earlier pre-launch prototype shape before any partner depended on it, so no /v2 was created for prototype wire compatibility. That reset does not relax compatibility for anything launched afterwards: from the first live integration, every change follows the rules above.

​
Support period

PayPathIQ supports a version for at least 12 months after its replacement is generally available, and never removes anything less than 6 months after announcing it. Whichever date is later applies. Only an urgent security or legal requirement may shorten this, and the changelog will say why.

​
Deprecation notice

For a planned breaking change, PayPathIQ publishes a dated entry in the changelog and a migration guide. It also notifies the named Integration technical contact directly. Nothing in V1 is deprecated. When something is, its responses will carry the standard Deprecation header (RFC 9745) from the announcement, and a Sunset header (RFC 8594) with the removal date. Log these headers so your team sees them before the date. Keep a current technical contact with your PayPathIQ Integration administrator so your team receives deprecation notices.

​
Check for changes

  • Read the changelog before each release of your integration.
  • Compare the OpenAPI document you built against with the current OpenAPI document. It is also served at GET /v1/openapi.json without a key.