Web Elements

Tilta Web Elements let you embed fully functional onboarding and payment flows directly inside your platform’s UI. Instead of redirecting users away from your application, you render Tilta’s flows as a Widget (an inline component within your page layout) or a Modal (a full-screen overlay triggered by a button or event). Both options use the same SDK and short-lived JWT tokens, so you get a branded experience without building the underlying financial flows yourself.

Prerequisites

Before installing the SDK, confirm your environment meets the following requirements:

Node.js v12.x or later
npm 6.x or later, or yarn 1.22.x or later
Your application must be served over HTTPS (Content Security Policy headers are enforced). Localhost is also supported for development.
A Tilta account with sandbox access – contact support@tilta.io if you do not have credentials yet.

Installation

Add the Web Elements SDK to your project

Choose the installation method that fits your stack:

Npm
Yarn
Script tag (CDN)

npm install @tilta/embed

yarn add @tilta/embed

Add the following <script> tag to the <head> of your HTML page. This loads the SDK from Tilta’s sandbox CDN – replace the URL with the production endpoint when you go live.

<script src="https://embed.tilta-sandbox.io/embed.js"></script>

Add the modal stylesheet

If you plan to use the Modal component, include Tilta’s CSS file so the overlay renders correctly:

<link rel="stylesheet" href="https://embed.tilta-sandbox.io/css/modal.css" />

Place this inside the <head> tag of your HTML, or import it at the top of your root stylesheet.

Import the SDK functions

When using the npm or yarn package, import the functions you need at the top of your component or script file:

import { createWidget, createModal } from '@tilta/embed';

Obtain a session token

Web Elements are authenticated with a short-lived JWT. Request a token from the Tilta API on your server before rendering any element, and pass it to the client. Never generate or store tokens in client-side code.

curl --request POST \
     --url https://api.tilta-sandbox.io/v1/tokens \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{"buyer_external_id": "buyer_001"}'

The response contains a token string – pass this to createWidget or createModal in the next step.

A Widget renders Tilta’s flow inline within your page. Add a container div to your markup and then call createWidget with the session token.

import { useEffect } from 'react';
import { createWidget } from '@tilta/embed';

export function TiltaWidget({ token }) {
  useEffect(() => {
    createWidget(token);
  }, [token]);

  return <div id="tiltaWidget" />;
}

import { createWidget } from '@tilta/embed';

document.addEventListener('DOMContentLoaded', function () {
  createWidget('your_token_here');
});

Make sure your markup includes the target container element before createWidget is called:

<div id="tiltaWidget"></div>

In React, wrapping the createWidget call inside a useEffect with the token as a dependency ensures the Widget re-initialises correctly if the token is refreshed.

A Modal overlays the current page when triggered. createModal returns a toggle function that you attach to any button or event handler.

import { createModal } from '@tilta/embed';

export function TiltaModalButton({ token }) {
  const { toggle } = createModal(token);

  return (
    <button onClick={toggle}>
      Apply for payment terms
    </button>
  );
}

import { createModal } from '@tilta/embed';

const { toggle } = createModal('your_token_here');

document.getElementById('activateModal').onclick = toggle;

Make sure the Modal CSS is loaded (see the installation steps above) before toggle is called for the first time. Without the stylesheet the overlay will not render correctly.

Token lifecycle

Tilta session tokens are short-lived JWTs. Keep the following in mind:

Tokens expire after a short period – generate a fresh token for each user session.
Always generate tokens server-side using your API key, then pass them to the browser.
If a token expires while the Widget or Modal is open, the user will see an authentication error. Handle this by catching the error event from the SDK and requesting a new token.

Troubleshooting

I see a content security policy (CSP) error in the browser console

Your server’s CSP headers must allow scripts and frames from Tilta’s domains. Add the following to your Content-Security-Policy header:

script-src 'self' https://embed.tilta-sandbox.io https://embed.tilta.io;
frame-src 'self' https://embed.tilta-sandbox.io https://embed.tilta.io;

For local development, also permit localhost in the relevant directives.

CreateWidget is not a function

If you installed the SDK via npm or yarn, confirm the import path is correct:

import { createWidget, createModal } from '@tilta/embed';

If you are using the CDN script tag, the functions are available on the global Tilta object. Check the browser console to confirm the script loaded without errors.

The token I pass is immediately rejected

Tokens must be generated server-side for the correct buyer and environment (sandbox vs. production). Confirm that:

You are using the right base URL for your environment.
The buyer_external_id in the token request matches a registered buyer.
The token is being passed to the SDK immediately after generation and has not expired in transit.

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

Web Elements

Prerequisites

Installation

Rendering a widget

Token lifecycle

Troubleshooting

​Prerequisites

​Installation

​Rendering a widget

​Rendering a modal

​Token lifecycle

​Troubleshooting

Prerequisites

Installation

Rendering a widget

Rendering a modal

Token lifecycle

Troubleshooting