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

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

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

```json
{
  "data": {
    "accessToken": "YOUR_ACCESS_TOKEN",
    "expiresAt": 1770977934
  }
}
```

## Step 2: Create the widget URL

Call the Create Widget URL API from your backend.

```bash
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": "GBP",
    "cryptoCurrencyCode": "ETH",
    "network": "ethereum",
    "paymentMethod": "credit_debit_card"
  }
}'
```

Sample response:

```json
{
  "data": {
    "widgetUrl": "https://global-stg.transak.com?apiKey=YOUR_API_KEY&sessionId=YOUR_SESSION_ID"
  }
}
```

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

```json
{
  "widgetParams": {
    "apiKey": "YOUR_API_KEY",
    "referrerDomain": "yourdomain.com",
    "productsAvailed": "BUY",
    "fiatAmount": 100,
    "fiatCurrency": "GBP",
    "cryptoCurrencyCode": "ETH",
    "network": "ethereum"
  }
}
```

## Test scenario 2: Skip the exchange screen

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

```json
{
  "widgetParams": {
    "apiKey": "YOUR_API_KEY",
    "referrerDomain": "yourdomain.com",
    "productsAvailed": "BUY",
    "fiatAmount": 100,
    "fiatCurrency": "GBP",
    "cryptoCurrencyCode": "ETH",
    "network": "ethereum",
    "paymentMethod": "credit_debit_card",
    "hideExchangeScreen": true
  }
}
```

## Test scenario 3: Skip wallet confirmation

```json
{
  "widgetParams": {
    "apiKey": "YOUR_API_KEY",
    "referrerDomain": "yourdomain.com",
    "walletAddress": "0xFfb61856d2aEC494e8c9cFB599b82D466124e280",
    "disableWalletAddressForm": true
  }
}
```

## Test scenario 4: Pre-fill email and lite KYC

```json
{
  "widgetParams": {
    "apiKey": "YOUR_API_KEY",
    "referrerDomain": "yourdomain.com",
    "email": "doe.jane@example.com",
    "userData": {
      "firstName": "Doe",
      "lastName": "Jane",
      "mobileNumber": "+12125550142",
      "dob": "1998-01-01",
      "address": {
        "addressLine1": "179 Richmond Oak",
        "addressLine2": "",
        "city": "California",
        "state": "CA",
        "postCode": "94016",
        "countryCode": "US"
      }
    }
  }
}
```

## Sandbox credentials for staging

Use the staging data below to test KYC flows.

### US test account

| Field          | Value              |
| -------------- | ------------------ |
| First Name     | `Doe`              |
| Last Name      | `Jane`             |
| Mobile Number  | `+1 2125550142`    |
| Date of Birth  | `01-01-1998`       |
| Address Line   | `179 Richmond Oak` |
| State / Region | `CA`               |
| City           | `California`       |
| Postal Code    | `94016`            |

Additional staging identifiers:

* **US SSN:** `123456789`

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

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

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