Copy page

Guides

Payment widget

Payment widget

Embed Clearway checkout on a merchant site. The browser never holds your API key — your server proxies requests to {docsEnv.apiHost}.

Technical integration details: Checkout integration.

Architecture

Role	Who	Key rule
Merchant site (browser)	Your storefront	Never holds clwy_live_…
Merchant server	Your backend route	Holds the API key in env only
Clearway widget	Script from {docsEnv.widgetScriptUrl}	Calls your proxy only
Clearway platform	API + pay pages	Your server talks here

Try the interactive demo on the dashboard at https://app-dev.clearway.to/widget/demo.

1. Create a widget API key

1. Complete onboarding (charges + identity).
2. Open https://app-dev.clearway.to/developer/api/keys.
3. Create a Widget / Checkout key.
4. Store the plain key only on your server.

2. Add the widget script and Pay button CSS

Code
<link rel="stylesheet" href="{docsEnv.dashboardUrl}/widget/v1/pay-button.css" />
<script src="{docsEnv.widgetScriptUrl}"></script>

3. Add a server proxy (required)

Implement POST /api/your-store/clearway/checkout (or similar) on your backend. Forward JSON to {docsEnv.apiBaseUrl}/CREATE_CHECKOUT_SESSION with your API key.

Return payPageUrl and session identifiers to the widget — never the API key.

4. Open checkout from your page

Code
ClearwayWidget.init({
  checkoutProxyUrl: 'https://your-store.com/api/clearway/checkout',
  payButtonDefaults: {
    labelTemplate: 'Pay {amount}',
    animation: 'shimmer',
    accentColor: '#0f766e',
  },
});

ClearwayWidget.applyPayButtonElement(
  document.getElementById('pay-button'),
  null,
  { amountLabel: '$75.00', productName: 'Consultation', currency: 'USD' },
);

document.getElementById('pay-button').addEventListener('click', () => {
  ClearwayWidget.openCheckout({
    amount: 7500,
    currency: 'USD',
    productName: 'Consultation',
  });
});

The widget resolves Pay button styling on your site before checkout. payButtonOverride refreshes your button label at click time — it does not change hosted checkout UI.

Pay button tools in the dashboard

Tool	URL	Use
Playground	https://app-dev.clearway.to/widget/demo	Integration snippets + live preview
Animation Lab	https://app-dev.clearway.to/widget/checkout-lab	Compare animations; Use in Playground
Appearance	https://app-dev.clearway.to/integrations/branding/appearance	Save default animation/label for embeds

Checkout presentation (popup, modal, side panel): see Animation Lab → Scenarios section.

Next steps

• Checkout integration — full proxy contract
• API keys and scopes
• Checkout and branding