***

title: Widget with API Customization
slug: guides/widget-with-api-customization
subtitle: Customize the Transak widget flow using APIs and query parameters
---------------------------------------------------------------------------

Transak provides a flexible solution for partners to create a more tailored Transak experience by combining query parameters and APIs to control parts of the user journey within their own application.

Partners can skip screens, prefill key user details, and use the Transak UI only where it is required in the user journey.

## Problem Statement

Widgets are quick to integrate, but they can still create friction when partners want more control over the user journey, branding, and prefilled data.

Here are some of the **key challenges** with a standard hosted widget flow:

<table>
  <tbody>
    <tr>
      <td>
        <div>
          <Icon icon="fa-light fa-arrow-right-arrow-left" size="6" color="#1461db" />

          <strong>
            Extra steps for users
          </strong>
        </div>

        Users may need to repeat selections or details that your app already knows, which adds avoidable friction to the flow.
      </td>
    </tr>

    <tr>
      <td>
        <div>
          <Icon icon="fa-light fa-window-maximize" size="6" color="#1461db" />

          <strong>
            Limited journey control
          </strong>
        </div>

        Partners cannot fully shape the user experience.
      </td>
    </tr>

    <tr>
      <td>
        <div>
          <Icon icon="fa-light fa-user-pen" size="6" color="#1461db" />

          <strong>
            Repeated data entry
          </strong>
        </div>

        Asking users to re-enter wallet, email, or KYC details can slow conversion and create an inconsistent experience.
      </td>
    </tr>

    <tr>
      <td>
        <div>
          <Icon icon="fa-light fa-chart-line-down" size="6" color="#1461db" />

          <strong>
            Higher drop-off risk
          </strong>
        </div>

        Every additional step can increase abandonment, especially when the partner app could have handled part of the journey upfront.
      </td>
    </tr>
  </tbody>
</table>

## Our Solution

Widget with API Customization helps partners streamline the user journey by combining public APIs and query parameters.

<Steps>
  <Step title="Fetch data in your UI">
    Use Transak's Public APIs to fetch [quotes](/api/public/get-price), [supported fiat currencies](/api/public/get-fiat-currencies), and [supported cryptocurrencies](/api/public/get-crypto-currencies) so your app can collect user choices before launching the widget.
  </Step>

  <Step title="Prefill or skip steps">
    Pass parameters such as `fiatCurrency`, `cryptoCurrencyCode`, `walletAddress`, `email`, `userData`, and other supported fields to reduce the number of screens inside the widget.
  </Step>

  <Step title="Create Widget URL with query parameters">
    Generate a single-use `widgetUrl` from the [Create Widget URL API](/api/public/create-widget-url), passing the supported [widget parameters](/customization/query-parameters) inside `widgetParams`.

    **Example Request:**

    ```bash
    curl --request POST \
      --url https://api-gateway-stg.transak.com/api/v2/auth/session \
      --header 'access-token: YOUR_ACCESS_TOKEN' \
      --header 'content-type: application/json' \
      --data '{
      "widgetParams": {
        "apiKey": "YOUR_API_KEY",
        "referrerDomain": "yourdomain.com",
        "fiatCurrency": "ETH", 
        .....
      }
    }'
    ```
  </Step>

  <Step title="Track the order outside the widget">
    Use [Get Order By ID](/api/public/get-order-by-order-id), [Get Orders](/api/public/get-orders), [Webhooks](/features/webhooks), and [WebSockets](/features/websockets) to track the order.
  </Step>
</Steps>

## How does it work?

<div>
  <Frame>
    <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-19T10:59:47.940Z/guides/widget-with-api-customization/d510a2ba2f7a3604291c73816ca90f6337d7778fe286d856213bc0adc2b9ee42-white-label-api.gif" alt="Widget with API customization flow diagram" title="Widget with API customization flow diagram" noZoom={false} />
  </Frame>
</div>

