Cashier Bootstrapper

Lightweight iframe bootstrapper for the Morefin cashier. It builds the cashier URL from request params and mounts the cashier inside an iframe to keep host styles isolated.

Installation

npm install @morefin/cashier-bootstrapper

Usage

Throughout the examples below, set an environment once and reuse it:

const CASHIER_ENVIRONMENT = 'uat' as const; // 'production' | 'uat'

Basic Embed

import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';

new CashierBootstrapper('#cashier-root', {
  properties: { environment: CASHIER_ENVIRONMENT }
});

Custom Request Params and Iframe Options

import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';

new CashierBootstrapper('#cashier-root', {
  requestParams: {
    merchantId: 'merchant-123',
    terminalId: 'terminal-456',
    userId: 'user-789',
    sessionId: 'session-abc',
    locale: 'sv_SE',
    channel: 'ios',
    predefinedAmounts: [100, 200, 300],
    layout: 'default',
    transactionType: ('deposit'|'withdrawal'),
    attributes: {
      campaign: 'spring-launch',
      isVip: true
    }
  },
  properties: {
    environment: CASHIER_ENVIRONMENT,
    iframe: {
      height: '720px',
      minHeight: '640px',
      title: 'Morefin Cashier',
      attributes: {
        'data-testid': 'cashier-iframe'
      }
    }
  }
}, api => {
  console.log('Cashier iframe ready', api.iframe);
});

requestParams.channel selects the cashier payment method order channel. Supported values are windows, mac, ios, android, and other; when omitted, the bootstrapper derives it from the user device.

requestParams.attributes sends custom cashier data as the attributes query parameter. Use it for values the cashier should receive as part of the request payload. It does not control payment method ordering.

properties.iframe.attributes applies plain HTML attributes directly to the rendered <iframe>. Use it for DOM concerns such as data-*, loading, or other iframe element attributes.

Provide Container via Config

import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';

new CashierBootstrapper(null, {
  properties: {
    environment: CASHIER_ENVIRONMENT,
    container: '#cashier-root'
  }
});

Runtime Controls (CSS + Data)

import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';

new CashierBootstrapper('#cashier-root', {
  properties: { environment: CASHIER_ENVIRONMENT }
}, api => {
  api.setCss(`
    .payment-layout-root .payment-container {
      border: 2px dashed hotpink;
    }
  `);

  api.updateData({ userId: 'updated-user' });
});

Transaction Result Callbacks

import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';

new CashierBootstrapper('#cashier-root', {
  properties: { environment: CASHIER_ENVIRONMENT },
  callbacks: {
    onSuccess: ({ status, transactionId }) => {
      console.log('Cashier success callback', status, transactionId);
    },
    onFailure: ({ status, message, transactionId }) => {
      console.log('Cashier failure callback', status, message, transactionId);
    },
    onCancel: ({ status, transactionId }) => {
      console.log('Cashier cancel callback', status, transactionId);
    },
    onValidationFailed: ({ message }) => {
      console.log('Cashier validation failed callback', message);
    }
  }
});

Callback mapping:

• onSuccess: result status APPROVED or DECLINED
• onFailure: result status INVALID (or explicit cashier error event)
• onCancel: result status CANCELLED
• onValidationFailed: /validate request failed; message is forwarded from cashier

API

new CashierBootstrapper(container, config?, onReady?)

Iframe-based embed that loads the cashier URL and exposes runtime controls once ready.

Parameters:

• container: string | HTMLElement | null | undefined - Where the iframe is appended. If omitted, config.properties.container is used (falling back to document.body).
• config?: CashierIframeConfig - Request params and iframe properties. properties.environment is required.
• config.callbacks?: CashierCallbacks - Host callback handlers for cashier result events.
• onReady?: (api: CashierIframeApi) => void - Called when the iframe loads; exposes helpers:
  • api.setCss(css: string) – inject CSS inside the cashier iframe
  • api.updateData(data: object) – post updated APP_DATA to the cashier
  • api.pause() / api.resume() – forward pause/resume signals

Types

interface CashierRequestParams {
  merchantId?: string;
  terminalId?: string;
  userId?: string;
  sessionId?: string;
  locale?: string;
  channel?: CashierRuntimeChannel | string;
  predefinedAmounts?: number[];
  layout?: string;
  transactionType?: string;
  attributes?: Record<string, unknown>;
}

type CashierRuntimeChannel = 'windows' | 'mac' | 'ios' | 'android' | 'other';

type CashierEnvironment = 'production' | 'uat';

interface CashierIframeOptions {
  width?: string;
  height?: string;
  minHeight?: string;
  title?: string;
  allow?: string;
  sandbox?: string;
  attributes?: Record<string, string>;
}

interface CashierIframeProperties {
  environment: CashierEnvironment;
  container?: string | HTMLElement;
  iframe?: CashierIframeOptions;
}

interface CashierIframeConfig {
  requestParams?: CashierRequestParams;
  properties?: CashierIframeProperties;
  callbacks?: CashierCallbacks;
}

interface CashierResultCallbackPayload {
  status?: string;
  transactionId?: string;
  message?: string;
}

interface CashierValidationFailedPayload {
  message: string;
}

interface CashierCallbacks {
  onSuccess?: (payload: CashierResultCallbackPayload) => void;
  onFailure?: (payload: CashierResultCallbackPayload) => void;
  onCancel?: (payload: CashierResultCallbackPayload) => void;
  onValidationFailed?: (payload: CashierValidationFailedPayload) => void;
}