Skip to main content

API Versioning

MidasPay uses URI-based major versioning. Every published endpoint lives under /v1/... today. Backwards-compatible evolution happens within a major: new optional fields, new enum values, new event types, and new endpoints can ship at any time without a client-side change.

Versioning dimensions​

DimensionMechanismExample
MajorURI path prefix (/v1)POST /v1/payment/orders
AdditiveSchema extension within a majorNew optional field, new enum value, new event type
PatchNo client actionBug fixes, performance improvements, internal refactoring

A future major (/v2) would ship alongside /v1 — not replace it — giving merchants a migration window. There is no /v2 today.

What counts as a breaking change​

The following are breaking — they require a new major:

  • Removing an endpoint, field, enum value, or error code.
  • Changing the type of a field (e.g. string → number, object → array).
  • Making an optional field required.
  • Tightening validation (shorter max length, stricter regex).
  • Changing the default behaviour when a field is omitted.
  • Renaming an event type or field.

The following are additive — they ship freely within a major:

  • Adding a new endpoint.
  • Adding a new optional request field.
  • Adding a new response field.
  • Adding a new enum value. Clients must treat unknown enum values defensively rather than rejecting them.
  • Adding a new event type. Webhook consumers must ignore unknown event_type values.
  • Relaxing validation (longer max length, optional → removable).
  • Adding a new HTTP header.
Code for unknown values

When you consume an enum (order status, event type, payment method name, etc.), handle the "unknown value" case explicitly — e.g. log and ignore, or fall back to a neutral branch. This lets MidasPay add categories safely without breaking your integration.

Deprecation signals​

Individual fields, enum values, or endpoints may be deprecated while the major they belong to is still active. Current signals are:

  1. deprecated markers in reference pages — deprecated fields are tagged as such in the API reference.
  2. Email to your technical contact — MidasPay sends advance notice before any deprecation that requires action.

Deprecated symbols (e.g. the renamed PAYMENT_ORDER_REFUND → PAYMENT_ORDER_REFUNDED alias) continue to be delivered for as long as the major containing them is active. When in doubt, migrate to the new name.

Checking the version of an endpoint​

The major version is encoded in the URI itself. There is currently no separate X-Version request header or API-Version response header — the path is the source of truth. If we introduce one in the future it will be announced via the channels above.

Migrating between majors​

When a future major ships, each affected endpoint will get:

  • A migration guide under /docs/migrations/... with a side-by-side reference comparing the old and new shape.
  • Code samples in the supported SDK languages.
  • Advance notice on the blog and via email.

Until a major has been announced there is nothing to migrate — stay on /v1.

FAQ​

Is there a separate sandbox version? No. Sandbox and production always serve the same API major and the same field shapes. Sandbox data is isolated and test credentials won't work in production.

Can I pin to a date? There is no date-based pinning today. Within a major, MidasPay changes are strictly additive, so your code keeps working without pinning.

What if I receive a field I don't recognise? Ignore it. Unknown top-level fields, unknown enum values, and unknown event types are all legal extensions of the current major.

See also​