Run the workflow inside your application

Learn how to render the workflow directly inside your application using an iframe for a seamless user experience.

You’ll build a simple integration where the user completes a workflow directly inside your app.

The example includes both client- and server-side code, and shows how to create a workflow execution and render the interface using the embedded mode. The workflow UI is securely loaded in an <iframe>, allowing you to fully integrate the process into your product without redirecting the user to an external page.

This setup is ideal for cases where you want full control over the user experience and visual consistency with your product.

Use this approach when:

• The workflow is part of an onboarding, verification, or registration flow

• You want to avoid any external redirection

• You need to match the look & feel of your existing UI

• You're building internal tooling or back-office processes with light user input

---

1

Set up the server

Create a Workflow Execution

Add an endpoint on your server that creates a Workflow Execution. The response includes a token, which is used on the client side to initialize and mount the widget. Return the token in your response so it can be passed to the widget in the frontend.

We recommend creating a new execution each time a user starts a workflow, to ensure that the flow is fresh and state is isolated for every attempt.

Node.js

const express = require('express');
const axios = require('axios');

const API_BASE = process.env.API_BASE ?? 'https://api.transactionlink.io';

// --- Recommended: organization token (tot_) ---
const ORG_TOKEN = process.env.ORG_TOKEN ?? 'tot_<your-organization-token>';

// --- Legacy: workspace credentials (JWT) — deprecated, will be removed in a future release ---
const KEY = process.env.KEY ?? '<your-key>';
const SECRET = process.env.SECRET ?? '<your-secret>';

const WF_DEF_ID = process.env.WF_DEF_ID ?? '<your-workflow-definition-id>';

const api = axios.create({ baseURL: API_BASE });

const app = express();
app.use(express.json());

// Legacy: obtain a JWT access token using workspace credentials.
// Deprecated in favor of organization tokens (tot_).
async function authorizeWithJwt() {
    const { data } = await api.post('/auth/authorize', { key: KEY, secret: SECRET });
    return data.accessToken;
}

// Returns the Authorization header value for the current auth strategy.
// Switch to the legacy option below if you haven't migrated to organization tokens yet.
function getAuthHeader() {
    // Recommended: pass the organization token directly (no Bearer prefix)
    return ORG_TOKEN;

    // Legacy (deprecated): obtain a JWT and pass it as a Bearer token
    // const jwt = await authorizeWithJwt();
    // return `Bearer ${jwt}`;
}

app.post('/create-workflow', async (_req, res) => {

    const payload = {
        workflowDefinitionId: WF_DEF_ID,
        expiresAt: new Date(Date.now() + 61 * 60 * 1000).toISOString(),
        locale: 'en',
    };

    const { data } = await api.post('/workflows', payload, {
        headers: { Authorization: getAuthHeader() },
    });

    res.json({ token: data.token, workflowId: data.id });

});

app.get('/workflow-status', async (req, res) => {

    const workflowId = req.query.workflowId;

    const { data } = await api.get(`/workflows/${workflowId}`, {
        headers: { Authorization: getAuthHeader() },
    }).catch(reason => console.log(reason));

    res.json({ status: data.status, workflowId: data.id });

});

app.listen(8080, () => console.log('Running on port 8080'));

Set the workflow to execute

workflowDefinitionId – UUID (required) The ID of the workflow you want to execute. This refers to a predefined flow configured in your TransactionLink Dashboard.

📌 You can find the workflowDefinitionId in the Dashboard by viewing the workflow’s details.

---

Set an expiration time

expiresAt – ISO 8601 timestamp

Defines when the workflow execution becomes invalid.

• Must be between 30 minutes and 30 days from creation.

• If omitted, defaults to 1 hour.

🔐 Use this to enforce time-limited actions (e.g. document upload, identity verification) and avoid stale sessions.

---

Set the interface language

locale – IETF language tag (e.g. en, pl, de)

Controls the language of the user-facing interface.

• If left blank, we detect the user’s browser language.

• Use this to enforce a specific language for localized flows.

2

Build your page

See full demo code at https://github.com/transactionlink/examples

Create HTML element for widget

Add an HTML on your page that will be replaced with an embedded Transactionlink widget. Place either <transactionlink-widget />or <div id="transactionlink-widget" /> element

<transactionlink-widget />

Obtain an ID and a token

