# Overview



## Overview

The Paytrie widget provides a seamless way for your users to purchase stablecoins (USDC, CADC) directly within your application. By embedding the widget with pre-filled URL parameters, you can streamline the user experience by pre-populating information like transaction amounts, user details, and wallet addresses.

This approach is ideal for:

* **Marketplace integrations** - Allow users to purchase stablecoins as part of your checkout flow
* **Wallet applications** - Enable users to buy crypto without leaving your app
* **Partner platforms** - Provide white-label crypto purchasing for your users

URL parameters enable you to customize the widget experience, reducing friction and improving conversion rates by minimizing the data users need to enter manually.

## Available Parameters

### Transaction Parameters

Configure the transaction amounts and currency labels.

| Parameter        | Description                                     | Example                       |
| ---------------- | ----------------------------------------------- | ----------------------------- |
| `leftSideValue`  | Amount to pay (in the source currency)          | `1000`                        |
| `rightSideValue` | Amount to receive (in the destination currency) | `700`                         |
| `leftSideLabel`  | Source currency or asset label                  | `CAD`, `USDC-ETH`, `CADC-SOL` |
| `rightSideLabel` | Destination currency or asset label             | `CAD`, `USDC-ETH`, `CADC-SOL` |

### User Information

Pre-fill user personal information to expedite the onboarding process.

| Parameter   | Description          | Example            |
| ----------- | -------------------- | ------------------ |
| `email`     | User's email address | `user@example.com` |
| `phone`     | User's phone number  | `4161234567`       |
| `firstName` | User's first name    | `John`             |
| `lastName`  | User's last name     | `Doe`              |

### Address Information

Pre-populate address fields for user verification.

| Parameter  | Description                                    | Example       |
| ---------- | ---------------------------------------------- | ------------- |
| `address1` | Street address line 1                          | `123 Main St` |
| `address2` | Street address line 2 (apartment, suite, etc.) | `Apt 4B`      |
| `city`     | City                                           | `Toronto`     |
| `province` | Province or state                              | `ON`          |
| `postal`   | Postal or ZIP code                             | `M5H 2N2`     |

### Other Parameters

Additional configuration options for advanced use cases.

| Parameter           | Description                                                                                                       | Example                  |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `vendorId`          | Your vendor identifier (6-digit app ID)                                                                           | `123456`                 |
| `ref`               | Referral code                                                                                                     | `1ABd7AF`                |
| `dob1`              | Date of birth - year                                                                                              | `1990`                   |
| `dob2`              | Date of birth - month                                                                                             | `05`                     |
| `dob3`              | Date of birth - day                                                                                               | `15`                     |
| `addr`              | Cryptocurrency wallet address                                                                                     | `0x1234...7890`          |
| `externalSessionId` | Custom session ID included in [transaction webhook](/docs/webhooks#transaction-webhooks) payloads (max 255 chars) | `partner-session-abc123` |

### Widget Configuration

Control widget behavior and appearance.

| Parameter        | Description                                                                                     | Example |
| ---------------- | ----------------------------------------------------------------------------------------------- | ------- |
| `lang`           | Widget language (`en` for English, `fr` for French)                                             | `en`    |
| `lockedFlow`     | Lock the buy/sell flow direction (prevents user from switching)                                 | `true`  |
| `lockNetwork`    | Lock the blockchain network selection                                                           | `true`  |
| `inputsDisabled` | Disable amount and currency input fields                                                        | `true`  |
| `autoConnect`    | Auto-connect wallet for MiniPay integration (also sets `lockNetwork=true` and forces Celo/USDC) | `true`  |

## Integration Examples

<Tabs items={['HTML', 'React', 'Next.js', 'Vue']}>
  <Tab value="HTML">
    ```html
    <!DOCTYPE html>
    <html>
    <head>
      <title>Paytrie Widget</title>
    </head>
    <body>
      <iframe
        src="https://app.paytrie.com?vendorId=123456&email=user@example.com"
        sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
        style="width: 100%; height: 700px; border: none;"
      ></iframe>
    </body>
    </html>
    ```
  </Tab>

  <Tab value="React">
    ```tsx
    import { useMemo } from 'react'

    interface PaytrieWidgetProps {
      vendorId: string
      email?: string
      amount?: number
    }

    export function PaytrieWidget({ vendorId, email, amount }: PaytrieWidgetProps) {
      const widgetUrl = useMemo(() => {
        const params = new URLSearchParams({
          vendorId,
          ...(email && { email }),
          ...(amount && { leftSideValue: amount.toString() }),
        })
        return `https://app.paytrie.com?${params.toString()}`
      }, [vendorId, email, amount])

      return (
        <iframe
          src={widgetUrl}
          sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
          className="w-full h-[700px] border-0"
          title="Paytrie Widget"
        />
      )
    }
    ```
  </Tab>

  <Tab value="Next.js">
    ```tsx
    'use client'

    import { useMemo } from 'react'

    interface WidgetParams {
      vendorId: string
      email?: string
      firstName?: string
      lastName?: string
      leftSideValue?: string
    }

    export function PaytrieWidget({ params }: { params: WidgetParams }) {
      const widgetUrl = useMemo(() => {
        const searchParams = new URLSearchParams()

        Object.entries(params).forEach(([key, value]) => {
          if (value) {
            searchParams.append(key, value)
          }
        })

        return `https://app.paytrie.com?${searchParams.toString()}`
      }, [params])

      return (
        <div className="w-full">
          <iframe
            src={widgetUrl}
            sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
            className="w-full h-[700px] border-0 rounded-lg"
            title="Paytrie Widget"
          />
        </div>
      )
    }
    ```
  </Tab>

  <Tab value="Vue">
    ```vue
    <template>
      <iframe
        :src="widgetUrl"
        sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
        class="w-full h-[700px] border-0"
        title="Paytrie Widget"
      />
    </template>

    <script setup>
    import { computed } from 'vue'

    const props = defineProps({
      vendorId: {
        type: String,
        required: true
      },
      email: String,
      amount: Number
    })

    const widgetUrl = computed(() => {
      const params = new URLSearchParams({
        vendorId: props.vendorId,
      })

      if (props.email) params.append('email', props.email)
      if (props.amount) params.append('leftSideValue', props.amount.toString())

      return `https://app.paytrie.com?${params.toString()}`
    })
    </script>
    ```
  </Tab>
</Tabs>

## Content Security Policy

If your application uses CSP headers, add `frame-src https://app.paytrie.com` to allow the widget iframe.

## Best Practices

<Steps>
  <Step>
    ### Start with minimal parameters

    Begin by passing only essential parameters like `vendorId` and `email`. Add more parameters as needed based on your use case.
  </Step>

  <Step>
    ### Handle iframe errors

    Implement error handling for iframe loading failures. Provide users with alternative options if the widget fails to load.

    ```typescript
    <iframe
      src={widgetUrl}
      onError={() => {
        console.error('Widget failed to load')
        // Show fallback UI
      }}
    />
    ```
  </Step>

  <Step>
    ### Use the URL Builder

    Use the [URL Builder](/docs/url-builder) to test your configurations before deploying.
  </Step>
</Steps>