Skip to main content

Versioning

NextAPI uses URL-based versioning. The current stable version is v2.

Base URL​

https://api.partners.nextpay.world/v2/

The /v2/ path segment identifies the API version. All endpoints in this documentation are under this base URL.

Versioning policy​

Backward-compatible changes (non-breaking)​

The following changes can be made to an existing version without a version bump. Your integration does not need to be updated:

  • Adding new optional request fields
  • Adding new response fields
  • Adding new endpoints
  • Adding new webhook event types
  • Adding new values to existing enum fields (design your code to handle unknown enum values gracefully)
  • Relaxing validation rules (e.g., increasing a maximum length)

Breaking changes (require new version)​

The following changes are considered breaking and will only be introduced in a new API version:

  • Removing or renaming existing fields
  • Changing a field's data type
  • Removing endpoints
  • Changing authentication mechanisms
  • Changing error response formats
  • Making previously optional fields required
  • Tightening validation rules

When v3 is released​

When NextAPI v3 is available:

  • A new base URL /v3/ will be introduced
  • v2 will be maintained in parallel for a deprecation period (communicated via changelog)
  • This documentation site will add a version switcher — /docs/ will show v3, /docs/v2/ will show frozen v2 docs
  • Migration guides will be published in the changelog

Staying informed​

Breaking changes, new versions, and deprecation timelines are announced in the Changelog. Subscribe to the changelog feed or check it regularly as part of your integration maintenance.

Design recommendations for forward compatibility​

Build your integration to be resilient to additive changes:

  • Ignore unknown fields — do not fail if a response includes a field you did not expect
  • Handle unknown enum values — use a default/fallback case for enum fields instead of exhaustive switches
  • Read the changelog — check for new optional fields or webhook events that could benefit your integration
  • Changelog — full release history and upcoming changes
  • Authentication — auth model (Basic Auth) is version-stable
  • Errors — error format is consistent across v2