Embedded checkout

The embedded checkout shows the hosted Warp checkout inside your page, in a modal, or in a popup, instead of redirecting the customer. It is the same checkout page, so wallet connection, quotes and on-chain verification work exactly as with a redirect.

Package	Use it for	Links
`@warpfi/react`	React 18+ and Next.js	Guide · npm · GitHub
`@warpfi/vue`	Vue 3.3+ and Nuxt	Guide · npm · GitHub
`@warpfi/js`	Any other site: ES module, `<script>` tag or the `<warp-checkout>` web component	Guide · npm · GitHub

For a step-by-step setup with full Next.js, Nuxt and Express examples, see Set up the SDKs.

Events from the embedded checkout are UI signals only. Fulfil orders from the payment.completed webhook or by retrieving the session on your server.

How it works

Create a session on your server

Create the session with your secret key, as usual, and set return_url or cancel_url to a page on the site that embeds the checkout. Return checkout_url to the browser.

Embed it

Pass the URL (or a function that fetches it) to the component. It loads the checkout in an iframe, modal or popup.

React to events

The checkout reports ready, status changes, completion, cancel and return. Use them to update your UI.

Server

The browser never sees your secret key. This example uses the Node.js SDK:

import Warp from '@warpfi/node'

const warp = new Warp(process.env.WARP_SECRET_KEY!)

app.post('/api/checkout', async (req, res) => {
  const order = await getOrder(req.body.orderId) // amount from your records, never from the browser
  const session = await warp.checkout.sessions.create({
    amount_usd: order.totalUsd,
    metadata: { order_id: order.id },
    return_url: `https://example.com/orders/${order.id}`,
    cancel_url: 'https://example.com/cart',
  })
  res.json({ checkoutUrl: session.checkout_url })
})

Client

React
Vue
JavaScript
Script tag

npm install @warpfi/react

'use client'

import { WarpCheckout, PayWithWarpButton } from '@warpfi/react'

async function createCheckout(orderId: string): Promise<string> {
  const res = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ orderId }),
  })
  if (!res.ok) throw new Error('Could not start checkout')
  return (await res.json()).checkoutUrl
}

// Inline
export function Checkout({ orderId }: { orderId: string }) {
  return (
    <WarpCheckout
      fetchCheckoutUrl={() => createCheckout(orderId)}
      onComplete={() => console.log('Paid, waiting for the webhook')}
      onCancel={() => history.back()}
    />
  )
}

// Modal (or mode="popup" / mode="redirect")
export function BuyButton({ orderId }: { orderId: string }) {
  return <PayWithWarpButton fetchCheckoutUrl={() => createCheckout(orderId)} />
}

useWarpCheckout(options) returns openModal, openPopup, close, status, sessionId, isOpen and error for custom buttons.

npm install @warpfi/vue

<script setup lang="ts">
import { WarpCheckout, PayWithWarpButton } from '@warpfi/vue'

const props = defineProps<{ orderId: string }>()

async function createCheckout(): Promise<string> {
  const res = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ orderId: props.orderId }),
  })
  if (!res.ok) throw new Error('Could not start checkout')
  return (await res.json()).checkoutUrl
}

function onPaid() {
  console.log('Paid, waiting for the webhook')
}
</script>

<template>
  <!-- Inline -->
  <WarpCheckout :fetch-checkout-url="createCheckout" @complete="onPaid" @cancel="$router.back()" />

  <!-- Modal (or mode="popup" / mode="redirect") -->
  <PayWithWarpButton :fetch-checkout-url="createCheckout" />
</template>

useWarpCheckout(options) returns openModal, openPopup, close and the refs status, sessionId, isOpen and error. WarpPlugin registers both components globally.

npm install @warpfi/js

import { mountCheckout, openCheckoutModal } from '@warpfi/js'

