Versioning & SDK Management

When integrating with the Checkout feature, understanding how versioning works is crucial to ensuring consistency and stability across payment processes.

Key Benefits of Versioning

• Consistency: Explicitly specifying versions in both templates and API requests ensures that merchant checkout processes behave as expected across different environments (e.g., preproduction, production)

• Transparency: The versioning system is designed to be as transparent as possible, so merchants always know which version they are working with

• Control and Stability: By managing versions explicitly, merchants can control when to adopt new features or patches, ensuring that their payment workflows remain stable even as updates are released

Versioning in Templates

When a merchant creates Configuration or Customisation templates in the Dashboard, they will see the 'Version' field. This field is important because it allows them to manage and apply different versions of their templates across various checkout workflows.

• Version Transparency: Each version of a template corresponds to a specific set of features and behaviours. By specifying the version in the template, merchants can ensure that the same configuration is applied consistently across all their checkouts.

• Backward Compatibility: If the merchant updates a template to a new version, previous versions remain supported. This means they can maintain older checkout workflows without disruption while taking advantage of new features in updated versions.

Versioning in the Create Intent Endpoint

When generating an intent using the /intent API endpoint, merchants need to explicitly pass the version of the workflow that they want to use. This is key to maintaining consistency between the API and the Master Widget.

• Explicit Versioning: By specifying the workflow version in merchants' API request, they ensure that the API and the Master Widget are aligned. This removes any ambiguity about which version of the checkout process is being used, reducing the risk of inconsistencies.

• Stability During Updates: Even as PowerBoard releases updates to the API and Master Widget, their integration remains stable. Merchants only move to a new version of the workflow when they are ready, giving them control over the timing of any changes.

Versioning Considerations

PowerBoard strongly recommends explicitly using specific SDK version tags rather than the 'latest' version to maintain full control over updates. A common scenario for updating implementations includes:

• PowerBoard releases a new Configuration or Customisation template version with enhanced capabilities.
• Merchants test the new version in a pre-production environment.
  • Create or modify templates for compatibility with the new version.
  • Update the existing /intent API requests to reference the updated version.
  • Update the SDK version explicitly to ensure compatibility.

Smart SDK Lookup Implementation Approach

PowerBoard offers a Smart SDK Lookup, dynamically providing the optimal SDK URL based on the merchant's environment and selected API version at runtime.

This simplifies SDK management, reduces risks, and enhances operational stability.

Adoption of Smart SDK Lookup is recommended, but not mandatory.

How it Works

Upon performing an intent request (POST /v1/checkouts/intent), PowerBoard returns a recommended SDK URL (recommended_sdk_version_url).

Merchants then dynamically integrate this URL into their frontend application to automatically load the suitable SDK version.

This is based on the 'version' field, where PowerBoard internally detects "if intent API = version x, then return recommended_sdk_version = y. This is what PowerBoard confirms compatibility with.

Example /intent API response

{
  "status": 201,
  "error": null,
  "resource": {
    "type": "checkout",
    "data": {
      "_id": "67ebc3d489371611a783c2bc",
      "version": 1,
      "status": "active",
      "amount": 1,
      "currency": "AUD",
      "reference": "123456",
      "description": "Sample order",
      "created_at": "2025-04-01T10:45:40.825Z",
      "updated_at": "2025-04-01T10:45:40.825Z",
      "token": "eyJhbG...wcqo",
      "recommended_sdk_version_url": "https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.js"
    }
  }
}

Implementation Steps

Merchants should dynamically embed the recommended SDK URL within the <script> tag on their checkout page as follows:

<script src=${recommended_sdk_version_url}></script>

Best Practices for SDK Injection

• Runtime SDK Injection: Always dynamically load the SDK URL from the intent request response.
• Avoid Static URLs: Do not use static SDK URLs or the /latest tag, as these could lead to breaking changes outside the merchant's control.

Advantages and Disadvantages of the Smart SDK Lookup Approach

Advantages:

• Reduces manual SDK version management.
• Ensures SDK and checkout API compatibility.
• Minimises merchant-side technical overhead.
• Ensures timely access to critical updates.

Disadvantages:

• Requires merchants to have flexible frontend logic to accept dynamic URLs.

Alternative Approach

While Smart SDK Lookup is highly recommended, PowerBoard also allows Explicit Static Versioning as an alternative option.

Merchants can manually specify exact SDK version URLs and subsequently they can periodically update during merchant releases or critical updates.

📘

Note:

Using the stable version may prevent access to updated functionality or new improvements for the SDK widget.