API Tutorials
HELP CENTERINTEGRATIONSSTATUS PAGESIGN UP
Start typing to search…

Checkout Hosted Widget

The Checkout Hosted Widget enables you to embed Cleeng’s purchase flow directly into your web application. It manages the complete checkout process, including payment processing, and ensures compliance with supported payment methods. Using the widget, you can integrate a fully functional transaction flow without building custom payment forms or handling sensitive payment data.

📘

Widgets have been introduced as a Beta feature, meaning it’s ready for real-world use while we gather user feedback to enhance its functionality and address any minor issues.

If you want to learn more about Hosted Widgets, review the currently supported features, and see how they compare to other integration methods, see our overview of available frontend integration options and their benefits.

Prerequisites

Before you begin, make sure you have:

  1. Cleeng account: Create one here.
  2. At least one offer created in the Cleeng dashboard: Learn more about Cleeng offers.
  3. Payment methods enabled for your account (if not already enabled, contact Cleeng Support).
    📘

    To ensure you have any Adyen payment method enabled, call Fetch payment method ids.

Code Integration

To embed a Cleeng widget, follow these steps:

1. Include the Cleeng-hosted script in your HTML file

🚧

If your application already uses another Cleeng widget and has included the cleeng.js script, skip this step.

In the index.html, or any HTML file of your app that will be loaded before using a Cleeng widget, include a Cleeng-hosted script.

🚧

The script must be loaded from Cleeng’s domain to ensure it is always up to date.

Do not attempt to self-host cleeng.js script, as it carries a risk of incompatibility in case of any product updates and security enhancements.

<script type="module" src="https://widgets.sandbox.cleeng.com/cleeng.js"></script>

For the production environment, the URL for the script will be different:

2. Create a container for the widget

Create an empty HTML container, e.g., <div /> element, with required data as data-* attributes, as in the example below:

<div
  data-cleeng-widget="checkout"
  data-cleeng-publisher-id="123"
  data-cleeng-offer-id="S123_US"
/>

Where:

  • data-cleeng-widget: the specific Cleeng widget you would like to render. Supported values: auth, checkout, account.
  • data-cleeng-publisher-id: Your unique Cleeng publisher ID (found in the Cleeng Dashboard under Admin & Tools > API Keys).
  • data-cleeng-offer-id: The unique ID of the offer (found in the Cleeng Dashboard under Offers & Coupons > Offers > ID column).
    You can also fetch offer IDs using https://developers.cleeng.com/reference/fetch-offers API endpoint.

The SDK monitors changes to data attributes and automatically updates widgets when relevant configuration changes. This allows for reactive updates without manual re-initialization. The widgets will detect the value's change and re-render automatically.

For the Checkout to display correctly, the user needs to be logged in. If they previously used the Auth widget, the Checkout widget will automatically detect that the user is authenticated and show the payment flow.

Alternatively, if you’re not using the Auth widget for authentication, you can pass a jwt token to the Checkout widget (by setAuthTokens method), so that it correctly knows the user credentials.

3. (Optional) Support for external authentication flow (SSO)

If your application uses an external identity provider, you can integrate Single Sign-On (SSO) with Cleeng’s widgets by programmatically passing authentication tokens.

After a user successfully logs in or registers through your external system, and you've generated the necessary jwt and refreshToken using Cleeng's SSO Login API endpoint, use the window.cleeng.setAuthTokens() method to authenticate the user in the widget.

This function sends the tokens to the widget and ensures that:

  • The user's session is recognized across Cleeng widgets.
  • The authenticated state remains synchronized when tokens are refreshed or reissued.

Call this method whenever the user's authentication state changes – the user logs in, logs out, or their tokens change. This keeps the frontend session in sync across your application and the Cleeng widgets.

Example:

// Set authentication tokens for all widgets
await window.cleeng.setAuthTokens({
  jwt: 'your-jwt-token',
  refreshToken: 'your-refresh-token'
});

As setAuthTokens method returns a Promise object, be sure to await its resolution. This way, you ensure that setting the authentication tokens will not be disrupted, and the application will proceed further only after this operation has finished.

4. Apple Pay production environment setup

To enable Apple Pay in a production environment, please follow the steps below:

  1. Host the Apple Pay Domain Association File

    1. Download and unzip the domain association file.

    2. Host the file with the exact name apple-developer-merchantid-domain-association on each domain (live environments, as well as any relevant subdomains) at the following path:
      https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association

      File requirements:

      • Must have the header Content-Type: text/plain.
      • Must be publicly accessible.
      • Must not be password-protected.
      • Must not be behind a proxy or redirect.
      • Must use Unix line endings.
        You can find an example of a valid domain association file here.

  2. Contact Cleeng Technical Support

    Reach out to the Cleeng Technical Support team to whitelist your domains for Apple Pay. Please provide a complete list of the domains where you plan to enable Apple Pay.

    Once both steps are completed, Apple Pay will be ready to use in your production environment.

    🚧

    Important: Until setup is complete, we recommend filtering out Apple Pay from the Checkout (Cleeng Dashboard -> Integration Hub). This will prevent it from being displayed to customers and avoid potential confusion.

5) (Optional) Integrate with the widgets methods

Widgets provide a simple way to communicate with your application, which is especially useful in the case of:

  • External identity provider (SSO) or
  • Making additional requests to the Mediastore API.

You can integrate with the available global methods by following the steps in the Global Communication Methods Developer Guide.

Configuration in the Cleeng Dashboard

After embedding the widget, configure it using the dashboard configuration instructions. The configuration page lets you adjust widget behavior and branding without redeploying your code. All changes you make in the dashboard are applied automatically to the deployed widgets.

Testing

Before deploying, ensure proper functionality through testing:

  1. Embed and load the Widget
    • Verify the widget appears correctly in your app
  2. User Authentication
    • If you use the default Cleeng identity management: Test user login and registration by the Auth widget.
    • If you use an external identity management: First, test your backend connection to Cleeng by ensuring that your system can successfully generate and retrieve JWT and refresh tokens via the SSO Login endpoint. Then, provide these tokens to the widgets (by setAuthTokens() method) and verify that authentication works correctly.
  3. Payment Flow
    • Emebed Checkout widget
    • Once user is authenticated, use a test offer and process payments with the sandbox environment. Depending on the payment success or failure, the confirmation screen will be presented in the widget.

By following these steps, you can ensure a smooth and error-free integration before going live.

What’s next

Once implemented, an iframe containing the Cleeng widget will be embedded into your application. The widget will automatically apply settings configured in the dashboard and react to changes in the data-* attributes.

To use a different widget, update the data-cleeng-widget attribute with the desired widget name.

Updated about 10 hours ago