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 sent as payment props; forwarding does not guarantee persistence or availability in transaction APIs.

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 can resolve or create the corresponding campaign record while the shared product/session has no campaign attribution yet (subject to tenant limits).
`affiliateName`	Affiliate/traffic-source name, alias, or your identifier. Paysight can resolve or create the corresponding affiliate record while the shared product/session has no affiliate attribution yet (subject to tenant limits).
`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.

Attribution across upsells

The same Paysight product and initial payment session are reused across the journey. Once campaign/affiliate attribution is established, changing data.campaignName or data.affiliateName on later widget instances does not reliably override it. The transaction table returns resolved campaign and affiliate values. These names are not reliable per-offer product labels. upsellId, sub-affiliate identifiers, click identifiers, UTM values, and arbitrary custom data keys are not exposed as dedicated fields by the current transaction list/detail APIs. Generic custom keys are not guaranteed to be stored per transaction. Keep your own offer-to-payment records if you need item-level identification. See Saved payment & upsell.

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

Attribution across upsells

Updating at runtime

UTM capture pattern

Distinction from session IDs

​Basic usage

​Common keys

​Playground data shape

​Attribution across upsells

​Updating at runtime

​UTM capture pattern

​Distinction from session IDs

​Related

Basic usage

Common keys

Playground data shape

Attribution across upsells

Updating at runtime

UTM capture pattern

Distinction from session IDs

Related