How to Create a Widget URL with Parameters and Test Different Scenarios

Generate a widget URL through the API and use sandbox credentials to validate common flows

This guide shows how to create a widget URL using widgetParams, then test different user journeys in the staging environment.

Important change

Passing query parameters directly in the hosted widget URL is deprecated.

Use the Create Widget URL API from your backend to generate a widgetUrl and load that session in your app.

Before you start

Your API key
Your API secret
A backend service where you can safely generate the access token and widget session
Access to the staging environment for testing

Step 1: Create a Partner Access Token

Generate a partner access token first.

$ curl --request POST \
>   --url https://api-stg.transak.com/partners/api/v2/refresh-token \
>   --header 'accept: application/json' \
>   --header 'api-secret: YOUR_API_SECRET' \
>   --header 'content-type: application/json' \
>   --data '{"apiKey":"YOUR_API_KEY"}'

You will receive:

1 {
2   "data": {
3     "accessToken": "YOUR_ACCESS_TOKEN",
4     "expiresAt": 1770977934
5   }
6 }

Call the Create Widget URL API from your backend.

$ 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 'content-type: application/json' \
>      --data '{
>   "widgetParams": {
>     "apiKey": "YOUR_API_KEY",
>     "referrerDomain": "yourdomain.com",
>     "productsAvailed": "BUY",
>     "fiatAmount": 100,
>     "fiatCurrency": "EUR",
>     "cryptoCurrencyCode": "ETH",
>     "network": "ethereum",
>     "paymentMethod": "credit_debit_card"
>   }
> }'

Sample response:

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

Session rules

Keep these constraints in mind:

The widgetUrl is valid for 5 minutes
A sessionId can be used only once
Reopening the same widget URL is not supported
Generate a fresh session for every new flow

Common parameters to use in `widgetParams`

Parameter	Purpose
`apiKey`	Your Transak API key
`referrerDomain`	Your approved website domain or app package
`productsAvailed`	`BUY`, `SELL`, or `BUY,SELL`
`fiatAmount`	Lock the fiat amount
`fiatCurrency`	Lock the fiat currency
`cryptoCurrencyCode`	Lock the crypto asset
`network`	Lock the blockchain network
`paymentMethod`	Lock the payment method
`hideExchangeScreen`	Skip the exchange screen when all required values are present
`walletAddress`	Pre-fill destination wallet
`disableWalletAddressForm`	Prevent editing of the wallet
`email`	Pre-fill email
`userData`	Pre-fill lite KYC details
`partnerOrderId`	Your internal order reference
`partnerCustomerId`	Your internal customer reference

Test scenario 1: Basic buy flow

Use this to validate the default path with minimal configuration.

1 {
2   "widgetParams": {
3     "apiKey": "YOUR_API_KEY",
4     "referrerDomain": "yourdomain.com",
5     "productsAvailed": "BUY",
6     "fiatAmount": 100,
7     "fiatCurrency": "EUR",
8     "cryptoCurrencyCode": "ETH",
9     "network": "ethereum"
10   }
11 }

Test scenario 2: Skip the exchange screen

If your own app already collects the trade inputs, you can skip the exchange screen.

1 {
2   "widgetParams": {
3     "apiKey": "YOUR_API_KEY",
4     "referrerDomain": "yourdomain.com",
5     "productsAvailed": "BUY",
6     "fiatAmount": 100,
7     "fiatCurrency": "GBP",
8     "cryptoCurrencyCode": "ETH",
9     "network": "ethereum",
10     "paymentMethod": "credit_debit_card",
11     "hideExchangeScreen": true
12   }
13 }

Test scenario 3: Skip wallet confirmation

1 {
2   "widgetParams": {
3     "apiKey": "YOUR_API_KEY",
4     "referrerDomain": "yourdomain.com",
5     "walletAddress": "0xFfb61856d2aEC494e8c9cFB599b82D466124e280",
6     "disableWalletAddressForm": true
7   }
8 }

Test scenario 4: Pre-fill email and lite KYC

1 {
2   "widgetParams": {
3     "apiKey": "YOUR_API_KEY",
4     "referrerDomain": "yourdomain.com",
5     "email": "doe.jane@example.com",
6     "userData": {
7       "firstName": "Doe",
8       "lastName": "Jane",
9       "mobileNumber": "+33791112345",
10       "dob": "1998-01-01",
11       "address": {
12         "addressLine1": "170 Rue du Faubourg Saint-Denis",
13         "addressLine2": "Paris",
14         "city": "Paris",
15         "state": "Paris",
16         "postCode": "75010",
17         "countryCode": "FR"
18       }
19     }
20   }
21 }

