For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
DocsAPI Reference
DocsAPI Reference
    • What is Transak
  • Features
    • Auth Reliance
    • KYC Reliance using Sumsub
    • Webhooks
    • WebSockets
  • Products Overview
    • On Ramp
    • Off Ramp
    • NFT Checkout
  • Integration Options
    • API
  • Customization Options
    • Query Parameters
    • Customizing theme using query parameters
  • Guides
    • How To Create a Partner Dashboard Account
    • How to Add Partner Fees and Set Up Partner Payouts
    • How to Test using Sandbox Credentials
    • How to Test ACH Pull Transaction in Sandbox
    • How to Test Apple Pay in Sandbox
    • How to Track Order Status
    • Transak Different KYC Levels
    • How to Submit FCA Requirements
    • How to Use Advanced Query Params
    • How to Create a Widget URL with Parameters and Test Different Scenarios
    • How to Generate Calldata for NFT Checkout
    • How to Add NFT Smart Contract in the Dashboard and Create a contractId
    • Get Price based on User Region
    • How to Create Partner Access Token
    • How to Decrypt the Webhook Payload
    • How to add MCP Server for Transak Documentation
    • Widget with API Customization
    • Integration Update - Mandatory Migration to API based Transak Widget URL
    • Biconomy: Simplified Onboarding Using MEE-Compatible Smart Accounts
    • Partner FAQs
    • Need Help?
Dashboard
LogoLogo
On this page
  • How It Works
  • Deprecation Notice
  • Deprecated (Old)
  • New (Required)
  • Additional Required Changes for Web Integrations
  • Redirect Link
  • iFrame (Embed / Double Embed)
  • Need Assistance with Migration?
Guides

Mandatory Migration to API-Based Widget URL

Migration to the Create Widget URL API to generate the widget URL
||View as Markdown|
Was this page helpful?
Edit this page
Previous

Widget with API Customization

Next

Biconomy MEE — Simplified Onboarding via Smart Accounts

Built with

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 API from your backend to generate a secure widget url using Query 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.

Redirect Link

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

HTML
JavaScript
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.