> For a complete page index, fetch https://docs.transak.com/llms.txt

# Mandatory Migration to API-Based 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

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.

Call the [Create Widget URL](/api/public/create-widget-url) API from your backend to generate a secure widget url using Query parameters

#### Request Headers

<table>
  <tbody>
    <tr>
      <td>
        Your Partner Access Token from Step 1.

        User Authorization Token — only required for integrations using the User Authentication API.
      </td>
    </tr>
  </tbody>
</table>

#### Request Body

<table>
  <tbody>
    <tr>
      <td>
        Object containing all widget configuration.

        Your API key from the [Transak Partner Dashboard](https://dashboard.transak.com/).

        Your domain URL (web) or application package name (mobile).
      </td>
    </tr>
  </tbody>
</table>

```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"
  }
}'
```

#### 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.

Use the returned `widgetUrl` to render the Transak widget in your app.

<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>

## 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

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

```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>
```

```javascript
window.open(
  'https://global.transak.com/?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID',
  '_blank',
  'noopener'
);
```

### iFrame (Embed / Double Embed)

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

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?

Contact the team and find resources to help with your integration.