Skip to main content
The POS SDK has a plugin system for extending behavior — intercepting requests, overriding UI components, and hooking into events.

Using Plugins

Register plugins at initialization or at runtime:
import { MyazaPOS, AnalyticsPlugin } from '@myazahq/pos-sdk';

// At initialization
const pos = new MyazaPOS({
  merchantId: 'your-merchant-id',
  plugins: [new AnalyticsPlugin()],
});

// Or at runtime
pos.use(new AnalyticsPlugin({ endpoint: 'https://analytics.example.com' }));

Built-in Plugins

AnalyticsPlugin

Tracks payment events and reports them to an analytics endpoint.
import { AnalyticsPlugin } from '@myazahq/pos-sdk';

const analytics = new AnalyticsPlugin({
  endpoint: 'https://analytics.example.com/events', // optional
  properties: {                                      // optional
    appVersion: '2.1.0',
    environment: 'production',
  },
});

pos.use(analytics);
OptionTypeDescription
endpointstringURL to send analytics events to
propertiesRecord<string, string>Extra properties attached to every event

ShopifyPlugin

Integrates the checkout flow with Shopify stores.
import { ShopifyPlugin } from '@myazahq/pos-sdk';

pos.use(new ShopifyPlugin({
  shopDomain: 'my-store.myshopify.com',
  orderStatusUrlTemplate: '/orders/{orderId}/status', // optional
  enableAppBridge: true,                               // optional
}));
OptionTypeDescription
shopDomainstringYour Shopify store domain
orderStatusUrlTemplatestringTemplate for order status URL
enableAppBridgebooleanEnable Shopify App Bridge integration

Creating Custom Plugins

A plugin implements the MyazaPlugin interface:
import type { MyazaPlugin, PluginSDKInterface } from '@myazahq/pos-sdk';

const myPlugin: MyazaPlugin = {
  id: 'com.example.my-plugin',
  name: 'My Custom Plugin',
  version: '1.0.0',

  install(sdk: PluginSDKInterface) {
    // Subscribe to events
    sdk.on('payment.confirmed', (event) => {
      console.log(`[MyPlugin] Payment confirmed: ${event.session.id}`);
    });

    // Access SDK state
    console.log('Current state:', sdk.getState());
    console.log('Merchant:', sdk.getMerchantId());
  },

  uninstall() {
    // Clean up resources
  },
};

pos.use(myPlugin);

Request & Response Interceptors

Plugins can modify API requests and responses:
const loggingPlugin: MyazaPlugin = {
  id: 'com.example.logging',
  name: 'Request Logger',
  version: '1.0.0',

  install(sdk) {},

  requestInterceptors: [
    async (request) => {
      console.log(`→ ${request.method} ${request.url}`);
      // Add custom headers
      request.headers['X-Custom-Header'] = 'value';
      return request;
    },
  ],

  responseInterceptors: [
    async (response) => {
      console.log(`← ${response.status}`);
      return response;
    },
  ],
};

UI Component Overrides

Replace parts of the checkout modal with custom components:
const brandingPlugin: MyazaPlugin = {
  id: 'com.example.branding',
  name: 'Custom Branding',
  version: '1.0.0',

  install(sdk) {},

  uiOverrides: [
    {
      slot: 'header',
      render(context) {
        const el = document.createElement('div');
        el.innerHTML = `
          <h2>Pay for Order #${context.orderId}</h2>
          <p>${context.amount} ${context.asset} on ${context.chain}</p>
        `;
        return el;
      },
    },
  ],
};
Available UI slots:
SlotDescription
headerTop of the checkout modal
footerBottom of the checkout modal
status_bannerStatus message area
qr_codeQR code display area
amount_displayPayment amount section

Custom States

Plugins can define custom state machine states:
const reviewPlugin: MyazaPlugin = {
  id: 'com.example.review',
  name: 'Manual Review',
  version: '1.0.0',

  install(sdk) {
    sdk.on('fraud.review_completed', (event) => {
      if (event.action === 'review') {
        console.log('Manual review required');
      }
    });
  },

  customStates: [
    {
      name: 'MANUAL_REVIEW',
      from: ['FRAUD_REVIEW'],
      to: ['CONFIRMED', 'CANCELLED'],
    },
  ],
};

Multi-Tenant Setup

Register multiple merchant configurations on a single SDK instance:
const pos = new MyazaPOS({ merchantId: 'primary-merchant' });
await pos.init();

// Register additional merchants
pos.registerMerchant({
  merchantId: 'secondary-merchant',
  apiKey: 'sk_secondary_...',
  theme: { primaryColor: '#FF6B6B' },
  successUrl: 'https://shop-b.example.com/success',
  fraud: { maxAmountUsd: 5000 },
});