@havenpay/web

Headless browser SDK for Havenpay checkout flows.

@havenpay/web runs in modern browsers and uses the public projectId plus a short-lived payment clientSecret created by a merchant backend. It owns the browser payment-session client, typed actions, retry policy, timeout handling, and reload recovery primitives while leaving UI fully under your control.

It never accepts merchant secret API keys, webhook secrets, provider credentials, provider PINs, server SDK imports, Node built-ins, React, React Native, or Svelte.

Install

bun add @havenpay/web

npm install @havenpay/web

Use it for

• Browser checkout pages that need a custom UI.
• Payment-sheet retrieval and presentation state.
• Mobile-money confirmation with a customer phone number.
• Provider-neutral customer actions such as OTP submission, resend, cancel, and status refresh.
• Reload recovery without storing payment secrets in browser storage.

Quickstart

Your server creates a PaymentIntent with @havenpay/server and returns only the public client payload needed by the browser.

import { initHavenpay } from '@havenpay/web'

const havenpay = initHavenpay({
  environment: 'test',
  projectId: 'proj_...',
  requestPolicy: {
    maxReadRetries: 1,
    retryBackoffMs: 100,
    timeoutMs: 10000,
  },
})

await havenpay.initPaymentSheet({
  clientSecret: 'pi_client_secret_from_your_server',
  returnUrl: 'https://merchant.example/checkout/return',
})

const intent = await havenpay.confirmPayment({
  msisdn: '+263771234567',
})

if (intent.nextAction?.type === 'mobile_money_otp') {
  await havenpay.submitAction({
    type: 'mobile_money_otp',
    otp: '123456',
  })
}

Runtime model

The browser SDK sends:

• Authorization: Bearer <clientSecret>
• X-Haven-Project: <projectId>
• X-Haven-Environment: test | live

The projectId is public. The clientSecret is short-lived and scoped to one payment, project, account, environment, and allowed client operation set. If a page reloads, reacquire a fresh/current client secret from your backend before recovery.

API surface

const havenpay = initHavenpay({ environment, projectId })

await havenpay.initPaymentSheet({ clientSecret, returnUrl })
await havenpay.presentPaymentSheet()
await havenpay.retrievePaymentIntent()
await havenpay.confirmPayment({ msisdn })
await havenpay.submitAction({ type: 'mobile_money_otp', otp })
await havenpay.resendAction()
await havenpay.cancelPayment()

Reads may retry transient network, timeout, and 5xx failures according to requestPolicy. Mutations do not retry by default because provider outcomes can be ambiguous. On mutation errors, retrieve payment state before deciding what the customer should do next.

Recovery

initPaymentSheet stores only non-secret recovery data in history.state:

• project ID
• environment
• payment intent ID
• optional return URL
• update timestamp

It does not write clientSecret to history.state, localStorage, or sessionStorage.

import {
  initHavenpay,
  readHavenpayRecoverySnapshot,
} from '@havenpay/web'

const snapshot = readHavenpayRecoverySnapshot()

if (snapshot) {
  const { clientSecret } = await fetch('/checkout/client-secret').then(response => response.json())

  await initHavenpay({
    environment: snapshot.environment,
    projectId: snapshot.projectId,
  }).recoverPaymentSession({
    clientSecret,
    snapshot,
  })
}

Entrypoints

| Entrypoint | Contents | | --- | --- | | @havenpay/web | Default browser SDK exports. | | @havenpay/web/headless | Headless client and recovery helpers. | | @havenpay/web/browser | Browser-safe alias for app bundlers. | | @havenpay/web/testing | Test helpers for SDK consumers. |

Security boundary

Keep this package in client code only. It must never receive or expose:

• Merchant secret API keys.
• Webhook signing secrets.
• Provider credentials or provider PINs.
• Account admin tokens.
• Server SDK objects.
• Raw provider responses.

Only your backend should create PaymentIntents, manage projects, rotate keys, verify webhooks, configure provider accounts, or request refunds.

Package boundaries

Use @havenpay/web when you want to own the browser UI. Use @havenpay/web-elements only if you want optional custom elements for checkout, OTP, and status views. Both packages depend on the same public client-secret payment model and neither package owns payment truth.

For server-owned operations, use @havenpay/server.