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

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
}

Step 2: Create the widget URL

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

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

Additional staging identifiers:

• US SSN: 123456789
• India PAN: ABCDE1234A

Payment test data

Test cards

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.