<Table align={["left", "left", "left"]}>
  <thead>
    <tr>
      <th>
        Screen
      </th>

      <th>
        Can be skipped?
      </th>

      <th>
        Demo Link
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Exchange Screen
      </td>

      <td>
        <Badge intent="success" minimal>Yes</Badge>
      </td>

      <td>
        <a href="https://global-stg.transak.com/?apiKey=942ae75f-9eb2-4820-815c-23e2527da11d&fiatCurrency=GBP&cryptoCurrencyCode=ETH&fiatAmount=100&productsAvailed=BUY,SELL&hideExchangeScreen=true&network=ethereum&paymentMethod=credit_debit_card" target="_blank">
          Skip Exchange Flow Demo
        </a>
      </td>
    </tr>

    <tr>
      <td>
        Wallet Confirmation Screen
      </td>

      <td>
        <Badge intent="success" minimal>Yes</Badge>
      </td>

      <td>
        <a href="https://global-stg.transak.com/?apiKey=942ae75f-9eb2-4820-815c-23e2527da11d&walletAddress=0xFfb61856d2aEC494e8c9cFB599b82D466124e280&disableWalletAddressForm=true" target="_blank">
          Skip Wallet Address Flow Demo
        </a>
      </td>
    </tr>

    <tr>
      <td>
        Email Verification Screen
      </td>

      <td>
        <Badge intent="success" minimal>Yes</Badge>
      </td>

      <td>
        <a href="https://global-stg.transak.com/?apiKey=942ae75f-9eb2-4820-815c-23e2527da11d&email=demo@transak.com" target="_blank">
          Skip Email Flow Demo
        </a>
      </td>
    </tr>

    <tr>
      <td>
        OTP Verification Screen
      </td>

      <td>
        <Badge intent="danger" minimal>No</Badge>
      </td>

      <td>
        NA
      </td>
    </tr>

    <tr>
      <td>
        Lite KYC Screen
      </td>

      <td>
        <Badge intent="success" minimal>Yes</Badge>
      </td>

      <td>
        <a href="https://global-stg.transak.com?apiKey=a2374be4-c59a-400e-809b-72c226c74b8f&environment=STAGING&productsAvailed=BUY&fiatAmount=38&fiatCurrency=EUR&network=ethereum&paymentMethod=sepa_bank_transfer&cryptoCurrencyCode=ETH&hideExchangeScreen=true&walletAddress=0xD902d7eBF7bc5eCa9EEA22a6Ee9F1A30EBeBEFeE&disableWalletAddressForm=true&userData=%7B%22firstName%22%3A%22Doe%22%2C%22lastName%22%3A%22Jane%22%2C%22mobileNumber%22%3A%22%2B33791112345%22%2C%22dob%22%3A%221998-01-01%22%2C%22address%22%3A%7B%22addressLine1%22%3A%22170RueduFaubourg%22%2C%22addressLine2%22%3A%22Saint-Denis%2CParis%22%2C%22city%22%3A%22Paris%22%2C%22state%22%3A%22Paris%22%2C%22postCode%22%3A%2275010%22%2C%22countryCode%22%3A%22FR%22%7D%7D" target="_blank">
          Skip Lite KYC Flow Demo
        </a>
      </td>
    </tr>

    <tr>
      <td>
        Standard KYC Screen
      </td>

      <td>
        <Badge intent="danger" minimal>No</Badge>
      </td>

      <td>
        NA
      </td>
    </tr>

    <tr>
      <td>
        Confirm Order Screen
      </td>

      <td>
        <Badge intent="danger" minimal>No</Badge>
      </td>

      <td>
        NA
      </td>
    </tr>

    <tr>
      <td>
        Payment Screen
      </td>

      <td>
        <Badge intent="danger" minimal>No</Badge>
      </td>

      <td>
        NA
      </td>
    </tr>

    <tr>
      <td>
        Payment Authorization Screen
      </td>

      <td>
        <Badge intent="danger" minimal>No</Badge>
      </td>

      <td>
        NA
      </td>
    </tr>

    <tr>
      <td>
        Order Status Screen
      </td>

      <td>
        <Badge intent="success" minimal>Yes</Badge>
      </td>

      <td>
        <a href="https://transak-playground.vercel.app/sandbox/order-status" target="_blank">
          Skip Order Status Flow - API Demo
        </a>
      </td>
    </tr>

    <tr>
      <td>
        Order History Screen
      </td>

      <td>
        <Badge intent="success" minimal>Yes</Badge>
      </td>

      <td>
        <a href="https://transak-playground.vercel.app/" target="_blank">
          Skip Order History Flow - API Demo
        </a>
      </td>
    </tr>
  </tbody>
