---
title: "Framekit integration guide"
url: "https://platformdocs.coinme.com/#/docs/web-integration-guide"
markdown: "https://platformdocs.coinme.com/docs/web-integration-guide.md"
summary: "End-to-end reference for partners embedding the Coinme Widget in a web page with the Widget SDK for the web, `@coinme/coinme-bridge-framekit`. For the shortest path, start with the quick start."
surface: "ramp"
platform: "web"
package: "@coinme/coinme-bridge-framekit"
version: "1.1.2"
peerDependencies: {"react":">=18.0.0","react-dom":">=18.0.0"}
updated: "2026-10-23"
---

# Framekit integration guide

End-to-end reference for partners embedding the Coinme Widget in a web page with the Widget SDK for the web, `@coinme/coinme-bridge-framekit`. For the shortest path, start with the [quick start](https://platformdocs.coinme.com/docs/web-quick-start.md).

## Installation

Add an `.npmrc` to your project:

```
@coinme:registry=https://npm.coinme.com/coinme-sdk-frontend/
//npm.coinme.com/coinme-sdk-frontend/:_authToken=${COINME_REGISTRY_TOKEN}
always-auth=true
```

```bash
yarn add @coinme/coinme-bridge-framekit
```

The package is published to the Coinme private npm registry. The entitlement token is issued by Coinme: ask your Coinme integration contact if you don't have one.

For React partners (optional, but ergonomic):

```bash
yarn add react@>=18 react-dom@>=18
```

React is an optional peer dependency. Skipping it means you only ship the vanilla bundle.

## Container element

Framekit takes a DOM element (or CSS selector) and mounts a single iframe inside it. The iframe is sized to `100% × 100%` of the container; the partner controls container dimensions via CSS.

```markup
<div
  id="coinme-mount"
  style="width: 100%; height: 720px; border-radius: 12px;"
></div>
```

If you pass a CSS selector and it doesn't match an `HTMLElement`, `createCoinmeFrame` throws `CoinmeError.containerNotFound` synchronously.

## CoinmeConfig fields

The `CoinmeConfig` interface, grouped by purpose. `rampId` is required; everything else is optional. The [field table on Build](https://platformdocs.coinme.com/pages/build/index.md#config) lists every field the installed package declares.

### Identity & partner

| Field | Type | Description |
| --- | --- | --- |
| `rampId` ★ | `string` | Identifies the ramp/integration in Coinme's systems. |
| `partnerKey` | `string` | Partner-scoped API key issued by Coinme. Informational on the web; add it only if the same integration also ships inside native WebViews, where it is validated. |
| `partnerId` | `string` | Optional partner identifier (separate from `partnerKey`). |
| `rampName` | `string` | Human-readable ramp name. |
| `environment` | `'prod' \| 'stage' \| 'dev'` | Has no effect: the Widget ignores it. Leave it unset; `orchestratorUrl` picks the environment. |
| `externalSessionId` | `string` | Partner-controlled session correlation ID. |

### Transaction prefill

| Field | Type | Description |
| --- | --- | --- |
| `sourceAmount` | `number` | Fiat amount to pre-fill. |
| `sourceCurrency` | `string` | Fiat currency code (e.g. `'USD'`). |
| `destinationCurrency` | `string` | Cryptocurrency to pre-select (e.g. `'BTC'`, `'ETH'`). |
| `walletAddress` | `string` | Crypto wallet address to pre-fill. |

### Lock flags (default `false`)

| Field | Type | Description |
| --- | --- | --- |
| `sourceAmountLock` | `boolean` | Lock the source-amount field. |
| `sourceCurrencyLock` | `boolean` | Lock the source-currency field. |
| `destinationCurrencyLock` | `boolean` | Lock the destination-currency field. |
| `walletAddressLock` | `boolean` | Lock the wallet-address field (wire key: `walletLock`). |

Locks emit only when `true` (parity with iOS / Android).

### UX

| Field | Type | Description |
| --- | --- | --- |
| `theme` | `'light' \| 'dark'` | Visual theme for the Orchestrator UI. |
| `language` | `string` | BCP-47 language tag (e.g. `'en'`, `'es-MX'`). |
| `flowId` | `string` | Defaults to `'greendot'` (parity with native shells). |

### Permissions

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `allowsCamera` | `boolean` | `true` | Maps to iframe `allow="camera; microphone"`. |
| `allowsLocation` | `boolean` | `true` | Maps to iframe `allow="geolocation"`. |
| `allowsCapture` | `boolean` | `false` | **No-op on web.** Kept for cross-platform `CoinmeConfig` parity with iOS / Android (where it gates screen-capture protection). |

### Geo & metadata

| Field | Type | Description |
| --- | --- | --- |
| `location.lat` / `location.long` | `string` | Geolocation hints (string form mirrors native). |
| `location.city` / `location.state` / `location.streetAddress` | `string` | Postal location hints. |
| `metadata.source` / `metadata.campaign` / `metadata.referralCode` / `metadata.deviceType` | `string` | Free-form attribution / instrumentation. |

Location and metadata are flattened into the top-level `rampConfig` wire payload (iOS / Android parity).

## Mounting the frame

```typescript
import { createCoinmeFrame } from '@coinme/coinme-bridge-framekit';

const frame = createCoinmeFrame({
  container: '#coinme-mount',
  orchestratorUrl: 'https://stage-widget.coinme.com',
  config: {
    rampId: 'your-ramp-id',
    destinationCurrency: 'BTC',
  },
  onEvent: (event) => {
    /* ... */
  },
  onError: (err) => {
    /* ... */
  },
  onSessionReady: () => {
    /* ... */
  },
  onSessionEnded: () => {
    /* ... */
  },
});
```

`orchestratorUrl` picks the environment: `https://stage-widget.coinme.com` for testing, `https://widget.coinme.com` for production. The Widget loads only in pages whose hostname is on the Orchestrator embed allowlist, so give Coinme each hostname you embed from (hostnames only, no scheme or port).

`createCoinmeFrame` is **synchronous**:

- Returns the `CoinmeFrame` handle immediately.
- Throws `CoinmeError.invalidConfig`, `CoinmeError.invalidOrchestratorUrl`, or `CoinmeError.containerNotFound` on construction failure; no DOM mutation occurs in those cases.
- Begins the handshake asynchronously. `onSessionReady` fires once the Orchestrator emits `bridge-session-ready` (typically within 1 to 2 seconds).

## Handling events

```typescript
onEvent: (event) => {
  switch (event.type) {
    case 'transactionComplete':
      // event.payload is a JsonObject
      reportSuccessToBackend(event.payload);
      break;
    case 'transactionFailed':
      reportFailureToBackend(event.payload);
      break;
    case 'userCancelled':
      navigateAway();
      break;
    case 'kycRequired':
      // Orchestrator is asking the user to complete KYC
      break;
    case 'sheetOpened':
      hidePartnerBackButton();
      break;
    case 'sheetClosed':
      showPartnerBackButton();
      break;
    case 'transactionRejected':
      // Handle this if your config locks the asset or transaction type: the
      // ramp rejected the locked value and the Orchestrator signs the user
      // out. The frame stays up; tell the user, or send updateConfig with a
      // different asset or an unlocked field. event.payload carries
      // { asset, transactionType }.
      handleRejectedTransaction(event.payload);
      break;
    case 'redirectRequested':
      // The widget asks you to navigate (the redirectUrl call-to-action).
      window.location.assign(String(event.payload.url));
      break;
    case 'closeRequested':
      // The widget asks to be dismissed (e.g. unsupported-asset acknowledged).
      unmountWidget();
      break;
    case 'sessionEnded':
      // The user logged out inside the widget.
      resetPartnerUi();
      break;
    case 'authStateChanged':
      // { authenticated, customer_email, customer_id } for personalization.
      syncSignInState(event.payload);
      break;
    case 'backAvailabilityChanged':
      // { canGoBack }: drive your own back affordance.
      setBackButtonVisible(Boolean(event.payload.canGoBack));
      break;
    case 'barcodeGenerated':
      // Cash flows: { orderTemplateId, timestamp }. Store it: the
      // host.barcode.resume action can resume this order later.
      rememberPendingOrder(event.payload);
      break;
    case 'barcodeInvalidated':
      // { orderTemplateId, reason: 'user-cancelled' | 'expired' | ... }
      forgetPendingOrder(event.payload);
      break;
    case 'kycCompleted':
      // The bookend of kycRequired: identity verification succeeded.
      break;
    case 'supportRequested':
      // The user asked for support; open your own support channel if you
      // have one.
      break;
    case 'signOutRequested':
      // The user requested sign-out from an error state.
      resetPartnerUi();
      break;
    case 'transactionRestarted':
      // { reason, errorCode? }: funnel analytics.
      break;
    case 'unknown':
      // Forward-compat: log event.eventType, but don't fail.
      console.warn('Unknown Coinme event:', event.eventType, event.payload);
      break;
  }
};
```

Every variant carries the full event payload envelope: the properties noted above arrive inside `event.payload` alongside the raw `eventType` string.

The `unknown` variant lets you handle newer Orchestrator events without a framekit upgrade.

> **Forwarding dependency**
>
> the flow-level events (per-method transaction completion, barcode lifecycle, KYC, sign-out and support requests) reach the host only from Orchestrator releases that forward them. If one never arrives, ask your Coinme integration contact.

Lifecycle events (`bridge-session-ready`, `bridge.session.ended`) do **not** flow through `onEvent`; they drive `onSessionReady` / `onSessionEnded`.

## Handling errors

```typescript
onError: (err) => {
  switch (err.kind) {
    case 'handshakeTimeout':
      // Orchestrator unreachable, CSP blocking, or the host not allowlisted
      break;
    case 'originMismatch':
      // Probably an Orchestrator URL mismatch
      break;
    case 'bridgeMessageParsingFailed':
      // Unrecognised inbound envelope, usually a foreign SDK on the page
      break;
    default:
      console.error(err);
  }
};
```

Synchronous errors from public methods (e.g. calling one after `destroy()`) bubble normally: wrap them in `try/catch`.

## Updating config at runtime

```typescript
frame.updateConfig({ destinationCurrency: 'ETH' });
```

The patch is merged into the stored config (shallow merge for `location` / `metadata`); framekit emits an `updateConfig` envelope to the Orchestrator. If called before `bridge-session-ready`, the envelope is queued and flushed in order on ready.

## Teardown

```typescript
frame.destroy();
```

Removes the iframe, removes the `'message'` listener, rejects in-flight RPC promises with `CoinmeError.destroyed`, and clears the queue. `destroy` is idempotent; method calls after destroy throw `CoinmeError.destroyed`.

If the session had started (the Orchestrator acknowledged the handshake) and had not already ended, `destroy()` then fires `onSessionEnded`: synchronously, once, after teardown, so `frame.isReady` is already `false` inside the handler. `onSessionEnded` fires at most once per session whichever way it ends, so a `bridge.session.ended` from the Orchestrator followed by `destroy()` notifies once. Destroying a frame before the handshake fires nothing. The React wrappers destroy their frame on unmount and on an `orchestratorUrl` change, so their `onSessionEnded` fires then too, and `useCoinmeFrame`'s `isReady` returns to `false` after `frame.destroy()`.

## React

### `<CoinmeFrame />` component

```tsx
import { CoinmeFrame } from '@coinme/coinme-bridge-framekit/react';

<CoinmeFrame
  orchestratorUrl="https://stage-widget.coinme.com"
  config={config}
  onEvent={(e) => /* ... */}
  onError={(e) => /* ... */}
  className="my-coinme-host"
  style={{ width: '100%', height: '720px' }}
/>
```

- Renders a wrapper `<div ref className style />` and mounts the iframe inside on first render.
- Changing the `config` prop diffs against the previous render and emits `frame.updateConfig(diff)`, with no remount.
- Changing `orchestratorUrl` remounts: a new iframe and a new bridge session. It is the only prop that does.
- Changing `iframeAttributes` updates `title`, `name`, `loading` and `className` on the live iframe, with no remount. Contents are compared by value, so an inline object literal with unchanged values does nothing; an attribute removed from the object reverts to framekit's default (`title="Coinme"`, `loading="eager"`, no `name` or `class`).
- `protocolVersion`, `handshakeTimeoutMs`, `partnerSource` and `seedConfigInUrl` are **read once at mount**. Changing one afterwards is ignored and, in development builds (`process.env.NODE_ENV !== 'production'`), logs a one-time `console.warn`. To apply a new value, remount deliberately by changing the component's React `key` (or `orchestratorUrl`).
- Callback identity changes do **not** remount: the latest closure runs on the next event.
- Construction errors (`invalidConfig`, `invalidOrchestratorUrl`, `containerNotFound`) are delivered to `onError`, as with `useCoinmeFrame`, and the wrapper `<div>` renders empty. If you omit `onError`, the error is rethrown from the mount effect to the nearest React error boundary, since the component has no other way to report it.
- Forwarded ref exposes the imperative `CoinmeFrameRefHandle` (the `CoinmeFrame` handle, with `iframe` typed `HTMLIFrameElement | null`):

```tsx
const ref = useRef<CoinmeFrameRefHandle>(null);
<CoinmeFrame ref={ref} ... />
// later:
ref.current?.updateConfig({ language: 'es' });
```

The ref is attached before the frame is created (the frame mounts in an effect after the first commit). While no frame is mounted (before that effect has run, after the component unmounts, or when construction failed), the methods `updateConfig` and `destroy` both throw the same "CoinmeFrame is not mounted" `Error`. Reading a property never throws: `isReady` reads `false` and `iframe` reads `null`. Once mounted, every member delegates to the live frame (so, for example, `updateConfig` after `destroy()` throws `CoinmeError.destroyed`), except that `iframe` reads `null` again after `ref.current.destroy()`, because the destroyed frame's iframe has been removed.

Property reads never throw because React's development build reads every property of a ref's value when it logs a failed effect. A throwing getter would escape your error boundary and replace the real error. A ref typed `useRef<CoinmeFrameHandle>(null)` still compiles, but it types `iframe` as never `null`, so prefer `CoinmeFrameRefHandle`.

### `useCoinmeFrame()` hook

For partners who manage their own container element:

```tsx
const containerRef = useRef<HTMLDivElement>(null);
const { frame, isReady, error } = useCoinmeFrame({
  container: containerRef,
  orchestratorUrl: 'https://stage-widget.coinme.com',
  config: { rampId: 'your-ramp-id' },
});
return <div ref={containerRef} style={{ height: '720px' }} />;
```

Construction errors never throw from the hook: they are delivered to `onError` (when given) and exposed as `error`, with `frame` left `null`. Cleans up automatically on unmount. Follows the same option rules as `<CoinmeFrame />`: only `orchestratorUrl` remounts, `config` changes are diffed into `frame.updateConfig`, `iframeAttributes` changes are applied to the live iframe, and the fixed-at-mount options above are ignored after mount (with a development warning).

## Observability

Framekit emits debug-level logs prefixed `[CoinmeBridge]`. They are gated:

- `globalThis.__COINME_BRIDGE_DEBUG__ = true` turns them on at runtime.
- `VITE_BRIDGE_DEBUG=true` does the same for Vite-built consumers.

Notable log events:

- `bridge.message.parse-failed`: inbound envelope failed shape validation.
- `bridge.message.origin-mismatch`: `MessageEvent.origin` ≠ orchestrator origin.
- `bridge.unhandled-message-type`: inbound message type not consumed by the session.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `CoinmeError.invalidOrchestratorUrl` | Not https / not a loopback host | Use https, or use `http://localhost` for dev. |
| `CoinmeError.handshakeTimeout` | Orchestrator unreachable, CSP blocks iframe, referrer policy stripped, or the hostname is not on the embed allowlist | Check network, allow the Orchestrator origin in CSP, verify `referrerpolicy="strict-origin-when-cross-origin"` is present on the iframe, and confirm with Coinme that your hostname is allowlisted. |
| `CoinmeError.originMismatch` repeats | Mixed `orchestratorUrl` (trailing slash / subdomain) | Confirm the origin of `orchestratorUrl` (scheme, host and port) equals the Orchestrator's real origin. |
| `bridgeMessageParsingFailed` repeats | Foreign SDK posting messages on the same page | Inspect `event.data`; benign unless it's high-volume. |
| `frame.updateConfig` after `destroy` throws `CoinmeError.destroyed` | Stale handle reference | Don't hold the handle past teardown; re-create with `createCoinmeFrame` for a fresh session. |