Sandbox credentials for staging

Use the staging data below to test KYC flows.

Europe test account

Field	Value
First Name	`Doe`
Last Name	`Jane`
Mobile Number	`+33 791112345`
Date of Birth	`01-01-1998`
Address Line	`170 Rue du Faubourg Saint-Denis, Paris`
State / Region	`Paris`
City	`Paris`
Postal Code	`75010`

Additional staging identifiers:

US SSN: 123456789
India PAN: ABCDE1234A

Payment test data

Test cards

Card Type	Card Number	Expiry	CVV	Fiat currencies
VISA	`4024764449971519`	`10/33`	`123`	USD, IDR
VISA	`4242424242424242`	`10/33`	`100`	GBP, EUR, AUD, CAD, CHF, NOK, JPY, KRW, ZAR, NZD, SGD, HKD

3DS password

Use Checkout1! on the staging payment authorization screen.

Bank transfer and payout testing

Test UTR: 345678909872 for INR
Use 000000 when a bank or phone verification code is requested

Test failure scenarios with email aliases

You can simulate different outcomes by changing the email address used in staging.

Scenario	Example email
Normal flow	`xyz@abc.com`
Refunded order	`xyz+review@abc.com`
Failed order	`xyz+failed@abc.com`

How to Create a Widget URL with Parameters and Test Different Scenarios

How to Create a Widget URL with Parameters and Test Different Scenarios

Important change

Before you start

Step 1: Create a Partner Access Token

Step 2: Create the widget URL

Session rules

Common parameters to use in `widgetParams`

Test scenario 1: Basic buy flow

Test scenario 2: Skip the exchange screen

Test scenario 3: Skip wallet confirmation

Test scenario 4: Pre-fill email and lite KYC

Sandbox credentials for staging

Europe test account

Payment test data

Test cards

3DS password

Bank transfer and payout testing

Test failure scenarios with email aliases

Important change

Before you start

Step 1: Create a Partner Access Token

Step 2: Create the widget URL

Session rules

Common parameters to use in `widgetParams`

Test scenario 1: Basic buy flow

Test scenario 2: Skip the exchange screen

Test scenario 3: Skip wallet confirmation

Test scenario 4: Pre-fill email and lite KYC

Sandbox credentials for staging

Europe test account

Payment test data

Test cards

3DS password

Bank transfer and payout testing

Test failure scenarios with email aliases

$	curl --request POST \
>	--url https://api-stg.transak.com/partners/api/v2/refresh-token \
>	--header 'accept: application/json' \
>	--header 'api-secret: YOUR_API_SECRET' \
>	--header 'content-type: application/json' \
>	--data '{"apiKey":"YOUR_API_KEY"}'

1	{
2	"data": {
3	"accessToken": "YOUR_ACCESS_TOKEN",
4	"expiresAt": 1770977934
5	}
6	}

$	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 'content-type: application/json' \
>	--data '{
>	"widgetParams": {
>	"apiKey": "YOUR_API_KEY",
>	"referrerDomain": "yourdomain.com",
>	"productsAvailed": "BUY",
>	"fiatAmount": 100,
>	"fiatCurrency": "EUR",
>	"cryptoCurrencyCode": "ETH",
>	"network": "ethereum",
>	"paymentMethod": "credit_debit_card"
>	}
>	}'

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

Important change

Before you start

Step 1: Create a Partner Access Token

Step 2: Create the widget URL

Session rules

Common parameters to use in widgetParams

Test scenario 1: Basic buy flow

Test scenario 2: Skip the exchange screen

Test scenario 3: Skip wallet confirmation

Test scenario 4: Pre-fill email and lite KYC

Sandbox credentials for staging

Europe test account

Payment test data

Test cards

3DS password

Bank transfer and payout testing

Test failure scenarios with email aliases

Important change

Before you start

Step 1: Create a Partner Access Token

Step 2: Create the widget URL

Session rules

Common parameters to use in widgetParams

Test scenario 1: Basic buy flow

Test scenario 2: Skip the exchange screen

Test scenario 3: Skip wallet confirmation

Test scenario 4: Pre-fill email and lite KYC

Sandbox credentials for staging

Europe test account

Payment test data

Test cards

3DS password

Bank transfer and payout testing

Test failure scenarios with email aliases

Common parameters to use in `widgetParams`

Common parameters to use in `widgetParams`