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

# Tracking & attribution

> Pass affiliate and campaign data via config.data

Attach arbitrary string key-value pairs to payment requests with the `data` object on `WidgetConfig`. Values are forwarded to the Paysight API with each payment attempt (card, wallet, upsell).

## Basic usage

```javascript theme={null}
PaySightSDK.createWidget({
  config: {
    productId: YOUR_PRODUCT_ID,
    sessionId: 'YOUR_SESSION_ID',
    environment: 'sandbox',
    amount: 29.99,
    data: {
      affiliateId: 'partner-123',
      campaign: 'spring-sale',
      source: 'landing-page-a',
      url: 'https://yoursite.com/offer?utm_source=email',
    },
  },
});
```

## Common keys

| Key                                        | Purpose                                             |
| ------------------------------------------ | --------------------------------------------------- |
| `url`                                      | Landing or checkout page URL (used for attribution) |
| `affiliateId` / `partnerId`                | Partner or affiliate identifier                     |
| `utm_source`, `utm_medium`, `utm_campaign` | Standard UTM parameters                             |
| `clickId`, `subId`                         | Click or sub-affiliate tracking                     |

There is no fixed schema — use keys your Paysight product or reporting expects.

## Updating at runtime

```javascript theme={null}
widget.update({
  data: {
    ...existingData,
    campaign: 'retargeting',
  },
});
```

## UTM capture pattern

```javascript theme={null}
function getUtmParams() {
  const params = new URLSearchParams(window.location.search);
  return {
    utm_source: params.get('utm_source') ?? '',
    utm_medium: params.get('utm_medium') ?? '',
    utm_campaign: params.get('utm_campaign') ?? '',
    url: window.location.href,
  };
}

const widget = PaySightSDK.createWidget({
  config: {
    // ...
    data: getUtmParams(),
  },
});
```

<Callout type="info">
  `data` values must be strings (`Record<string, string>`). Coerce numbers before passing.
</Callout>

## Distinction from session IDs

| Field             | Source       | Purpose                                   |
| ----------------- | ------------ | ----------------------------------------- |
| `sessionId`       | You          | Per-checkout idempotency in widget config |
| `data.*`          | You          | Attribution / metadata                    |
| `paysightSession` | Paysight API | Upsell handoff — not set via `data`       |

## Related

* [Configuration reference](/widget-sdk/reference/configuration)
* [Core concepts](/widget-sdk/core-concepts)