@polar-sh/checkout

JavaScript utilities for embedding Polar into your website. Drop in the single CDN script (auto-init) or import per-feature from npm for tree-shaking.

Payment Method

A customer session token authenticates every embed. Create it on your server — your Polar access token must stay secret — then hand the token to the browser. The SDK accepts either a polar_cst_* or polar_mst_* prefix and routes internally.

Javascript

Modal

A full-screen overlay the SDK creates and tears down for you — open it on demand, e.g. from a button click.

import { Polar } from '@polar-sh/sdk'
import { PolarEmbedPaymentMethod } from '@polar-sh/checkout/payment-method'

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN })
const session = await polar.customerSessions.create({
  customerId: 'ABC-123',
})

const embed = await PolarEmbedPaymentMethod.create({
  sessionToken: session.token,
})

embed.addEventListener('success', (event) => {
  console.log('Attached:', event.detail.paymentMethodId)
})

create() options

Inline

A chrome-less, auto-resizing iframe mounted into an element you control — compose it into your own layout.

import { Polar } from '@polar-sh/sdk'
import { PolarEmbedPaymentMethod } from '@polar-sh/checkout/payment-method'

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN })
const session = await polar.customerSessions.create({
  customerId: 'ABC-123',
})

const embed = PolarEmbedPaymentMethod.createInline({
  sessionToken: session.token,
  element: document.getElementById('polar-payment-method')!,
})

embed.addEventListener('success', (event) => {
  console.log('Attached:', event.detail.paymentMethodId)
})

createInline() options

Events

All events are dispatched as cancelable CustomEvents on the embed instance. Call event.preventDefault() to opt out of the SDK's default action.

Instance methods

Redirect re-entry

Redirect-based payment methods (Amazon Pay etc, etc) authorise on the provider's own site — the browser navigates the whole tab away and back to returnUrl (defaults to the page the SDK was opened from), so the modal can't survive the round-trip. Read the outcome on the returned page with the static getRedirectResult():

const result = PolarEmbedPaymentMethod.getRedirectResult()
// result: { status: 'succeeded' | 'failed' } | null

if (result?.status === 'succeeded') {
  // refresh the customer's payment methods
}

It strips the status param from the URL so a refresh won't resurface a stale result. Card payments (3DS) complete inside the modal and never trigger this path.

React

Modal

Open the full-screen modal with PolarEmbedPaymentMethod.create() — the same API as vanilla JS, called from a Client Component event handler.

import { Polar } from '@polar-sh/sdk'
import { PolarEmbedPaymentMethod } from '@polar-sh/checkout/payment-method'

export function AddPaymentMethodButton({
  sessionToken,
}: {
  sessionToken: string
}) {
  const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN })
  const session = await polar.customerSessions.create({
    customerId: 'ABC-123',
  })

  const openEmbed = async () => {
    const embed = await PolarEmbedPaymentMethod.create({ sessionToken })
    embed.addEventListener('success', (event) => {
      console.log('Attached:', event.detail.paymentMethodId)
    })
  }

  return <button onClick={openEmbed}>Add payment method</button>
}

Inline

Render <PolarPaymentMethod /> for a chrome-less, auto-resizing embed inside your own layout.

import { Polar } from '@polar-sh/sdk'
import { PolarPaymentMethod } from '@polar-sh/checkout/react/payment-method'

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN })
const session = await polar.customerSessions.create({
  customerId: 'ABC-123',
})

return (
  <PolarPaymentMethod
    sessionToken={session.token}
    onSuccess={(id) => console.log('Attached:', id)}
  />
)

Props

Redirect re-entry

Redirect-based payment methods (Amazon Pay etc etc.) navigate the whole tab away to the provider and back. Read the outcome on the returned page with the usePaymentMethodRedirectResult hook:

import { usePaymentMethodRedirectResult } from '@polar-sh/checkout/react/payment-method'

usePaymentMethodRedirectResult({
  onSuccess: () => toast('Payment method added'),
  onError: () => toast('Could not add payment method'),
})

It reads the result once on mount and strips the status param from the URL. Card payments (3DS) complete inside the embed and never trigger this path.

Code snippet

import { Polar } from '@polar-sh/sdk'

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN })
const session = await polar.customerSessions.create({
  customerId: 'ABC-123',
})

<script
  defer
  data-auto-init
  src="https://cdn.jsdelivr.net/npm/@polar-sh/checkout@latest/dist/embed.global.js"
></script>

<!-- session.token rendered into the attribute server-side -->
<button data-polar-payment-method="polar_cst_…">Add payment method</button>

The same script also powers PolarEmbedCheckout triggers — one tag covers every Polar embed.

Attributes