Changelog - EBPP API (Multi Profile Account) v2026

The changes below cover the v2026 EBPP API contract for the MPA (Multi Profile Account) model. v2026 is a breaking release. Existing v1 integrations must be updated before v1 reaches its EOL date.

Review each section below and follow the Migration Guide to plan your migration.

---

What's New

• Path-based versioning with an explicit /v2026/ segment in all endpoint URLs
• Base context path in v2026 endpoints use /ebpp/ instead of /payments/
• Unified contact model via a contacts[] array, replacing the top-level email and mobile_phone fields
• Terminology standardised: funding_account renamed to payment_method
• Card CVV field name is card_cvv_number (v1 and v2026); in v2026 it must be inside payment_method only
• PBT Enrollment merged into the Payment Setup flow
• New lifecycle response headers on every API call
• New payment_channel request header; channel renamed to access_channel
• Hypermedia links removed from all responses
• Payment eligibility is controlled by a configuration-level feature flag - the customer_account_eligibility_check request field is removed; do not send it and work with EBPP Support to configure the flag

---

Breaking Changes

BC-1 - Path-Based Versioning Breaking

All endpoints now use versioned paths. The /mpa/ segment has been removed.

# Before (v1/mpa)
POST https://api.orbipay.com/payments/v1/mpa/customers
GET  https://api.orbipay.com/payments/v1/mpa/customers/{id}
POST https://api.orbipay.com/payments/v1/mpa/payments

# After (v2026)
POST https://api.orbipay.com/ebpp/v2026/customers
GET  https://api.orbipay.com/ebpp/v2026/customers/{id}
POST https://api.orbipay.com/ebpp/v2026/payments

BC-2 - Terminology Standardisation Breaking

Several field names have been renamed across all APIs for consistency.

// Before (v1/mpa)
{
  "funding_account": { "id": "FA_001" },
  "payment_method": "ACH"
}

// After (v2026)
{
  "payment_method": { "id": "PM_001" },
  "fulfilment_type": "ACH"
}

BC-3 - Customer: contacts Object Breaking

The top-level email and mobile_phone fields are deprecated. All customer contact data must use contacts[].

Affected APIs: Save Customer · Get Customer · Retrieve Customers

// Before (v1/mpa)
{
  "id": "cust_001",
  "email": "user@example.com",
  "mobile_phone": "+11234567991"
}

// After (v2026)
{
  "id": "cust_001",
  "contacts": [
    { "value": "+11234567991", "type": "sms",   "verified_by": "other" },
    { "value": "user@example.com", "type": "email", "verified_by": "other" }
  ]
}

BC-4 - Customer Account: contacts Object Breaking

Customer Account resources now follow the same contacts[] model. The email and mobile_phone fields are deprecated and silently ignored on requests.

Affected APIs: Save Customer Account · Get Customer Account · Retrieve Customer Accounts

// After (v2026)
{
  "customer_account": {
    "id": "ca_001",
    "contacts": [
      { "value": "user@example.com", "type": "email", "verified_by": "other" }
    ]
  }
}

BC-5 - Payment Changes Breaking

CVV field consolidation

CVV must now only be sent inside payment_method.card_cvv_number.

customer_account_eligibility_check removed

The customer_account_eligibility_check request parameter has been removed. Eligibility behaviour is now managed via a configuration-level feature flag for your account and environment.

Affected API: Create Payment

// Before (v1/mpa)
QUERY Param  "customer_account_eligibility_check": true
{
  "card_cvv_number": "123",
  "funding_account": { "id": "12345" }
}

// After (v2026)
{
  "payment_method": {
    "id": "12345",
    "card_cvv_number": "123"
  }
}

BC-6 - Manage PBT Enrollment / Retrieve PBT Enrollments Deprecated Breaking

The v1 Manage PBT Enrollment and Retrieve PBT Enrollments APIs are consolidated into Payment Setup. Migrate all PBT calls to the Payment Setup equivalents.

Before (v1/mpa) - POST /payments/v1/mpa/pbt

PBT Request Body 

After (v2026) - POST /ebpp/v2026/paymentsetups

Payment Setup Request Body

BC-7 - Hypermedia Links Removed Breaking

In v1, related collections are sometimes represented as named objects with a url field. In v2026, those embedded url fields are removed entirely from responses.

// Before (v1) — example: named objects with url (when present)
{
  "id": "cust_001",
  "status": "active",
  "funding_accounts": {
    "url": "/customers/{ID_CUSTOMER}/fundingaccounts"
  },
  "payments": {
    "url": "/customers/{ID_CUSTOMER}/payments"
  },
  "payment_setups": {
    "url": "/customers/{ID_CUSTOMER}/paymentsetups"
  }
}

// After (v2026) — same objects / url fields are not returned
{
  "id": "cust_001",
  "status": "active"
}

BC-8 - Base URL context path (/ebpp/) Breaking

For v2026 only, the API base context path changes from /payments/ to /ebpp/. All v2026 URLs must be prefixed with /ebpp/ (for example https://api.orbipay.com/ebpp/v2026/...). v1 integrations continue to use /payments/v1/mpa/... until migrated.

BC-9 - Payment method classification dimensions changed Breaking

In v1, funding account classification relied on the following fields inside funding_account:

• account_type
• account_subtype
• account_holder_type

In v2026, these fields are removed from payment_method (renamed from funding_account) and replaced with the following dimensional fields:

• payment_method_type
• payment_method_subtype
• payment_method_owner_type
• payment_method_source
• payment_method_card_brand

Example reclassification:

• Before (v1): account_type: debit_card, account_subtype: visa_debit
• After (v2026): payment_method_type: card_account, payment_method_subtype: debit_card, payment_method_card_brand: visa

BC-10 - Request headers: payment_channel (new, mandatory) and channel → access_channel Breaking

v2026 introduces a required request header payment_channel and renames the v1 header channel to access_channel. Requests that omit payment_channel or still send channel instead of access_channel are not valid for v2026.

---

Summary of All Changes

---

Migration Guide

Complete these steps to ensure readiness for v2026:

---

See the Versioning and Deprecation Policy for the full lifecycle rules and headers.