</Table>

## User Flow

<AccordionGroup>
  <Accordion title="Exchange Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:30:32.523Z/guides/widget-with-api-customization/f458c99-2024-02-08_08-43-39.png" alt="Exchange Screen" title="Exchange Screen" noZoom={false} />
      </Frame>
    </div>

    The Exchange Screen allows users to select the fiat amount, crypto asset, network, and payment method.

    To skip this step, collect those inputs in your own UI and pass them through `widgetParams`.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>Recommended parameters</strong><br /><br />
            `apiKey`, `productsAvailed`, `fiatAmount`, `fiatCurrency`, `cryptoCurrencyCode`, `network`, `paymentMethod`, `hideExchangeScreen`
          </td>
        </tr>

        <tr>
          <td>
            <strong>Useful APIs</strong><br /><br />
            [Get Price](/api/public/get-price), [Get Fiat Currencies](/api/public/get-fiat-currencies), [Get Crypto Currencies](/api/public/get-crypto-currencies)
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Wallet Confirmation Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:31:33.976Z/guides/widget-with-api-customization/9a59eb316d52473a649549a8db96d8781b8f47948ee73337b813b08b46f2b65d-image.png" alt="Wallet Confirmation Screen" title="Wallet Confirmation Screen" noZoom={false} />
      </Frame>
    </div>

    This step confirms the destination wallet for on-ramp transactions.

    To skip this step, pass the wallet details through `widgetParams`.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>Required parameters</strong><br /><br />
            `walletAddress`, `disableWalletAddressForm=true`
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Email Verification Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:32:49.196Z/guides/widget-with-api-customization/73df191-2024-02-08_11-15-47.png" alt="Email Verification Screen" title="Email Verification Screen" noZoom={false} />
      </Frame>
    </div>

    This screen is used to collect the user's email for OTP verification.

    To skip this step, pass the user's email through `widgetParams`.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>Required parameter</strong><br /><br />
            `email`
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="OTP Verification Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:34:14.947Z/guides/widget-with-api-customization/7a003bb-2024-02-08_12-35-47.png" title="OTP Verification Screen" noZoom={false} alt="OTP Verification Screen" />
      </Frame>
    </div>

    OTP verification is a mandatory step and cannot be skipped.

    Prefilling the users email helps streamline the flow, but it does not bypass OTP verification.
  </Accordion>

  <Accordion title="Lite KYC Screen">
    <div>
      <div>
        <Frame>
          <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:38:18.800Z/guides/widget-with-api-customization/a0f68a3-2024-02-08_12-08-59.png" alt="Lite KYC Address Details" title="Lite KYC Address Details" noZoom={false} />
        </Frame>
      </div>

      <div>
        <Frame>
          <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:36:22.109Z/guides/widget-with-api-customization/40c42cb-2024-02-08_12-12-05.png" alt="Lite KYC Personal Details" title="Lite KYC Personal Details" noZoom={false} />
        </Frame>
      </div>
    </div>

    The Lite KYC Screen captures the user's personal and address details.

    To skip this step, pass structured `userData` through `widgetParams`.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>Required parameter</strong><br /><br />
            `userData`
          </td>
        </tr>
      </tbody>
    </table>

    **Example**

    ```json
    {
      "firstName": "Satoshi",
      "lastName": "Nakamoto",
      "email": "satoshi.nakamoto@transak.com",
      "mobileNumber": "+15417543010",
      "dob": "1994-08-26",
      "address": {
        "addressLine1": "170 Pine St",
        "addressLine2": "San Francisco",
        "city": "San Francisco",
        "state": "CA",
        "postCode": "94111",
        "countryCode": "US"
      }
    }
    ```
  </Accordion>

  <Accordion title="Standard KYC Screen">
    <div>
      <div>
        <Frame>
          <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:39:26.817Z/guides/widget-with-api-customization/5ea7346-ID_Proof_and_Selfie.png" alt="Standard KYC document upload" title="Standard KYC document upload" noZoom={false} />
        </Frame>
      </div>

      <div>
        <Frame>
          <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:40:55.395Z/guides/widget-with-api-customization/1e8ea91-ID_Selfie.png" title="Standard KYC document upload" noZoom={false} alt="Standard KYC document upload" />
        </Frame>
      </div>
    </div>

    Standard KYC includes document upload and liveness checks.

    This step is not skippable in the widget and triggered only when the order value exceeds Lite KYC limits.
  </Accordion>

  <Accordion title="Confirm Order Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:41:42.094Z/guides/widget-with-api-customization/557e017-2024-02-08_18-42-11.png" alt="Confirm Order Screen" title="Confirm Order Screen" noZoom={false} />
      </Frame>
    </div>

    The Confirm Order step displays the final transaction summary before payment.

    This step is not skippable in the widget and shown to users before they proceed with the payment.
  </Accordion>

  <Accordion title="Payment Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:42:30.198Z/guides/widget-with-api-customization/51dd941-f74e2cd-2024-02-08_13-43-17.png" alt="Payment Screen" title="Payment Screen" noZoom={false} />
      </Frame>
    </div>

    This is where users enter or confirm payment details.

    This step is not skippable in the widget.
  </Accordion>

  <Accordion title="Payment Authorization Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:43:54.587Z/guides/widget-with-api-customization/f971b73-2024-02-08_18-47-55.png" alt="Payment Authorization Screen" title="Payment Authorization Screen" noZoom={false} />
      </Frame>
    </div>

    To skip this step, continue the user journey in your own application by listening for the `TRANSAK_ORDER_SUCCESSFUL` event after payment is initiated.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>How it works</strong><br /><br />
            Once the event is received, you can close the widget or move users to the next step in your own flow instead of keeping them on the completion screen.
          </td>
        </tr>

        <tr>
          <td>
            <strong>Supported integrations</strong><br /><br />
            [JavaScript SDK](/integration/web/js-sdk), [Android](/integration/mobile/native-android), [iOS](/integration/mobile/native-ios), [React Native](/integration/mobile/react-native)
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Order Status Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:48:49.063Z/guides/widget-with-api-customization/c4ba051-2024-02-08_18-45-51.png" alt="Order Status Screen" title="Order Status Screen" noZoom={false} />
      </Frame>
    </div>

    To skip this step, display order status updates in your own application instead of relying on the order status screen.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>Supported options</strong><br /><br />
            [Get Order By ID](/api/public/get-order-by-order-id), [Webhooks](/features/webhooks), [WebSockets](/features/websockets)
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Order History Screen">
    <div>
      <Frame>
        <img src="https://files.buildwithfern.com/visual-editor-images/transak-labs.docs.buildwithfern.com/2026-03-23T05:51:27.094Z/guides/widget-with-api-customization/65eadaf-Order_History.png" alt="Order History Screen" title="Order History Screen" noZoom={false} />
      </Frame>
    </div>

    To skip this step, display transaction history in your own application instead of relying on the order history screen.

    <table>
      <tbody>
        <tr>
          <td>
            <strong>Supported option</strong><br /><br />
            [Get Orders](/api/public/get-orders)
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>