# @confirmo/overlay

> Confirmo overlay library

Latest version **4.6.0** (published 2026-09-01) · 0 weekly downloads

## Install

```sh
npm install @confirmo/overlay
pnpm add @confirmo/overlay
yarn add @confirmo/overlay
bun add @confirmo/overlay
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; large bundle.

## Facts

| | |
|---|---|
| Version | 4.6.0 |
| Published | 2026-09-01 |
| First published | 2019-05-14 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 74.8 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Confirmo |
| Maintainers | profinit.tradpo |

## Links

- npm: https://www.npmjs.com/package/@confirmo/overlay
- npm.io page: https://npm.io/package/@confirmo/overlay

## Dependencies (1)

- [install-peers](https://npm.io/package/install-peers.md) ^1.0.4

## Recent versions

- 4.6.0 (latest) — 2026-09-01
- 2.0.0 (beta) — 2021-03-18
- 4.5.2 — 2026-06-23
- 4.5.1 — 2026-06-22
- 4.5.0 — 2026-06-22
- 4.4.1 — 2025-07-28
- 4.4.0 — 2025-07-28
- 4.3.0 — 2025-04-17
- 4.2.2 — 2024-10-07
- 4.2.1 — 2024-07-04
- 4.2.0 — 2024-07-04
- 4.1.1 — 2024-06-26
- 4.1.0 — 2024-06-26
- 4.0.0 — 2023-08-11
- 3.2.0 — 2022-11-22
- … 13 more at https://npm.io/package/@confirmo/overlay/versions

## README

# Confirmo

### npm

```
npm install @confirmo/overlay
```

### yarn

```
yarn add @confirmo/overlay
```

### pnpm

```
pnpm add @confirmo/overlay
```

### CDN

```html
<!-- To always install exact version (recommended - avoid future breaking changes) -->
<script src="https://cdn.jsdelivr.net/npm/@confirmo/overlay@4.6.0/dist/confirmo.js"></script>
<!-- To always install exact major version -->
<script src="https://cdn.jsdelivr.net/npm/@confirmo/overlay@4/dist/confirmo.js"></script>
<!-- To always install the latest version -->
<script src="https://cdn.jsdelivr.net/npm/@confirmo/overlay@latest/dist/confirmo.js"></script>
```

## Overlay

### Bundlers

```javascript
import { Invoice } from '@confirmo/overlay';

/**
 * Opens Confirmo invoice overlay
 *
 * @param {string} invoice_url - URL of invoice.
 * @param {callback} [callback_fnc] - Optional - callback which is called when overlay was closed
 * @param {InvoiceOverlayConfig} [overlayConfig] - Optional - Confirmo overlay configuration (currently only for auto-close when invoice is paid)
 *
 * @example
 *
 * // URL of invoice created from REST API
 * const invoice_url = 'https://pay.confirmo.com/public/invoice/invv9e1rxdz8?m=mer951dkwdw1';
 *
 * // (optional) Callback which is called when overlay was closed
 * const callback_fnc = () => alert('Overlay has been closed');
 *
 * // (optional) Confirmo overlay configuration
 * const overlayConfig = {
 *   closeAfterPaid: true,
 *   closeAfterPaidTimeoutMs: 2000, // when unspecified, default is 2000ms
 * }
 *
 */
const overlay = Invoice.open(invoice_url, callback_fnc, overlayConfig);

/**
 * Closes Confirmo invoice overlay
 */
overlay.close();
```

### Script Tag

```html
<script>
  const overlay = Confirmo.Invoice.open(invoice_url, callback_fnc, overlayConfig);

  overlay.close();
</script>
```

## Payment button

### HTML

```html
<div id="placeholder-for-button"></div>
```

### Bundlers

```javascript
import { PaymentButton } from '@confirmo/overlay';

/**
 * Creates Confirmo payment button
 */
const button = PaymentButton.initialize(
  {
    id: 'placeholder-for-button',
    paymentButtonId: 'pbt16354asde',
    buttonType: 'SIMPLE',
    values: {
      productName: 'Some cool product',
      productDescription: 'Simple description',
      reference: 'merchantRef',
      returnUrl: 'https://my-cool-eshop.com/?q=this+is+return+url',
      merchantId: 'mer951dkwdw1',
      overlay: true,
    },
  },
  /**
   * Overlay related properties (relevant only if values.overlay set to `true`)
   */
  // (optional) Callback function called on Invoice.close() (see overlay.d.ts)
  () => {
    console.log('Overlay has been closed!');
  },
  // (optional) Invoice overlay config
  overlayConfig,
);

/**
 * Removes Confirmo payment button
 */
button.remove();
```

### Script Tag

```html
<script>
  const button = Confirmo.PaymentButton.initialize(
    {
      id: 'placeholder-for-button',
      paymentButtonId: 'pbt16354asde',
      buttonType: 'SIMPLE',
      values: {
        productName: 'Some cool product',
        productDescription: 'Simple description',
        reference: 'merchantRef',
        returnUrl: 'https://my-cool-eshop.com/?q=this+is+return+url',
        merchantId: 'mer951dkwdw1',
      },
    },
    /**
     * Overlay related properties (relevant only if values.overlay set to `true`)
     */
    // (optional) Callback function called on Invoice.close() (see overlay.d.ts)
    () => {
      console.log('Overlay has been closed!');
    },
    // (optional) Invoice overlay config
    overlayConfig,
  );

  button.remove();
</script>
```

### Overlay events

Events fired from Public invoice view via window#postMessage API https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

A component using @confirmo/overlay can listen to InvoiceOverlayMessageEventData accordingly:

```javascript
import { ConfirmoOverlayInvoiceStatus, ConfirmoOverlayMessageAction, Invoice } from '@confirmo/overlay';

const overlay = Invoice.open(invoiceUrl, callback_fnc);

// Custom implementation of closing Confirmo overlay after invoice being paid
window.addEventListener('message', (event) => {
  if (
    invoiceUrl.includes(event.origin) &&
    event.data.action === ConfirmoOverlayMessageAction.CONFIRMO_OVERLAY_INVOICE_STATUS_CHANGE &&
    event.data.status === ConfirmoOverlayInvoiceStatus.PAID
  ) {
    // handle paid invoice (e.g. by closing the overlay)
    setTimeout(() => {
      overlay.close();
    }, 2000); // close overlay after 2 seconds
  }
});
```

_Note: the same effect as shown above can be achieved simply by setting `overlayConfig`'s `closeAfterPaid`_

```javascript
import { Invoice } from '@confirmo/overlay';

const overlayConfig = {
  closeAfterPaid: true,
};

Invoice.open(invoiceUrl, callback_fnc, overlayConfig);
```

---
_Source: https://npm.io/package/@confirmo/overlay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._