async function fetchCheckoutUrl(): Promise<string> {
  const res = await fetch('/api/checkout', { method: 'POST' })
  return (await res.json()).checkoutUrl
}

// Inline
const checkout = await mountCheckout('#checkout', {
  fetchCheckoutUrl,
  onComplete: () => (window.location.href = '/thanks'),
})

// Modal
document.querySelector('#pay')!.addEventListener('click', () => {
  openCheckoutModal({ fetchCheckoutUrl, onComplete: showThankYou }).catch(() => {})
})

<div id="checkout"></div>
<script src="https://cdn.jsdelivr.net/npm/@warpfi/js@0/dist/warp.global.js"></script>
<script>
  Warp.mountCheckout('#checkout', {
    fetchCheckoutUrl: () =>
      fetch('/api/checkout', { method: 'POST' }).then((r) => r.json()).then((d) => d.checkoutUrl),
    onComplete: () => (window.location.href = '/thanks'),
  })
</script>

The script also registers a web component: <warp-checkout checkout-url="..." theme="auto">, which dispatches warp:ready, warp:status, warp:complete, warp:cancel, warp:return and warp:error.

Display modes

Mode	Function	Notes
Inline	`mountCheckout` / `<WarpCheckout>`	An iframe in your layout that resizes to its content.
Modal	`openCheckoutModal` / `PayWithWarpButton`	A full-screen overlay. Closes on Escape, backdrop click, the close button, and after the customer returns.
Popup	`openCheckoutPopup` / `mode="popup"`	A new window, for pages that cannot frame the checkout. Must be opened from a click.
Redirect	`mode="redirect"`	Sends the customer to `checkout_url`, like a plain integration.

All modes accept theme (light, dark or auto). Match it to your page so the iframe background blends in.

Events

Callback	When
`onReady`	The checkout loaded.
`onStatus(status)`	On load and on every change: `pending`, `processing`, `completed`, `failed`, `expired`.
`onComplete`	The status became `completed` (once).
`onCancel`	The customer clicked Cancel and return, or closed the modal or popup before paying.
`onReturn`	The customer clicked Back to merchant on the success page.
`onClose`	A modal or popup closed, for any reason.
`onError(error)`	A `WarpCheckoutError`.

In embed mode the cancel and return buttons send events instead of navigating, so your page decides what happens next.

Error code	Meaning
`invalid_checkout_url`	The URL is not a Warp checkout session URL.
`fetch_failed`	Your `fetchCheckoutUrl` threw or returned no URL.
`popup_blocked`	The browser blocked the popup.
`load_failed`	The checkout did not load within 15 seconds, usually because framing is not allowed for this origin.
`destroyed`	The checkout was closed before it finished loading.

Allowed origins

The checkout can only be framed by, and only sends events to, the origins of the session’s return_url and cancel_url. Testnet sessions (created with an sk_test_ key) also allow http://localhost and http://127.0.0.1 on any port, for local development.

Set return_url or cancel_url to a page on the site that embeds the checkout. A session without either cannot be embedded; redirect to checkout_url instead.
If your site sends a Content-Security-Policy, add frame-src https://checkout.usewarp.net.
For popups, do not send Cross-Origin-Opener-Policy: same-origin; use same-origin-allow-popups.

Next steps

Webhooks

Confirm payments on your server.

Node.js SDK

Create sessions and verify webhooks.

Set up with examples

Full Next.js, Nuxt and Express walkthroughs.

SDK overview

Every package with npm and GitHub links.

Getting started

Pay with Warp

SDKs

ZK Proofs

Roadmap

Embedded checkout

How it works

Server

Client

Display modes

Events

Allowed origins

Next steps

Webhooks

Node.js SDK

Set up with examples

SDK overview

​How it works

​Server

​Client

​Display modes

​Events

​Allowed origins

​Next steps

Webhooks

Node.js SDK

Set up with examples

SDK overview

How it works

Server

Client

Display modes

Events

Allowed origins

Next steps