API Versioning

A55 uses URL-based versioning with a stable backwards-compatibility contract. The current version is v1 and all endpoints are served under:

https://core-manager.a55.tech/api/v1/

---

Versioning strategy

Aspect	Policy
Scheme	URL path prefix (/api/v1/, /api/v2/)
Current version	v1
Stability	Production-stable — no breaking changes within a major version
Deprecation notice	Minimum 6 months before a major version is sunset
Sunset period	12 months of dual-version support during migration

What counts as a breaking change

These changes trigger a new major version:

Breaking change	Example
Removing a field from a response	Dropping usd_currency from charge response
Renaming a required request field	payer_name → cardholder_name
Changing a field's type	installment_count from integer to string
Removing an endpoint	Dropping POST /charge/
Changing authentication scheme	Bearer token → API key
Changing error response structure	message: string → message: array

What is NOT a breaking change

These changes happen within the current version without notice:

Non-breaking change	Example
Adding new optional request fields	New metadata field on create charge
Adding new fields to responses	New provider_reference in charge response
Adding new endpoints	POST /api/v1/bank/wallet/checkout/
Adding new enum values	New type_charge: "googlepay"
Adding new HTTP status codes	New 429 rate limit response
Improving error descriptions	More specific error messages
Performance improvements	Faster response times

Always handle unknown fields

Your integration should ignore unknown fields in API responses. A55 may add new response fields at any time as a non-breaking change. Use permissive JSON parsing and avoid strict schema validation on responses.

---

Environment URLs

Environment	Base URL	Purpose
Production	https://core-manager.a55.tech/api/v1	Live transactions
Sandbox	https://sandbox.api.a55.tech/api/v1	Testing and development

Use environment variables to switch between environments:

export A55_API_URL="https://sandbox.api.a55.tech"   # Development
export A55_API_URL="https://core-manager.a55.tech"   # Production
export A55_ACCESS_TOKEN="your-token-here"

---

Deprecation process

When a new major version is released:

1. Announcement — Blog post, email notification, and dashboard banner 6+ months before sunset.
2. Dual support — Both versions run in parallel for 12 months. v1 endpoints return a Deprecation header.
3. Migration guide — A detailed field-by-field migration guide is published.
4. Sunset — After the sunset date, old version returns 410 Gone with a migration link.

Deprecation headers

When a version or endpoint is deprecated, responses include:

Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.a55.tech/migration/v1-to-v2>; rel="successor-version"

---

SDK versioning

A55 SDKs follow semantic versioning:

SDK	Package	Versioning
JavaScript	@a55/a55pay-sdk	MAJOR.MINOR.PATCH
Python	a55-sdk	MAJOR.MINOR.PATCH

SDK major versions align with API major versions. A new API v2 will ship with SDK 2.x.

---

Changelog →See what changed in each API release.Authentication →Set up Bearer tokens for API access.Create charge →Start integrating with the current API version.