Versioning and Deprecation Policy

This page explains how EBPP services are versioned, how breaking changes are introduced, and what you must do to keep your integration working as versions move through their lifecycle.

---

Overview

EBPP uses year based versioning: each service version is encoded into its URLs. This means you always know exactly which contract your integration targets, and changes to newer versions never silently affect your existing calls.

EBPP API

# v1 — context path /payments/
/payments/{version}/{resource}

# v2026+ — context path /ebpp/
/ebpp/{version}/{resource}

# Examples
GET /payments/v1/customers/{id}
GET /payments/v1/mpa/customers/{id}
GET /ebpp/v2026/customers/{id}

Hosted Web Forms

/app/opco/{version}/scripts/checkoutofsc.js
/app/opco/{version}/service/payments/token

# Examples
/app/opco/v2026/scripts/checkoutofsc.js
/app/opco/v2026/service/payments/token

Important: Each EBPP offering: APIs, Webhooks, Billing System Integration, and Hosted Web Forms are versioned independently. You can migrate one service at a time without a single all-or-nothing cutover.

---

Base URLs

---

Why Versions Are Deprecated

Versioning and eventual deprecation is a deliberate, structured process driven by the following objectives:

---

Version Lifecycle

Every versioned EBPP service passes through three stages:

API response headers

All versioned EBPP API responses include the following lifecycle headers to help you monitor your integration's status:

---

Deprecation Timeline

Deprecation is tied to the release of a new version. When a new version becomes current, the previous version transitions to deprecated status and remains available for a defined support period before it is retired.

The EOL (removal) date is published in release notes and also returned in the removal_date response header.

---

Service-Level Versioning

Versioning is maintained per service, giving you flexibility to migrate in phases.

Recommended migration order: APIs, then Webhooks, then Billing System Integration, then Hosted Web Forms.

---

API Error Responses

HTTP 410 - End of Life

Returned when you call a retired EBPP API version.

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "errors": [{
    "code": "error_api_version_retired",
    "message": "The requested api version is no longer supported."
  }]
}

HTTP 426 - Upgrade Required

Returned when the requested EBPP API version is below the minimum supported version for your account.

HTTP/1.1 426 Upgrade Required
Content-Type: application/json

{
  "errors": [{
    "code": "error_api_version_not_supported",
    "message": "The requested version does not meet the minimum supported version for this account."
  }]
}

---

Deprecated Fields

When individual fields within an API are deprecated rather than an entire version. The API schema includes structured metadata to guide migration:

---

Migration Support

During a version's support period:

• Deprecated endpoints continue to function as documented.
• Security patches are applied throughout the support window; bug fixes may be limited.
• Migration guides are published alongside each new version release.
• If you require extended migration timelines, contact your account representative.

For questions or assistance, please contact support.

---

Version History

---