Developers

HWF V2 → V2026 Version Migration — Key Changes

The changes below cover the Hosted Web Form (HWF) versioning model from v2 through v2026 and provides a concise migration path from V2 to V2026. HWF exposes versioned JavaScript via CDN and versioned REST endpoints. The latest version (v2026) is recommended.

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

  • CDN example: https://jsco.billerpayments.com/app/opco/v2026/scripts/checkoutofsc.js
  • API endpoint example: https://apico.billerpayments.com/app/opco/v2026/service/payments/token

What's New

  • Updated Path-based versioning via CDN script URL and API base path (e.g. /app/opco/v2026/scripts/, /app/opco/v2026/service/)
  • Implemented Strict versioning model from v2026 i.e, API version and JS CDN version must align (v2026 with v2026)
  • All Server-side SDKs (Java, Python, C#, Node.js, PHP) are now deprecated.Direct REST integration is required for server side integration

Version Changes

Listed newest to oldest. Earlier jumps may still affect your integration if you are migrating from v2, v3, or v4.

v5 → v2026

  • URI namespace modification (e.g. /app/opco/v5/scripts → /app/opco/v2026/scripts)
  • Strict versioning model begins with v2026
  • Idempotent request key is mandatory in server side integration.
  • Server-side SDKs deprecated, direct REST integration required
Action required:
  • Do direct REST integration instead of using server-side SDKs.
  • Send idempotent request key in server side API request. 
# Before (v5)
<script id="orbipay-checkout-script" src="https://jsco.billerpayments.com/app/opco/v5/scripts/checkoutofsc.js"></script>

# After (v2026)
<script id="orbipay-checkout-script" src="https://jsco.billerpayments.com/app/opco/v2026/scripts/checkoutofsc.js"></script>

# Before (v5)
POST /app/opco/v5/service/payments/token

# After (v2026)
POST /app/opco/v2026/service/payments/token

v4 → v2026

  • Renamed data-id_account → data-id_funding_account. Legacy fields are still supported
  • Added New fields for MPA Support : data-association_type, data-delink_other_customer_accounts, data-customer_account_status
  • Added New field data-is_fs_required to post extra funding account details to merchant callback based on the parameter
  • Added state-based fee waiver support
  • URI namespace modification (e.g. /app/opco/v4/scripts → /app/opco/v2026/scripts)
  • Strict versioning model begins with v2026
  • Idempotent request key is mandatory in server side integration.
  • Server-side SDKs deprecated, direct REST integration required
Action required:
  • Update data-id_account attribute to data-id_funding_account.
  • Do direct REST integration instead of using server-side SDKs.
  • Send idempotent request key in server side API request.

v3 → v2026

  • Removed data-live_mode . v2026 uses base path and API version from the src URL
  • Used data-customer_* for payer address. Legacy fields are still supported
  • Introduced data-dispatch_custom_event_to_parent, from checkout to post custom events to the parent window
  • Removed copying zip to postal code for non-USA countries {Only Specific Partner}
  • Modified URI namespace (e.g. /app/opco/v3/scripts → /app/opco/v2026/scripts)
  • Renamed data-id_account → data-id_funding_account. Legacy fields are still supported
  • Added New fields for MPA Support : data-association_type, data-delink_other_customer_accounts, data-customer_account_status
  • Added New field data-is_fs_required to post extra funding account details to merchant callback based on the parameter
  • Added state-based fee waiver support
  • Strict versioning model begins with v2026
  • Idempotent request key is mandatory in server side integration.
  • Server-side SDKs deprecated, direct REST integration required
Action required:
  • Do not set data-live_mode attribute.
  • Update all customer address fields to use data-customer_* attributes.
  • Update data-id_account attribute to data-id_funding_account.
  • Do direct REST integration instead of using server-side SDKs.
  • Send idempotent request key in server side API request.

v2 → v2026

  • Added Fee support
  • Added reCAPTCHA v2 support
  • Introduced data-customer_first_name and data-customer_last_name rather than a single complete data-customer_name
  • Kept data-client_id / data-client_key in sync when either is set
  • Intoduced new JS Event hwf_form_closing_event when the hosted form closes
  • data-parameters are loaded into the iframe when the iframe is initialized, rather than when the script loads
  • URI corrections and namespace change (e.g. /app/opco/v2/scripts → /app/opco/v2026/scripts)
  • Removed data-live_mode . v2026 uses base path and API version from the src URL
  • Used data-customer_* for payer address. Legacy fields are still supported
  • Introduced data-dispatch_custom_event_to_parent, from checkout to post custom events to the parent window
  • Removed copying zip to postal code for non-USA countries {Only Specific Partner}
  • Renamed data-id_account → data-id_funding_account. Legacy fields are still supported
  • Added New fields for MPA Support : data-association_type, data-delink_other_customer_accounts, data-customer_account_status
  • Added New field data-is_fs_required to post extra funding account details to merchant callback based on the parameter
  • Added state-based fee waiver support
  • Strict versioning model begins with v2026
  • Idempotent request key is mandatory in server side integration.
  • Server-side SDKs deprecated, direct REST integration required
Action required:
  • Update data-customer_name to data-customer_first_name and data-customer_last_name.
  • Update data-client_id to data-client_key.
  • Do not set data-live_mode attribute.
  • Update all customer address fields to use data-customer_* attributes.
  • Update data-id_account attribute to data-id_funding_account.
  • Do direct REST integration instead of using server-side SDKs.
  • Send idempotent request key in server side API request.

Versioning Alignment Rules

From v2026, strict alignment is enforced.

Use a single major version consistently across CDN scripts and API endpoints to avoid incompatibilities.

For more details , please follow Versioning and Deprecation Policy

Migration Guide

Complete these steps to ensure readiness for v2026:

UI integration (CDN)

  • Update the script source to v2026
    • <script id="orbipay-checkout-script" src="https://jsco.billerpayments.com/app/opco/v2026/scripts/checkoutofsc.js"></script>

Backend integration (API)

  • SDK-based server integrations are deprecated, use direct REST integration.
  • Point server calls to v2026 token endpoints.
POST /app/opco/v2026/service/payments/token
POST /app/opco/v2026/service/funding-accounts/token
POST /app/opco/v2026/service/funding-accounts/{ID_ACCOUNT}/token

Notes and Best Practices

  • Prefer the latest app and API versions for security and feature parity.
  • Update request/response validations for field additions from earlier version jumps (payer address from v4, fee logic from v3, funding account attributes from v5) before promoting to production.
  • Align staging and production to the same major version to avoid drift.

References

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