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

# How to create API based Transak 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

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

#### Create a Widget URL (using Backend Only)

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>
        **`access-token`** `string` — required

        Your Partner Access Token from Step 1.

        ---

        **`authorization`** `string`

        User Authorization Token — only required for integrations using the User Authentication API.

        ---
      </td>
    </tr>
  </tbody>
</table>

#### Request Body

<table>
  <tbody>
    <tr>
      <td>
        **`widgetParams`** `object` — required

        Object containing all widget configuration.

        ---

        **`widgetParams.apiKey`** `string` — required

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

        ---

        **`widgetParams.referrerDomain`** `string` — required

        Your domain URL (web) or application package name (mobile).

        ---
      </td>
    </tr>
  </tbody>
</table>

**`Staging`**

```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": "GBP",
    "cryptoCurrencyCode": "ETH"
  }
}'
```

**`Production`**

```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": "GBP",
    "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.

#### Load the Widget

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

* The `widgetUrl` is valid for **5 minutes** from creation.
* Each `sessionId` can only be used **once**.
* The widget **cannot be reopened** with the same `widgetUrl`.
* A **new `sessionId`** is required for every fresh user flow.

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

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

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

#### [Need Help?](/getting-started/help-and-support)

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