***

title: Mandatory Migration to API-Based Widget URL
slug: guides/migration-to-api-based-transak-widget-url
subtitle: Migration to the Create Widget URL API to generate the widget URL
---------------------------------------------------------------------------

All partners are required to migrate their integration to use the [Create Widget URL API](/api/public/create-widget-url), which generates a secure `widgetUrl` to load the Transak widget.
This approach ensures **secure**, **validated**, and **consistent** integrations across all [integration options](/integration/api/overview).

Passing query parameters directly in the widget URL is **deprecated and no longer supported**.

## How It Works

<Steps>
  <Step title="Generate a Partner Access Token (Backend Only)">
    Call the [Refresh Access Token](/api/public/refresh-access-token) endpoint from your backend to obtain a `Partner Access Token`.

    Store this token securely and reuse it until it expires. When you call the endpoint again, the previously issued token is automatically invalidated.
  </Step>

  <Step title="Create a Widget URL (using Backend Only)">
    Call the [Create Widget URL](/api/public/create-widget-url) to generate a Widget URL by securely passing the [widget parameters](/customization/query-parameters).

    #### Request Headers

    <table>
      <tbody>
        <tr>
          <td>
            <ParamField path="access-token" type="string" required={true}>
              Your Partner Access Token from Step 1.
            </ParamField>

            <ParamField path="authorization" type="string" required={false}>
              User Authorization Token — only required for integrations using the User Authentication API.
            </ParamField>
          </td>
        </tr>
      </tbody>
    </table>

    #### Request Body

    <table>
      <tbody>
        <tr>
          <td>
            <ParamField path="widgetParams" type="object" required={true}>
              Object containing all widget configuration.
            </ParamField>

            <ParamField path="widgetParams.apiKey" type="string" required={true}>
              Your API key from the [Transak Partner Dashboard](https://dashboard.transak.com/).
            </ParamField>

            <ParamField path="widgetParams.referrerDomain" type="string" required={true}>
              Your domain URL (web) or application package name (mobile).
            </ParamField>
          </td>
        </tr>
      </tbody>
    </table>

    <CodeBlocks>
      ```bash title="Staging"
      curl --request POST \
           --url https://api-gateway-stg.transak.com/api/v2/auth/session \
           --header 'accept: application/json' \
           --header 'access-token: YOUR_ACCESS_TOKEN' \
           --header 'authorization: YOUR_USER_AUTH_TOKEN' \
           --header 'content-type: application/json' \
           --data '{
        "widgetParams": {
          "apiKey": "YOUR_API_KEY",
          "referrerDomain": "yourdomain.com",
          "fiatAmount": 300,
          "fiatCurrency": "EUR",
          "cryptoCurrencyCode": "ETH"
        }
      }'
      ```

      ```bash title="Production"
      curl --request POST \
           --url https://api-gateway.transak.com/api/v2/auth/session \
           --header 'accept: application/json' \
           --header 'access-token: YOUR_ACCESS_TOKEN' \
           --header 'authorization: YOUR_USER_AUTH_TOKEN' \
           --header 'content-type: application/json' \
           --data '{
        "widgetParams": {
          "apiKey": "YOUR_API_KEY",
          "referrerDomain": "yourdomain.com",
          "fiatAmount": 300,
          "fiatCurrency": "EUR",
          "cryptoCurrencyCode": "ETH"
        }
      }'
      ```
    </CodeBlocks>

    #### Response

    ```json
    {
      "data": {
        "widgetUrl": "https://global-stg.transak.com?apiKey=YOUR_API_KEY&sessionId=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvdHQiOiI2YzgxMDFiMjlhMzg0YWE2YmRjM2JjMmFkODA1M2YzMyIsImlhdCI6MTc1NzMyNTkwNywiZXhwIjoxNzU3MzI2MjA3fQ.zooQ07sGOnI_2dwtIzYL5sOD-Z0wQZoahPxZqZcCVCI"
      }
    }
    ```

    On success, the response will include `widgetUrl`. This URL must be used to load the Transak Widget.
  </Step>

  <Step title="Load the Widget">
    Use the returned `widgetUrl` to render the Transak widget in your app.

    <Frame>
      <div>
        <ul>
          <li>
            The <code>widgetUrl</code> is valid for <strong>5 minutes</strong> from creation.
          </li>

          <li>
            Each <code>sessionId</code> can only be used <strong>once</strong>.
          </li>

          <li>
            The widget <strong>cannot be reopened</strong> with the same <code>widgetUrl</code>.
          </li>

          <li>
            A <strong>new <code>sessionId</code></strong> is required for every fresh user flow.
          </li>
        </ul>
      </div>
    </Frame>
  </Step>
</Steps>

## Deprecation Notice

The old method of embedding query parameters directly in the widget URL is no longer supported.

### Deprecated (Old)

```
https://global.transak.com?apiKey=YOUR_API_KEY&productsAvailed=BUY,SELL&fiatAmount=300&fiatCurrency=GBP&network=ethereum&paymentMethod=credit_debit_card&cryptoCurrencyCode=ETH&hideExchangeScreen=true&walletAddress=0xE99B71B9a035102432e30F47843746e646737b79&disableWalletAddressForm=true
```

### New (Required)

```
https://global.transak.com?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID
```

The `sessionId` is returned from the [Create Widget URL](/api/public/create-widget-url) API.

## Additional Required Changes for Web Integrations

The Transak widget relies on the browser's **Referer header** as a runtime signal to verify the source domain. Make sure your integration sends this header correctly.

### Redirect Link

<Frame>
  <div>
    Do **not** use `rel=noreferrer`. It prevents the Referer header from being sent and breaks runtime domain validation.
  </div>
</Frame>

<Tabs>
  <Tab title="HTML">
    ```html
    <a
      href="https://global.transak.com?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID"
      target="_blank"
      rel="noopener"
    >
      Buy/Sell Crypto with Transak
    </a>
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript
    window.open(
      'https://global.transak.com/?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID',
      '_blank',
      'noopener'
    );
    ```
  </Tab>
</Tabs>

### iFrame (Embed / Double Embed)

<Frame>
  <div>
    Do **not** use `referrerpolicy=no-referrer`. It strips the Referer header and prevents domain validation.
  </div>
</Frame>

Nesting the Transak iframe inside a third-party iframe is **not permitted** unless the parent site has received explicit approval from Transak.

Use `referrerpolicy="strict-origin-when-cross-origin"` (recommended) or `"origin"`

```html
<iframe
  src="https://global.transak.com?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID"
  width="100%"
  height="625"
  style="border: none;"
  allow="clipboard-write"
  referrerpolicy="strict-origin-when-cross-origin"
/>
```

## Need Assistance with Migration?

<CardGroup cols={1}>
  <Card title="Need Help?" icon="fa-light fa-circle-question" iconPosition="left" href="/getting-started/help-and-support">
    Contact the team and find resources to help with your integration.
  </Card>
</CardGroup>