Use an API created on your server in previous step to receive an execution ID and token for your workflow. You can trigger an HTTP call for the token when your application needs to launch the widget - on a button click, page load, or in any other scenario that is specific to your use case.

async function createWorkflowExecution() {
    try {
        const response = await fetch('/workflow-execution', { method: 'POST' });
        const data = await response.json()
        return data;
    } catch (err) {
        console.error(err);
        throw err;
    }
}

Initialize widget

Append the widget script to the page and define a callback function as window.transactionlink_ready. It will be executed when the script is ready, so that you can pass the previously obtained token and launch the widget.

Vanilla HTML/JS

<script>
async function launchWidget() {
    const { workflowId, token } = await createWorkflowExecution();

    window.transactionlink_ready = () => {
        transactionlink.setOptions({ token });
        transactionlink.open();
    };

    const script = document.createElement('script');
    script.src = 'https://widget.transactionlink.io/transactionlink-widget.umd.js';
    document.head.appendChild(script);
}

document.getElementById('launch-widget')
    .addEventListener('click', launchWidget);
</script>

<!-- Button to trigger the widget -->
<button id="launch-widget">Launch Embedded Widget</button>

<transactionlink-widget />

React component

Await for workflow status (optional)

If you want your app to be notified when the workflow has been completed, you can poll for workflow status. It may be useful to close the Transactionlink widget and update your UI.

Update your launchWidget function as follows:

Vanilla HTML/JS

let scriptAdded = false;

async function createWorkflowExecution() {
    try {
        const response = await fetch('http://localhost:8080/create-workflow', {
            method: 'POST'
        });
        const data = await response.json();
        return data;
    } catch (err) {
        console.error('Failed to create workflow execution:', err);
        throw err;
    }
}

async function launchWidget() {
    try {
        const { workflowId, token } = await createWorkflowExecution();

        if (!scriptAdded) {
            // Set only once
            window.transactionlink_ready = () => openWidget(workflowId, token);

            const script = document.createElement('script');
            script.src = 'https://widget.transactionlink.io/transactionlink-widget.umd.js';
            document.head.appendChild(script);

            scriptAdded = true;
        } else {
            openWidget(workflowId, token);
        }
    } catch (err) {
        console.error('Error during widget launch:', err);
    }
}

async function isWorkflowFinished(workflowId) {
    try {
        const response = await fetch(`http://localhost:8080/workflow-status?workflowId=${workflowId}`);
        const data = await response.json();

        console.log('Workflow status:', data.status);

        return data.status === 'COMPLETED';
    } catch (err) {
        console.error('Error checking workflow status:', err);
        return false;
    }
}

async function openWidget(workflowId, token) {
    if (!window.transactionlink) {
        console.error('transactionlink object is not available yet.');
        return;
    }

    transactionlink.setOptions({ token });
    transactionlink.open();

    let finished = false;

    while (!finished) {
        await new Promise(resolve => setTimeout(resolve, 2000));
        finished = await isWorkflowFinished(workflowId);
    }

    transactionlink.close();
}

document.getElementById('launch-widget')
    .addEventListener('click', launchWidget);

3

Get notified about workflow status

There are two ways to notify your backend when something happens in the workflow

1. Webhook Task

You can add a Webhook Task directly in your workflow. This lets you send a custom HTTP POST request to your server at any point during the flow — with a payload you fully control.

Use it when:

• You want to notify your backend during a specific step in the process

• You need to trigger external logic or update another system

• You want to send dynamic data collected earlier in the flow

• You want to notify your server when the process is completed — with your own payload

Tip: Place a Webhook Task at the end of the workflow to send a custom completion signal, including any relevant context or identifiers.

Both options can be used together or independently — depending on your use case.

2. Polling the API (Long polling)

As an alternative, you can implement long polling from your backend. This involves periodically calling the TransactionLink API to check the status of a specific workflow execution.

While not real-time, long polling can be useful when:

• You cannot expose a public webhook endpoint

• Your infrastructure requires strict control over incoming connections

• You need fallback logic when webhooks are unavailable or blocked

Keep in mind: Webhooks (automatic or via task) are the recommended approach for real-time and scalable integration.

4

Congratulations!

You’ve successfully set up a basic TransactionLink integration.

Now, learn how to customize your workflow experience — from styling the hosted page to configuring dynamic logic and automating data collection using workflow tasks and parameters.