> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dollarpe.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget integration

> Embed the DollarPe widget via a hosted link or an iframe using the Widget Initialize API.

The DollarPe widget covers the full customer journey: onboarding, KYC, bank linking, payin, and payout. Your logo, colors, and email branding apply automatically.

<img src="https://mintcdn.com/dollarpe/w_zVBmfWYNlVbKBv/static/widget.png?fit=max&auto=format&n=w_zVBmfWYNlVbKBv&q=85&s=dd7658cc9a2ed998f2fe2699ad3b7944" alt="Widget UI with partner logo, primary accent on actions, and branded chrome." className="dp-ncode-capture--widget" loading="lazy" width="956" height="1552" data-path="static/widget.png" />

## Pick an integration path

<CardGroup cols={2}>
  <Card title="Hosted mode" icon="link" href="#hosted-mode">
    Send users to a URL. No backend code required.
  </Card>

  <Card title="iframe (Initialize API)" icon="code" href="#iframe-integration-initialize-api">
    Call Widget Initialize from your server, embed the returned URL in an iframe.
  </Card>
</CardGroup>

|             | Hosted mode                                     | iframe (Initialize API)                                                                         |
| ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| What you do | Send users to a URL (link, button, or redirect) | Call Widget Initialize on your server, load the returned URL in an `iframe`                     |
| Best when   | You want zero backend logic                     | You need to pre-fill buy/sell context, amounts, or wallet                                       |
| URL         | You build `https://app.dollarpe.xyz?...`        | `data.widget_link` from [Widget Initialize](/api-reference-exchange/endpoint/widget/initialize) |
| API secret  | Not needed                                      | Keep on the server; pass only `widget_link` to the browser                                      |

For operators using the full browser portal, see [No code options](/guides/integration-guides/no-code-option).

## Hosted mode

Open the widget with your `app_id`:

```
https://app.dollarpe.xyz?app_id={org_app_id}
```

Replace `{org_app_id}` with the value from onboarding. Works on desktop and mobile. You can open it in a new tab, a webview, or an `iframe`.

### Pre-filling parameters

To pre-fill buy or sell parameters before the user lands on the widget, use the [Widget Initialize](/api-reference-exchange/endpoint/widget/initialize) API. Supported parameters are listed in the API reference.

## iframe integration (Initialize API)

Use this when each session needs server-side context: buy or sell flow, amounts, asset, network. Your API secret never goes in frontend code.

<Steps>
  <Step title="Call Widget Initialize from your backend">
    Send an authenticated request to [Widget Initialize](/api-reference-exchange/endpoint/widget/initialize) with a buy or sell body. The response includes `data.widget_link`, a URL ready to load in an iframe.
  </Step>

  <Step title="Return the link to your frontend">
    Pass only `widget_link` to the client. Keep signing and auth on the server. See [Authentication](/guides/development-and-testing/authentication) for request headers.
  </Step>

  <Step title="Load the widget in an iframe">
    Set `src` on your `iframe` to `widget_link`. The widget loads with your branding and runs the flow end to end.
  </Step>
</Steps>

### iframe example

```html theme={null}
<iframe
  src="{widget_link}"
  width="100%"
  height="700"
  style="border: none; border-radius: 12px;"
  allow="camera; microphone"
  title="DollarPe widget"
></iframe>
```

<Note>
  Use `allow="camera; microphone"` when KYC includes selfie or document capture inside the widget.
</Note>

## Branding

Branding is set for your organization during onboarding. To update your logo, colors, or email styling after launch, contact [support@dollarpe.xyz](mailto:support@dollarpe.xyz).

| Item            | What it affects                                 |
| --------------- | ----------------------------------------------- |
| Logo            | Header and key surfaces in the widget           |
| Primary color   | Buttons and primary actions                     |
| Secondary color | Secondary UI and backgrounds                    |
| Email templates | Onboarding & Transactional emails to your users |

Branding is tied to your `app_id`. Both hosted mode and iframe sessions show the same white label settings.