SDK versioning

Publication status

The release ledger contains 2 normal releases and 1 published major channel. The supported production channel is https://js.maxanapay.com/v1/maxanapay.js.

Versioning model

A major-channel URL can receive compatible updates and an exact-version URL provides byte-level pinning. Use the major-channel URL for automatic compatible updates, or an immutable exact-version URL when your release process requires byte-level pinning. Both choices follow the same public API compatibility contract.

Supported URL and cache behavior

The published major channel uses this cache policy:

public, max-age=300, stale-while-revalidate=86400

Exact-version assets use:

public, max-age=31536000, immutable

Do not invent a script path or copy a configured host into a production integration. The major channel follows the greatest release in its major. An exact version never changes and uses immutable caching; choose it only when your release process requires every byte change to be reviewed. No unversioned root script is published. Each normal exact release also publishes maxanapay.js.map beside the bundle.

Published production major channel URL:
https://js.maxanapay.com/v1/maxanapay.js

Subresource integrity

The supported major-channel URL can change bytes within its major and therefore must not be paired with a fixed integrity hash. If a release process requires an integrity hash, pin a recorded exact version and copy the browser-ready integrity field,

integrity, for maxanapay.js from the committed release ledger directly into the script’s integrity attribute. Also set crossorigin=“anonymous”. The ledger’s raw sha256 field verifies repository bytes; it is not the value browsers expect in the HTML attribute. Never put integrity on a channel URL because its next compatible release is supposed to change the bytes.

Compatibility within a major

The global remains window.MaxanaPay and continues to expose

MaxanaPay.checkout(options). Its returned handle retains handle.unmount() and handle.sessionId. Documented options remain accepted; their allowed values may grow additively.

Every documented error code remains stable in name and meaning. New codes may be added, so treat an unknown code as a generic failure. The documented

error.retryable, error.status, error.providerIssue, and error.retryAfterSeconds fields also remain. The onApproved result retains its documented fields and types; new fields may be added.

The re-entry contract remains stable: the SDK consumes PayPal return parameters once, cleans only those parameters from the URL, and does not create a second charge when loaded twice or revisiting an already completed session. The DOM contract also remains stable: rendering stays inside the supplied container, the container is emptied before mount and by unmount(), SDK-owned classes keep the maxana-checkout- prefix, and the SDK adds no own elements or styles outside that container. The published CSP origin ceiling does not grow within a major, and the live API origin does not move within one. The sandbox API origin carries neither promise: it names a Maxana test deployment, and a compatible release may move it, with notice.

Limits of the version contract

The contract does not freeze developer-facing message text,

error.detail, console output, rendered element structure, inline styles, bundle size, module structure, minified identifiers, sourcemap internals, non-exported implementation details, request counts, retry timing, mount timing, or which funding buttons appear. Provider eligibility and buyer-visible wallet availability depend on the session and buyer, not the SDK version.

Deprecation policy

When a new major ships, the previous major is maintained for twelve months for security and payment-correctness fixes, not new features. The release notice names its maintenance end date; integrators with known contacts receive notice at release and again ninety days before that date. After maintenance ends, the old channel is frozen at its last release and continues to serve indefinitely. Pinned exact-version assets are never removed or rewritten. Only a legal order can override that retention promise.

Versionless backend compatibility

The immutable release ledger currently records 2 normal releases. Every exact-version byte claim on this page comes from that ledger.

• 1.0.0 — SHA-256 06c95d31258189ae8d2bff8555a854b8d02cb5037c2acef40c94966af69adad0 — integrity sha384-Mb3ToF8kEIWxBQdXeKKGnU48WCbUSXsXHpqeJ3pptVJmviH68bc7VYDwASQv5N6d
• 1.1.0 — SHA-256 13516a48762a0938120d70c1aac68884e2ed90112997609310c4af0e600dd3ca — integrity sha384-KkS7LPMI/Nyxog8xkMNzHxmiNgaz4HPl8sHsZh/S708bZAygBnfgM4lR5zO9+YK/

The backend API is versionless. A response field removed from it disappears for every SDK bundle still running, including pinned artifacts on pages that cannot be updated. The SDK response compatibility contract therefore records the fields shipped bundles read, and backend governance keeps those fields in the public OpenAPI.

Do not invent an SDK URL, mutate published bytes, or edit the compatibility contract to accept a breaking backend change. Make SDK byte changes through the normal release process and keep API response additions backward-compatible.

Release ledger

The repository ledger is the source for published exact-version bytes and hashes. Release tooling must add new immutable artifacts rather than rewriting or deleting an entry already recorded there.