Versioning and deprecation
What may change under /v1 without warning, what may not, and the notice period we have never yet had to use.
The version lives in the path. Everything documented in this reference sits under /v1, and breaking changes only ever appear under a new path.
What may change under /v1
New fields may appear in responses at any time. Parse what you need and ignore what you do not recognize. A client that rejects unknown fields will break on a change that is not breaking, and that failure will be yours to debug.
New optional request fields may be added. Existing ones keep their meaning.
New enum values may appear, including new decision codes. Treat an unrecognized verdict as a denial rather than as an allow: the safe default when a payments system tells you something you do not understand is not to spend money. The current list is on decision codes.
What will not change under /v1
Field names and types will not be repurposed. A field will not change units or currency semantics. An endpoint will not change its HTTP method or its success status code. A decision code will not be given a different meaning — if the meaning changes, the code changes.
Anything that would break a correct client written against this reference waits for /v2.
Deprecation
A version path stays available for at least twelve months after its successor ships. We write to your named contacts at least ninety days before any path is retired, and the notice says what replaces it.
We have never retired a version. When we do, this paragraph will say when it happened and what the migration was — a deprecation policy that has never been exercised is a promise, and it is worth being clear about which of the two you are reading.
The machine-readable contract
The OpenAPI description at docs.saifuro.com/openapi.yaml covers the same 23 paths and the same schemas as these pages. Where the two disagree, that is a bug in one of them — tell us at contact@saifuro.com and we will say which.