@havenpay/web-elements

Custom elements for Havenpay browser checkout interfaces.

@havenpay/web-elements is the optional UI companion to @havenpay/web. It provides framework-neutral custom elements for checkout layout, mobile-money phone capture, OTP submission, payment sheet state, and payment status rendering.

The elements are presentational. They do not call Havenpay APIs, do not store payment secrets, and do not decide payment truth. Host applications listen for events and call @havenpay/web or @havenpay/web/headless.

Install

bun add @havenpay/web-elements @havenpay/web

npm install @havenpay/web-elements @havenpay/web

Use it for

• Plain HTML checkout pages.
• React, Vue, Angular, Svelte, or server-rendered apps that want framework-neutral payment UI.
• Mobile-money form, OTP, retry, cancel, and status components.
• Themed checkout surfaces using CSS custom properties and ::part.

Quickstart

import { initHavenpay } from '@havenpay/web'
import '@havenpay/web-elements'

const havenpay = initHavenpay({
  environment: 'test',
  projectId: 'proj_...',
})

await havenpay.initPaymentSheet({
  clientSecret: 'pi_client_secret_from_your_server',
})

document
  .querySelector('havenpay-mobile-money-form')
  ?.addEventListener('havenpay:confirm', async (event) => {
    const detail = (event as CustomEvent<{ msisdn: string }>).detail
    await havenpay.confirmPayment({ msisdn: detail.msisdn })
  })

document
  .querySelector('havenpay-otp-sheet')
  ?.addEventListener('havenpay:submit-action', async (event) => {
    const detail = (event as CustomEvent<{ action: { type: 'mobile_money_otp', otp: string } }>).detail
    await havenpay.submitAction(detail.action)
  })

<havenpay-checkout>
  <havenpay-payment-sheet heading="Pay with mobile money">
    <havenpay-mobile-money-form></havenpay-mobile-money-form>
    <havenpay-otp-sheet></havenpay-otp-sheet>
    <havenpay-payment-status></havenpay-payment-status>
  </havenpay-payment-sheet>
</havenpay-checkout>

Elements

| Element | Purpose | | --- | --- | | <havenpay-checkout> | Checkout shell for composing payment UI. | | <havenpay-payment-sheet> | Payment-sheet container and state surface. | | <havenpay-mobile-money-form> | Customer phone capture and confirm event. | | <havenpay-otp-sheet> | OTP entry, resend, cancel, and submit-action events. | | <havenpay-payment-status> | Payment status rendering with polite live updates. |

Events

| Event | Purpose | | --- | --- | | havenpay:confirm | Host app should call confirmPayment. | | havenpay:submit-action | Host app should call submitAction. | | havenpay:resend-action | Host app should call resendAction. | | havenpay:cancel | Host app should call cancelPayment. | | havenpay:status | Host app can observe element state changes. |

Events are composed so host apps can listen outside the shadow root.

Registration

Importing the package registers elements when a browser custom-element registry exists:

import '@havenpay/web-elements'

For explicit timing, SSR-safe setup, or stricter tree shaking:

import { defineHavenpayElements } from '@havenpay/web-elements/define'

await defineHavenpayElements()

The root @havenpay/web-elements entrypoint auto-registers elements when globalThis.customElements exists. The @havenpay/web-elements/define subpath does not auto-register and is the preferred import for applications that control registration timing.

Styling

Elements use open Shadow DOM, named part attributes, and CSS custom properties. Host apps own page-level layout, focus strategy, localization, and final brand styling.

havenpay-payment-sheet::part(surface) {
  border-radius: 8px;
}

havenpay-payment-status {
  --havenpay-accent: #1463ff;
}

Security boundary

The elements do not accept clientSecret as an attribute or property. They must not expose API keys, webhook secrets, provider credentials, customer PINs, or raw provider payloads.

Use custom events to connect UI interactions to the headless browser SDK. Keep payment authorization in @havenpay/web, and keep secret-key operations on your backend with @havenpay/server.

Package boundaries

This package intentionally depends on browser platform APIs and Svelte-generated custom elements. It is not a server SDK, not a React Native SDK, and not a provider adapter.

Use:

• @havenpay/web for the browser payment client.
• @havenpay/core for shared public types.
• @havenpay/server for backend-only secret-key operations.

Browser support

The package targets modern browsers with native Custom Elements, Shadow DOM, ES modules, dynamic import, CustomEvent, CSS custom properties, and ::part. It does not ship polyfills. Apps that need older browser support should provide their own polyfills or build a custom UI with @havenpay/web.