Skip to main content

Versioning and compatibility

API versioning is a critical part of ensuring stability and longevity in any integration. It allows providers like Nopan to evolve our APIs by fixing bugs, adding features, or improving usability, while preserving compatibility for existing integrations.

At Nopan, we use a flexible and forward-compatible approach to versioning that balances clarity with developer productivity.

How Versioning Works​

We implement API versioning through a custom HTTP header:

Nopan-Version: 0.1
  • This version header follows semantic versioning in the format MAJOR.MINOR.
  • You can specify this header in each request to control the behavior and shape of the response.

Example​

cURL - POST /payments/initiate
curl -X POST https://api.nopan.com/payments/initiate \
  -H "Authorization: Bearer <access-token>" \
  -H "Idempotency-Key: 63c2e3f0-12aa-41bb-ae62-f3d91fdbb762" \
  -H "Signature: nopan_sig=<signature>" \
  -H "Signature-Input: nopan_sig=("@status");keyid="your-key-id";created=1766678793 \
  -H "Content-Type: application/json" \
  -H "Nopan-Version: 0.1" \
  -d '{
    "clientTransactionId": "order123",
    "transactionType": "ONE_TIME",
    "paymentDetails": {
      "amount": 100,
      "currency": "PLN",
      "country": "PL",
      "description": "Product ID 1234 purchase"
    },
    "providerDetails": {
      "providerId": "BLIK"
    },
    "payerDetails": {
      "payerId": "payerUUID",
      "oneTimeCode": "123456"
    }
  }'

Defaults and Compatibility​

If the Nopan-Version header is not specified, the API will default to the latest stable version. This ensures that new integrations always benefit from the most refined, tested behavior without additional configuration.

tip

For predictable behavior across environments and teams, we recommend explicitly setting the Nopan-Version header in production.

Backward Compatibility​

All stable endpoints are designed to be backward compatible. This means we avoid breaking changes after an endpoint is released as stable.

We may add optional fields to responses, but we will not alter or remove existing fields.

info

Your integration should ignore unknown fields. This ensures your application continues working even as payloads evolve.

This design allows your integration to remain functional and secure as the API improves.

Versioning Policy​

Versioning follows semantic versioning:

  • Minor version updates (1.1 → 1.2) introduce safe, non-breaking enhancements.
  • Major version updates (1.x → 2.0) may introduce structural or behavioral changes

Each version is documented in our API Reference, and changes are clearly communicated in release notes.

Best Practices for Clients​

  • Always specify Nopan-Version in production integrations for deterministic behavior.

Design your API client to:

  • Accept optional fields in responses.
  • Ignore unknown fields during deserialization.
  • Monitor changelogs for upcoming version transitions.

By using header-based semantic versioning, Nopan ensures that innovation doesn’t come at the cost of reliability. Your integration remains stable, while your users benefit from continuous improvements under the hood.