Changelog and Versioning

This page documents the UrbanPayX API versioning policy, breaking change commitments, and a log of changes.

Current version

The UrbanPayX API is currently at v1 (/api/v1/). All endpoints use this version prefix.

Versioning policy

We will not make breaking changes to v1 without advance notice.

A breaking change is any change that could cause a working integration to fail. This includes: removing endpoints, removing or renaming fields in response bodies, changing the type of existing fields, adding new required request parameters, or changing the meaning of existing status codes.

The following are NOT breaking changes and may happen at any time: adding new endpoints, adding new optional fields to request or response bodies, adding new webhook event types, adding new optional query parameters, changing error message text (the HTTP status codes remain stable), and improving validation error detail messages.

How we communicate changes

Non-breaking changes are documented here in the changelog as they are released. No advance notice is required.

Breaking changes (if ever necessary) will be communicated through:

A notice in this changelog at least 30 days before the change
A deprecation header (Deprecation: true) on affected endpoints during the notice period
Email notification to all registered client contacts

Our goal is to evolve the API additively so that breaking changes are never necessary.

Deprecation policy

When an endpoint or field is deprecated:

It continues to work for at least 30 days after the deprecation notice
The response includes a Deprecation: true header and a Sunset header with the removal date
The replacement (if any) is documented in this changelog
After the sunset date, the endpoint may return 410 Gone

No endpoints are currently deprecated.

Changelog

March 2026

Documentation

Added Getting Started guide with 7-step quickstart flow
Added Core Concepts guide (OpCos, Projects, Users, Transactions)
Added Authentication Guide (two auth methods, MFA, security challenges)
Added KYC Verification Guide (both modes, bulk operations)
Added Sandbox and Testing guide (test flows, webhook testing, outcome simulation)
Added Transaction Lifecycle guide (state machine, webhook payloads, handling patterns)
Added Roles and Permissions matrix
Added Error Reference (all HTTP status codes with causes and fixes)
Added Launch Checklist for production readiness
Added Pagination guide
Added this Changelog and Versioning page

API

No API changes in this release. These updates are documentation-only.

Upcoming

Planned improvements (not yet released):

Standardized error response format with machine-readable error codes
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) on rate-limited endpoints
/llms.txt endpoint for AI-agent discoverability

These will be documented here when they ship.

Questions

If you have questions about API changes or need guidance on adapting your integration, contact support or open a ticket via POST /tickets.