Traaaction

Integration

Step-by-step guide to connect your Stripe account with Traaaction and start tracking affiliate sales.

Overview: 3 steps to integrate

Integrating Traaaction with your startup requires three steps:

1Configure your Stripe webhook to send events to Traaaction
2Add tracking metadata to your Stripe Checkout sessions
3Optionally install the trac.js SDK for automatic Click ID injection

The webhook handles all commission creation, subscription tracking, and refund processing automatically.

Webhook configuration

In your Stripe dashboard, create a webhook endpoint pointing to the URL provided by Traaaction. Select these 4 required events:

Event	Purpose
checkout.session.completed	Creates SALE or RECURRING month 1 commission
invoice.paid	Creates RECURRING month 2+ commissions on renewals
charge.refunded	Triggers clawback (commission deletion + negative balance if needed)
customer.subscription.deleted	Deletes all PENDING commissions for the cancelled subscription

Each webhook is verified via Stripe HMAC signature (per-workspace signing secret). Store your signing secret in the Traaaction dashboard.

Stripe metadata

When creating a Stripe Checkout session, include the Click ID in your metadata so Traaaction can attribute the sale to the correct seller:

Payment mode (one-time)

Set client_reference_id and metadata.tracClickId to the Click ID. Optionally add tracCustomerExternalId for customer identification.

Subscription mode

Same metadata as payment mode. The subscription is automatically tracked — renewals via invoice.paid use the Customer record.

// Stripe Checkout — payment mode

const session = await stripe.checkout.sessions.create({

mode: 'payment',

client_reference_id: clickId,

metadata: {

tracClickId: clickId,

tracCustomerExternalId: userId,

});

Priority: tracClickId (metadata) → client_reference_id → Customer lookup. If using trac.js, the Click ID is injected automatically.

trac.js SDK (optional)

Install the trac.js script on your website to automate Click ID detection and Stripe injection:

<script

src="https://traaaction.com/trac.js"

defer

></script>

Detects Click ID from URL parameters, cookies, or localStorage
Automatically injects Click ID into Stripe Payment Links, Buy Buttons, Pricing Tables
Dual storage (cookie + localStorage) for resilience against cookie blockers
SPA-compatible: monitors History API for URL changes in single-page apps

With trac.js installed, no manual metadata configuration is needed — the script handles everything automatically.

Lead tracking API

For LEAD-type missions (sign-ups, form submissions), use the Lead API to create commissions without a Stripe payment:

// POST /api/track/lead

fetch('https://traaaction.com/api/track/lead', {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'x-workspace-id': 'your-workspace-id',

body: JSON.stringify({

eventName: 'signup',

customerExternalId: userId,

clickId: tracClickId,

customerEmail: email,

})

});

Field	Required	Description
eventName	Yes	Name of the event (e.g., 'signup', 'trial_start')
customerExternalId	Yes	Unique user ID in your system
clickId	No	Click ID for attribution (auto-detected if using trac.js)
customerEmail	No	Customer email for identification
metadata	No	Additional JSON data attached to the lead event

Testing & debugging

Use Stripe test mode to verify webhook delivery before going live
Check the Stripe dashboard (Developers → Webhooks) to see event delivery logs
Verify attribution in your Traaaction dashboard — each commission shows the attributed seller
Test the full flow: click affiliate link → make purchase → verify commission appears
Common issue: missing tracClickId metadata → commission created but no seller attribution

Security & Data