Guides

Mandatory Migration to API-Based Widget URL

Migration to the Create Widget URL API to generate the widget URL
View as Markdown

All partners are required to migrate their integration to use the Create Widget URL API, which generates a secure widgetUrl to load the Transak widget. This approach ensures secure, validated, and consistent integrations across all integration options.

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

How It Works

1

Generate a Partner Access Token (Backend Only)

Call the 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.

2

Create a Widget URL (using Backend Only)

Call the Create Widget URL to generate a Widget URL by securely passing the widget parameters.

Request Headers

access-token
stringRequired

Your Partner Access Token from Step 1.

authorization
string

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

Request Body

widgetParams
objectRequired

Object containing all widget configuration.

widgetParams.apiKey
stringRequired

Your API key from the Transak Partner Dashboard.

widgetParams.referrerDomain
stringRequired

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

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

Response

1{
2  "data": {
3    "widgetUrl": "https://global-stg.transak.com?apiKey=YOUR_API_KEY&sessionId=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvdHQiOiI2YzgxMDFiMjlhMzg0YWE2YmRjM2JjMmFkODA1M2YzMyIsImlhdCI6MTc1NzMyNTkwNywiZXhwIjoxNzU3MzI2MjA3fQ.zooQ07sGOnI_2dwtIzYL5sOD-Z0wQZoahPxZqZcCVCI"
4  }
5}

On success, the response will include widgetUrl. This URL must be used to load the Transak Widget.

3

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.

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.

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

1<a
2  href="https://global.transak.com?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID"
3  target="_blank"
4  rel="noopener"
5>
6  Buy/Sell Crypto with Transak
7</a>

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"

1<iframe
2  src="https://global.transak.com?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID"
3  width="100%"
4  height="625"
5  style="border: none;"
6  allow="clipboard-write"
7  referrerpolicy="strict-origin-when-cross-origin"
8/>

Need Assistance with Migration?

Need Help?

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