Tracking & attribution

Attach 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). Some keys receive dedicated attribution handling; other keys are preserved as custom metadata.

Basic usage

PaySightSDK.createWidget({
  config: {
    productId: YOUR_PRODUCT_ID,
    sessionId: 'YOUR_SESSION_ID',
    environment: 'sandbox',
    amount: 29.99,
    data: {
      affiliateName: 'partner-123',
      campaignName: 'spring-sale',
      clickId: 'click-abc123',
      utm_source: 'email',
      url: 'https://yoursite.com/offer?utm_source=email',
    },
  },
});

Common keys

Key	Purpose
`campaignName`	Campaign name, alias, or your campaign identifier. Paysight resolves or creates the corresponding campaign record.
`affiliateName`	Affiliate/traffic-source name, alias, or your identifier. Paysight resolves or creates the corresponding affiliate record.
`clickId`	Click identifier used for attribution.
`utm_source`, `utm_medium`, `utm_campaign`	Standard UTM attribution values.
`gclid`, `wbraid`, `gbraid`	Google Ads identifiers. The Widget also captures these URL parameters automatically when available.
`subAffiliateId`	Sub-affiliate identifier.
`trackhouseClickId`	Trackhouse click identifier.
`url` and other string keys	Custom metadata. Availability in reports depends on your Paysight configuration.

Do not use campaignId or affiliateId for your own identifiers. These deprecated fields accept only internal, Paysight-assigned IDs. Unknown values can cause the payment request to be rejected. Use campaignName and affiliateName instead.

Playground data shape

The Widget Playground starts with campaign, utm_source, and url rows to demonstrate generic custom metadata. The campaign key is not the dedicated Paysight campaign field. Use campaignName when you want Paysight campaign attribution, and use affiliateName for affiliate or traffic-source attribution.

Updating at runtime

widget.update({
  data: {
    ...existingData,
    campaignName: 'retargeting',
  },
});

UTM capture pattern

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(),
  },
});

data values must be strings (Record<string, string>). Coerce numbers before passing.

Distinction from session IDs

Field	Source	Purpose
`sessionId`	You	Per-checkout identifier in widget config; forwarded as `partnerSession` and limited to 50 characters
`data.*`	You	Attribution / metadata
`paysightSession`	Paysight API	Upsell handoff — not set via `data`

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Basic usage

Common keys

Playground data shape

Updating at runtime

UTM capture pattern

Distinction from session IDs

​Basic usage

​Common keys

​Playground data shape

​Updating at runtime

​UTM capture pattern

​Distinction from session IDs

​Related

Basic usage

Common keys

Playground data shape

Updating at runtime

UTM capture pattern

Distinction from session IDs

Related