PayOS UI Extension SDK

Package name: @surfair/payos-ui-extension-sdk

Version: 0.1.0-beta.1

This folder contains the beta SDK for building PayOS Dashboard UI Extensions - the sandboxed surfaces an installed App Platform app can mount inside the PayOS dashboard (e.g. a card on a transaction's detail page), declared via dashboardSurfaces.extensionUrl on the app.

What it does

Your extension is a page you host yourself at any HTTPS URL (or http://localhost during development). PayOS loads that page into a sandboxed iframe (sandbox="allow-scripts allow-forms", no allow-same-origin) wherever your dashboardSurfaces declaration matches the current viewport. Your code never touches real HTML in the host - it calls render(tree) with a plain, JSON-serializable description of what to show, and PayOS's own trusted React components paint the actual pixels in the host page. Event handlers (onPress, onChange) fire back into your code as plain callbacks.

Practically this means:

• Your extension can never inject arbitrary HTML/CSS/JS into the host dashboard - only host-controlled component types can ever render, so XSS through this channel isn't possible.
• Your rendered UI automatically matches PayOS's own design system.
• The iframe you run in has no cookies, no localStorage, and cannot read or write the parent page - its own origin is forced opaque even though it's loaded from your real HTTPS URL. Do your own data fetching against your own backend with your own credentials (e.g. an App Platform API key); PayOS does not expose merchant session data to you beyond what's in the context object passed to onReady().

This SDK does not give your extension a way to call PayOS's own business APIs on the merchant's behalf - that bridge is intentionally out of scope for this version. Authenticate to your own backend the same way you would for any other integration.

Quick start

With npm/a bundler:

import { onReady, render } from '@surfair/payos-ui-extension-sdk';

onReady((context) => {
  render({
    type: 'Box',
    props: { direction: 'column', spacing: 'md' },
    children: [
      { type: 'Text', props: { variant: 'heading' }, children: `Hello, ${context.viewport}` },
      { type: 'Button', props: { variant: 'primary', onPress: () => console.log('clicked') }, children: 'Click me' }
    ]
  });
});

Without a build step, drop in the global build directly:

<script src="https://unpkg.com/@surfair/payos-ui-extension-sdk/dist/payos-ui-extension-sdk.global.js"></script>
<script>
  PayOSUI.onReady(function(context) {
    PayOSUI.render({ type: 'Text', props: {}, children: 'Hello, ' + context.viewport });
  });
</script>

See public/demo-extension.html in the dashboard repo for a complete working example, including the two extension state patterns (redraw-on-event, and a sandbox self-check confirming cookies/localStorage are unreachable).

API

• onReady(handler) - fired once with the page context (viewport, resourceType, resourceId, merchantId, appId, installationId, locale) as soon as the host has attached your frame. Call render() from inside this handler to draw your initial UI. If context has already arrived, the handler fires synchronously.
• render(tree) - draws (or redraws) your UI. tree is { type, props, children }. Unknown types/props are silently dropped by the host, not rendered - see the App Platform docs for the full allow-listed component list (Box, Text, Button, TextField, Banner, Spinner, Link, Divider, Badge) and their props, or index.d.ts in this package for the typed version of the same list.
• notify(message, severity?) - shows a toast in the host dashboard. severity defaults to 'info'.
• getContext() - the current context, or null before onReady has fired.

Component allow-list

The host validates every node against a fixed allow-list before rendering it (componentRegistry.js in the dashboard repo is the source of truth) - this is the actual security boundary of the feature, not a convenience. index.d.ts mirrors it exactly, so a TypeScript build will catch an unsupported type or prop before you ship it, rather than it silently rendering as a gap in production.

Build

npm run build

Produces dist/index.mjs (ESM), dist/index.cjs (CommonJS), and dist/payos-ui-extension-sdk.global.js (the <script>-tag build, which sets window.PayOSUI) from the single source of truth at src/index.js. The build also copies the global build into the dashboard app's public/payos-ui-extension-sdk.js, so the in-repo demo extension always exercises exactly what gets published - never a hand-maintained copy that can drift.

Publishing

Mirrors @surfair/payos-sdk's release flow:

• npm run pack:dry-run from this directory to sanity-check the tarball contents.
• CI publishes to the GitLab npm package registry with the beta dist-tag from the default branch, via .gitlab/publish_payos_ui_extension_sdk.sh.