Copy page

Guides

Checkout integration

Checkout integration

Embed Clearway checkout on a merchant site using the proxy-first widget. The browser never sees your clwy_ API key.

Four roles

Role	Who	Rule
Merchant site (browser)	Your storefront JS	Calls your proxy only
Merchant server	Your backend route	Holds the API key in environment variables
Clearway widget	{docsEnv.widgetScriptUrl}	Calls your proxy, not {docsEnv.apiHost} directly
Clearway platform	{docsEnv.apiHost} + {docsEnv.paySiteUrl}	Your server talks here

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 with required scopes (create:checkout_session, create:payment_link).
4. Store the plain key only on your server.

2. Host the widget script

Code
<script src="{docsEnv.widgetScriptUrl}"></script>

3. Implement a server proxy

Your backend receives checkout payloads from the widget and forwards them to the merchant API:

Code
POST {docsEnv.apiBaseUrl}/CREATE_CHECKOUT_SESSION
Authorization: Bearer YOUR_SERVER_KEY
Content-Type: application/json

{
  "amount": 7500,
  "currency": "USD",
  "productName": "Consultation",
  "linkUsage": "one_off"
}

Successful responses include a Clearway pay page URL on {docsEnv.paySiteUrl} (embedded checkout), for example payPageUrl.

Return that URL (and any session identifiers your frontend needs) to the widget — do not expose the API key.

4. Initialize the widget

Code
<script src="{docsEnv.widgetScriptUrl}"></script>
<script>
  ClearwayWidget.init({
    checkoutProxyUrl: 'https://your-store.com/api/clearway/checkout',
  });

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

Errors and idempotency

Pass through API errors (401, 403, 429) to your frontend with actionable messages. Send Idempotency-Key on money-moving proxy calls — see Idempotency.

Next steps

• API keys and scopes — widget key template
• Payment widget (dashboard) — merchant UI walkthrough
• API Reference — Checkout tag operations